everyday: use the dashless form of git-init
[git/git.git] / Documentation / everyday.txt
CommitLineData
db9536c8
JH
1Everyday GIT With 20 Commands Or So
2===================================
3
119550af 4<<Basic Repository>> commands are needed by people who have a
db9536c8
JH
5repository --- that is everybody, because every working tree of
6git is a repository.
7
8In addition, <<Individual Developer (Standalone)>> commands are
9essential for anybody who makes a commit, even for somebody who
10works alone.
11
12If you work with other people, you will need commands listed in
119550af 13the <<Individual Developer (Participant)>> section as well.
db9536c8 14
119550af 15People who play the <<Integrator>> role need to learn some more
db9536c8
JH
16commands in addition to the above.
17
18<<Repository Administration>> commands are for system
119550af
BF
19administrators who are responsible for the care and feeding
20of git repositories.
db9536c8
JH
21
22
23Basic Repository[[Basic Repository]]
24------------------------------------
25
119550af 26Everybody uses these commands to maintain git repositories.
db9536c8 27
5162e697 28 * linkgit:git-init[1] or linkgit:git-clone[1] to create a
db9536c8
JH
29 new repository.
30
5162e697 31 * linkgit:git-fsck[1] to check the repository for errors.
db9536c8 32
5162e697 33 * linkgit:git-gc[1] to do common housekeeping tasks such as
8f57b0a0
JH
34 repack and prune.
35
1e2ccd3a
JH
36Examples
37~~~~~~~~
38
01f49e34 39Check health and remove cruft.::
1e2ccd3a
JH
40+
41------------
df391b19 42$ git fsck <1>
1e2ccd3a 43$ git count-objects <2>
8a82b133 44$ git gc <3>
48aeecdc
SE
45------------
46+
268b827d 47<1> running without `\--full` is usually cheap and assures the
1e2ccd3a
JH
48repository health reasonably well.
49<2> check how many loose objects there are and how much
7872b188 50disk space is wasted by not repacking.
208641cf 51<3> repacks the local repository and performs other housekeeping tasks.
1e2ccd3a 52
01f49e34 53Repack a small project into single pack.::
1e2ccd3a
JH
54+
55------------
8a82b133 56$ git gc <1>
48aeecdc
SE
57------------
58+
119550af
BF
59<1> pack all the objects reachable from the refs into one pack,
60then remove the other packs.
1e2ccd3a
JH
61
62
db9536c8
JH
63Individual Developer (Standalone)[[Individual Developer (Standalone)]]
64----------------------------------------------------------------------
65
66A standalone individual developer does not exchange patches with
7872b188 67other people, and works alone in a single repository, using the
db9536c8
JH
68following commands.
69
5162e697 70 * linkgit:git-show-branch[1] to see where you are.
db9536c8 71
5162e697 72 * linkgit:git-log[1] to see what happened.
db9536c8 73
5162e697 74 * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch
db9536c8
JH
75 branches.
76
5162e697 77 * linkgit:git-add[1] to manage the index file.
44db136c 78
5162e697 79 * linkgit:git-diff[1] and linkgit:git-status[1] to see what
44db136c 80 you are in the middle of doing.
db9536c8 81
5162e697 82 * linkgit:git-commit[1] to advance the current branch.
db9536c8 83
5162e697 84 * linkgit:git-reset[1] and linkgit:git-checkout[1] (with
db9536c8
JH
85 pathname parameters) to undo changes.
86
5162e697 87 * linkgit:git-merge[1] to merge between local branches.
db9536c8 88
5162e697 89 * linkgit:git-rebase[1] to maintain topic branches.
db9536c8 90
5162e697 91 * linkgit:git-tag[1] to mark known point.
db9536c8 92
44db136c
JH
93Examples
94~~~~~~~~
95
268b827d 96Use a tarball as a starting point for a new repository.::
1e2ccd3a 97+
44db136c
JH
98------------
99$ tar zxf frotz.tar.gz
100$ cd frotz
3e5970a4 101$ git init
180c4746 102$ git add . <1>
d336fc09 103$ git commit -m "import of frotz source tree."
180c4746 104$ git tag v2.43 <2>
48aeecdc
SE
105------------
106+
180c4746
JH
107<1> add everything under the current directory.
108<2> make a lightweight, unannotated tag.
44db136c 109
01f49e34 110Create a topic branch and develop.::
1e2ccd3a 111+
44db136c 112------------
180c4746
JH
113$ git checkout -b alsa-audio <1>
114$ edit/compile/test
115$ git checkout -- curses/ux_audio_oss.c <2>
116$ git add curses/ux_audio_alsa.c <3>
117$ edit/compile/test
268b827d 118$ git diff HEAD <4>
180c4746 119$ git commit -a -s <5>
44db136c 120$ edit/compile/test
180c4746 121$ git reset --soft HEAD^ <6>
44db136c 122$ edit/compile/test
180c4746
JH
123$ git diff ORIG_HEAD <7>
124$ git commit -a -c ORIG_HEAD <8>
125$ git checkout master <9>
268b827d 126$ git merge alsa-audio <10>
180c4746
JH
127$ git log --since='3 days ago' <11>
128$ git log v2.43.. curses/ <12>
48aeecdc
SE
129------------
130+
180c4746 131<1> create a new topic branch.
268b827d 132<2> revert your botched changes in `curses/ux_audio_oss.c`.
180c4746 133<3> you need to tell git if you added a new file; removal and
268b827d 134modification will be caught if you do `git commit -a` later.
180c4746
JH
135<4> to see what changes you are committing.
136<5> commit everything as you have tested, with your sign-off.
137<6> take the last commit back, keeping what is in the working tree.
138<7> look at the changes since the premature commit we took back.
139<8> redo the commit undone in the previous step, using the message
140you originally wrote.
141<9> switch to the master branch.
c14261ea 142<10> merge a topic branch into your master branch.
01f49e34 143<11> review commit logs; other forms to limit output can be
268b827d
JH
144combined and include `\--max-count=10` (show 10 commits),
145`\--until=2005-12-10`, etc.
146<12> view only the changes that touch what's in `curses/`
147directory, since `v2.43` tag.
44db136c
JH
148
149
db9536c8
JH
150Individual Developer (Participant)[[Individual Developer (Participant)]]
151------------------------------------------------------------------------
152
153A developer working as a participant in a group project needs to
154learn how to communicate with others, and uses these commands in
155addition to the ones needed by a standalone developer.
156
5162e697 157 * linkgit:git-clone[1] from the upstream to prime your local
01f49e34
JH
158 repository.
159
5162e697 160 * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin"
01f49e34 161 to keep up-to-date with the upstream.
db9536c8 162
5162e697 163 * linkgit:git-push[1] to shared repository, if you adopt CVS
db9536c8
JH
164 style shared repository workflow.
165
5162e697 166 * linkgit:git-format-patch[1] to prepare e-mail submission, if
db9536c8
JH
167 you adopt Linux kernel-style public forum workflow.
168
44db136c
JH
169Examples
170~~~~~~~~
171
01f49e34 172Clone the upstream and work on it. Feed changes to upstream.::
1e2ccd3a 173+
44db136c
JH
174------------
175$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
176$ cd my2.6
177$ edit/compile/test; git commit -a -s <1>
1e2ccd3a 178$ git format-patch origin <2>
44db136c 179$ git pull <3>
119550af 180$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
180c4746
JH
181$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
182$ git reset --hard ORIG_HEAD <6>
208641cf 183$ git gc <7>
01f49e34 184$ git fetch --tags <8>
48aeecdc
SE
185------------
186+
44db136c
JH
187<1> repeat as needed.
188<2> extract patches from your branch for e-mail submission.
268b827d 189<3> `git pull` fetches from `origin` by default and merges into the
d808111e
JH
190current branch.
191<4> immediately after pulling, look at the changes done upstream
192since last time we checked, only in the
180c4746 193area we are interested in.
d808111e 194<5> fetch from a specific branch from a specific repository and merge.
180c4746
JH
195<6> revert the pull.
196<7> garbage collect leftover objects from reverted pull.
268b827d
JH
197<8> from time to time, obtain official tags from the `origin`
198and store them under `.git/refs/tags/`.
01f49e34
JH
199
200
201Push into another repository.::
202+
203------------
268b827d 204satellite$ git clone mothership:frotz frotz <1>
01f49e34 205satellite$ cd frotz
e0d10e1c 206satellite$ git config --get-regexp '^(remote|branch)\.' <2>
268b827d
JH
207remote.origin.url mothership:frotz
208remote.origin.fetch refs/heads/*:refs/remotes/origin/*
209branch.master.remote origin
210branch.master.merge refs/heads/master
e0d10e1c 211satellite$ git config remote.origin.push \
268b827d 212 master:refs/remotes/satellite/master <3>
01f49e34
JH
213satellite$ edit/compile/test/commit
214satellite$ git push origin <4>
215
216mothership$ cd frotz
217mothership$ git checkout master
268b827d 218mothership$ git merge satellite/master <5>
48aeecdc
SE
219------------
220+
01f49e34
JH
221<1> mothership machine has a frotz repository under your home
222directory; clone from it to start a repository on the satellite
223machine.
268b827d
JH
224<2> clone sets these configuration variables by default.
225It arranges `git pull` to fetch and store the branches of mothership
226machine to local `remotes/origin/*` tracking branches.
227<3> arrange `git push` to push local `master` branch to
228`remotes/satellite/master` branch of the mothership machine.
229<4> push will stash our work away on `remotes/satellite/master`
230tracking branch on the mothership machine. You could use this as
231a back-up method.
01f49e34
JH
232<5> on mothership machine, merge the work done on the satellite
233machine into the master branch.
44db136c 234
01f49e34 235Branch off of a specific tag.::
1e2ccd3a 236+
44db136c
JH
237------------
238$ git checkout -b private2.6.14 v2.6.14 <1>
239$ edit/compile/test; git commit -a
240$ git checkout master
241$ git format-patch -k -m --stdout v2.6.14..private2.6.14 |
242 git am -3 -k <2>
48aeecdc
SE
243------------
244+
44db136c
JH
245<1> create a private branch based on a well known (but somewhat behind)
246tag.
268b827d 247<2> forward port all changes in `private2.6.14` branch to `master` branch
180c4746 248without a formal "merging".
44db136c
JH
249
250
db9536c8
JH
251Integrator[[Integrator]]
252------------------------
253
254A fairly central person acting as the integrator in a group
255project receives changes made by others, reviews and integrates
256them and publishes the result for others to use, using these
257commands in addition to the ones needed by participants.
258
5162e697 259 * linkgit:git-am[1] to apply patches e-mailed in from your
db9536c8
JH
260 contributors.
261
5162e697 262 * linkgit:git-pull[1] to merge from your trusted lieutenants.
db9536c8 263
5162e697 264 * linkgit:git-format-patch[1] to prepare and send suggested
db9536c8
JH
265 alternative to contributors.
266
5162e697 267 * linkgit:git-revert[1] to undo botched commits.
db9536c8 268
5162e697 269 * linkgit:git-push[1] to publish the bleeding edge.
db9536c8
JH
270
271
180c4746
JH
272Examples
273~~~~~~~~
274
01f49e34 275My typical GIT day.::
1e2ccd3a 276+
180c4746
JH
277------------
278$ git status <1>
279$ git show-branch <2>
280$ mailx <3>
281& s 2 3 4 5 ./+to-apply
282& s 7 8 ./+hold-linus
283& q
268b827d 284$ git checkout -b topic/one master
180c4746
JH
285$ git am -3 -i -s -u ./+to-apply <4>
286$ compile/test
287$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>
1e2ccd3a 288$ git checkout topic/one && git rebase master <6>
268b827d
JH
289$ git checkout pu && git reset --hard next <7>
290$ git merge topic/one topic/two && git merge hold/linus <8>
180c4746 291$ git checkout maint
01f49e34 292$ git cherry-pick master~4 <9>
180c4746 293$ compile/test
d336fc09 294$ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>
01f49e34
JH
295$ git fetch ko && git show-branch master maint 'tags/ko-*' <11>
296$ git push ko <12>
1e2ccd3a 297$ git push ko v0.99.9x <13>
48aeecdc
SE
298------------
299+
180c4746
JH
300<1> see what I was in the middle of doing, if any.
301<2> see what topic branches I have and think about how ready
302they are.
303<3> read mails, save ones that are applicable, and save others
304that are not quite ready.
305<4> apply them, interactively, with my sign-offs.
306<5> create topic branch as needed and apply, again with my
268b827d 307sign-offs.
1e2ccd3a
JH
308<6> rebase internal topic branch that has not been merged to the
309master, nor exposed as a part of a stable branch.
268b827d 310<7> restart `pu` every time from the next.
1e2ccd3a 311<8> and bundle topic branches still cooking.
01f49e34
JH
312<9> backport a critical fix.
313<10> create a signed tag.
d808111e 314<11> make sure I did not accidentally rewind master beyond what I
268b827d 315already pushed out. `ko` shorthand points at the repository I have
01f49e34 316at kernel.org, and looks like this:
53bcf78a
HB
317+
318------------
319$ cat .git/remotes/ko
320URL: kernel.org:/pub/scm/git/git.git
321Pull: master:refs/tags/ko-master
268b827d 322Pull: next:refs/tags/ko-next
53bcf78a
HB
323Pull: maint:refs/tags/ko-maint
324Push: master
268b827d 325Push: next
53bcf78a
HB
326Push: +pu
327Push: maint
328------------
329+
268b827d
JH
330In the output from `git show-branch`, `master` should have
331everything `ko-master` has, and `next` should have
332everything `ko-next` has.
53bcf78a 333
01f49e34
JH
334<12> push out the bleeding edge.
335<13> push the tag out, too.
180c4746
JH
336
337
db9536c8
JH
338Repository Administration[[Repository Administration]]
339------------------------------------------------------
340
341A repository administrator uses the following tools to set up
342and maintain access to the repository by developers.
343
5162e697 344 * linkgit:git-daemon[1] to allow anonymous download from
db9536c8
JH
345 repository.
346
5162e697 347 * linkgit:git-shell[1] can be used as a 'restricted login shell'
db9536c8
JH
348 for shared central repository users.
349
d808111e
JH
350link:howto/update-hook-example.txt[update hook howto] has a good
351example of managing a shared central repository.
db9536c8 352
1e2ccd3a
JH
353
354Examples
355~~~~~~~~
f8a5da6d
CC
356We assume the following in /etc/services::
357+
358------------
359$ grep 9418 /etc/services
360git 9418/tcp # Git Version Control System
361------------
362
01f49e34 363Run git-daemon to serve /pub/scm from inetd.::
1e2ccd3a
JH
364+
365------------
7872b188 366$ grep git /etc/inetd.conf
01f49e34 367git stream tcp nowait nobody \
d9c04ba3 368 /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm
1e2ccd3a 369------------
01f49e34
JH
370+
371The actual configuration line should be on one line.
1e2ccd3a 372
c51901de
HB
373Run git-daemon to serve /pub/scm from xinetd.::
374+
375------------
376$ cat /etc/xinetd.d/git-daemon
377# default: off
378# description: The git server offers access to git repositories
379service git
380{
381 disable = no
382 type = UNLISTED
383 port = 9418
384 socket_type = stream
385 wait = no
386 user = nobody
387 server = /usr/bin/git-daemon
d9c04ba3 388 server_args = --inetd --export-all --base-path=/pub/scm
c51901de
HB
389 log_on_failure += USERID
390}
391------------
392+
393Check your xinetd(8) documentation and setup, this is from a Fedora system.
394Others might be different.
395
01f49e34 396Give push/pull only access to developers.::
1e2ccd3a
JH
397+
398------------
01f49e34 399$ grep git /etc/passwd <1>
1e2ccd3a
JH
400alice:x:1000:1000::/home/alice:/usr/bin/git-shell
401bob:x:1001:1001::/home/bob:/usr/bin/git-shell
402cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
403david:x:1003:1003::/home/david:/usr/bin/git-shell
01f49e34
JH
404$ grep git /etc/shells <2>
405/usr/bin/git-shell
48aeecdc
SE
406------------
407+
01f49e34 408<1> log-in shell is set to /usr/bin/git-shell, which does not
268b827d 409allow anything but `git push` and `git pull`. The users should
01f49e34
JH
410get an ssh access to the machine.
411<2> in many distributions /etc/shells needs to list what is used
412as the login shell.
01f49e34
JH
413
414CVS-style shared repository.::
415+
416------------
417$ grep git /etc/group <1>
418git:x:9418:alice,bob,cindy,david
419$ cd /home/devo.git
420$ ls -l <2>
421 lrwxrwxrwx 1 david git 17 Dec 4 22:40 HEAD -> refs/heads/master
422 drwxrwsr-x 2 david git 4096 Dec 4 22:40 branches
423 -rw-rw-r-- 1 david git 84 Dec 4 22:40 config
424 -rw-rw-r-- 1 david git 58 Dec 4 22:40 description
425 drwxrwsr-x 2 david git 4096 Dec 4 22:40 hooks
426 -rw-rw-r-- 1 david git 37504 Dec 4 22:40 index
427 drwxrwsr-x 2 david git 4096 Dec 4 22:40 info
428 drwxrwsr-x 4 david git 4096 Dec 4 22:40 objects
429 drwxrwsr-x 4 david git 4096 Nov 7 14:58 refs
430 drwxrwsr-x 2 david git 4096 Dec 4 22:40 remotes
431$ ls -l hooks/update <3>
432 -r-xr-xr-x 1 david git 3536 Dec 4 22:40 update
433$ cat info/allowed-users <4>
434refs/heads/master alice\|cindy
435refs/heads/doc-update bob
436refs/tags/v[0-9]* david
48aeecdc
SE
437------------
438+
01f49e34
JH
439<1> place the developers into the same git group.
440<2> and make the shared repository writable by the group.
441<3> use update-hook example by Carl from Documentation/howto/
442for branch policy control.
443<4> alice and cindy can push into master, only bob can push into doc-update.
444david is the release manager and is the only person who can
445create and push version tags.
80248b2e
JH
446
447HTTP server to support dumb protocol transfer.::
448+
449------------
450dev$ git update-server-info <1>
451dev$ ftp user@isp.example.com <2>
452ftp> cp -r .git /home/user/myproject.git
48aeecdc
SE
453------------
454+
80248b2e
JH
455<1> make sure your info/refs and objects/info/packs are up-to-date
456<2> upload to public HTTP server hosted by your ISP.