Documentation: more examples.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Dec 12, 2005 at 23:24 UTC
1e2ccd3abc8f5d96244806f753568493c3e77d4c
7 files changed
+209
-26
Documentation/everyday.txt
+79
-20
@@ -50,6 +50,35 @@ Everybody uses these commands to feed and care git repositories.
50
51
* gitlink:git-repack[1] to pack loose objects for efficiency.
52
53
+Examples
54
+~~~~~~~~
55
+
56
+Check health and remove cruft::
57
++
58
+------------
59
+$ git fsck-objects <1>
60
+$ git prune
61
+$ git count-objects <2>
62
+$ git repack <3>
63
+$ git prune <4>
64
+
65
+<1> running without "--full" is usually cheap and assures the
66
+repository health reasonably well.
67
+<2> check how many loose objects there are and how much
68
+diskspace is wasted by not repacking.
69
+<3> without "-a" repacks incrementally. repacking every 4-5MB
70
+of loose objects accumulation may be a good rule of thumb.
71
+<4> after repack, prune removes the duplicate loose objects.
72
+------------
73
+
74
+Repack a small project into single pack::
75
++
76
+------------
77
+$ git repack -a -d <1>
78
+$ git prune
79
+------------
80
+
81
+
82
Individual Developer (Standalone)[[Individual Developer (Standalone)]]
83
----------------------------------------------------------------------
84
@@ -88,7 +117,8 @@ following commands.
117
Examples
118
~~~~~~~~
119
91
-* Extract a tarball and create a working tree and a new repository to keep track of it.
120
+Extract a tarball and create a working tree and a new repository to keep track of it::
121
++
122
------------
123
$ tar zxf frotz.tar.gz
124
$ cd frotz
@@ -101,7 +131,8 @@ $ git tag v2.43 <2>
131
<2> make a lightweight, unannotated tag.
132
------------
133
104
-* Create a topic branch and develop
134
+Create a topic branch and develop::
135
++
136
------------
137
$ git checkout -b alsa-audio <1>
138
$ edit/compile/test
@@ -158,12 +189,13 @@ addition to the ones needed by a standalone developer.
189
Examples
190
~~~~~~~~
191
161
-* Clone the upstream and work on it. Feed changes to upstream.
192
+Clone the upstream and work on it. Feed changes to upstream::
193
++
194
------------
195
$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
196
$ cd my2.6
197
$ edit/compile/test; git commit -a -s <1>
166
-$ git format-patch master <2>
198
+$ git format-patch origin <2>
199
$ git pull <3>
200
$ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
201
$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
@@ -180,7 +212,8 @@ area we are interested in.
212
<7> garbage collect leftover objects from reverted pull.
213
------------
214
183
-* Branch off of a specific tag.
215
+Branch off of a specific tag::
216
++
217
------------
218
$ git checkout -b private2.6.14 v2.6.14 <1>
219
$ edit/compile/test; git commit -a
@@ -219,7 +252,8 @@ commands in addition to the ones needed by participants.
252
Examples
253
~~~~~~~~
254
222
-* My typical GIT day.
255
+My typical GIT day::
256
++
257
------------
258
$ git status <1>
259
$ git show-branch <2>
@@ -231,16 +265,17 @@ $ git checkout master
265
$ git am -3 -i -s -u ./+to-apply <4>
266
$ compile/test
267
$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>
234
-$ git checkout pu && git reset --hard master <6>
235
-$ git pull . topic/one topic/two && git pull . hold/linus <7>
268
+$ git checkout topic/one && git rebase master <6>
269
+$ git checkout pu && git reset --hard master <7>
270
+$ git pull . topic/one topic/two && git pull . hold/linus <8>
271
$ git fetch ko master:refs/tags/ko-master &&
237
- git show-branch master ko-master <8>
238
-$ git push ko <9>
272
+ git show-branch master ko-master <9>
273
+$ git push ko <10>
274
$ git checkout maint
240
-$ git cherry-pick master~4 <10>
275
+$ git cherry-pick master~4 <11>
276
$ compile/test
242
-$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <11>
243
-$ git push ko v0.99.9x <12>
277
+$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <12>
278
+$ git push ko v0.99.9x <13>
279
280
<1> see what I was in the middle of doing, if any.
281
<2> see what topic branches I have and think about how ready
@@ -250,14 +285,16 @@ that are not quite ready.
285
<4> apply them, interactively, with my sign-offs.
286
<5> create topic branch as needed and apply, again with my
287
sign-offs.
253
-<6> restart "pu" every time from the master.
254
-<7> and bundle topic branches still cooking.
255
-<8> make sure I did not accidentally rewound master beyond what I
288
+<6> rebase internal topic branch that has not been merged to the
289
+master, nor exposed as a part of a stable branch.
290
+<7> restart "pu" every time from the master.
291
+<8> and bundle topic branches still cooking.
292
+<9> make sure I did not accidentally rewound master beyond what I
293
already pushed out.
257
-<9> push out the bleeding edge.
258
-<10> backport a critical fix.
259
-<11> create a signed tag.
260
-<12> push the tag out.
294
+<10> push out the bleeding edge.
295
+<11> backport a critical fix.
296
+<12> create a signed tag.
297
+<13> push the tag out.
298
------------
299
300
@@ -276,3 +313,25 @@ and maintain access to the repository by developers.
313
* link:howto/update-hook-example.txt[update hook howto] has a
314
good example of managing a shared central repository.
315
316
+
317
+Examples
318
+~~~~~~~~
319
+
320
+Run git-daemon to serve /pub/scm from inetd::
321
++
322
+------------
323
+$ grep git /etc/inet.conf
324
+git stream tcp nowait nobody /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm
325
+------------
326
+
327
+Give push/pull only access to developers::
328
++
329
+------------
330
+$ grep git /etc/shells
331
+/usr/bin/git-shell
332
+$ grep git /etc/passwd
333
+alice:x:1000:1000::/home/alice:/usr/bin/git-shell
334
+bob:x:1001:1001::/home/bob:/usr/bin/git-shell
335
+cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
336
+david:x:1003:1003::/home/david:/usr/bin/git-shell
337
+------------
Documentation/git-am.txt
+1
-1
@@ -69,7 +69,7 @@ recover from this in one of two ways:
69
70
. hand resolve the conflict in the working directory, and update
71
the index file to bring it in a state that the patch should
72
- have produced. Then run the command with '--resume' option.
72
+ have produced. Then run the command with '--resolved' option.
73
74
The command refuses to process new mailboxes while `.dotest`
75
directory exists, so if you decide to start over from scratch,
Documentation/git-branch.txt
+26
@@ -32,6 +32,32 @@ start-point::
32
Where to create the branch; defaults to HEAD. This
33
option has no meaning with -d and -D.
34
35
+
36
+Examples
37
+~~~~~~~~
38
+
39
+Start development off of a know tag::
40
++
41
+------------
42
+$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
43
+$ cd my2.6
44
+$ git branch my2.6.14 v2.6.14 <1>
45
+$ git checkout my2.6.14
46
+
47
+<1> These two steps are the same as "checkout -b my2.6.14 v2.6.14".
48
+------------
49
+
50
+Delete unneeded branch::
51
++
52
+------------
53
+$ git clone git://git.kernel.org/.../git.git my.git
54
+$ cd my.git
55
+$ git branch -D todo <1>
56
+
57
+<1> delete todo branch even if the "master" branch does not have all
58
+commits from todo branch.
59
+------------
60
+
61
Author
62
------
63
Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net>
Documentation/git-checkout.txt
+7
-3
@@ -50,10 +50,14 @@ the `Makefile` to two revisions back, deletes hello.c by
50
mistake, and gets it back from the index.
51
52
------------
53
-$ git checkout master
54
-$ git checkout master~2 Makefile
53
+$ git checkout master <1>
54
+$ git checkout master~2 Makefile <2>
55
$ rm -f hello.c
56
-$ git checkout hello.c
56
+$ git checkout hello.c <3>
57
+
58
+<1> switch branch
59
+<2> take out a file out of other commit
60
+<3> or "git checkout -- hello.c", as in the next example.
61
------------
62
63
If you have an unfortunate branch that is named `hello.c`, the
Documentation/git-clone.txt
+21
@@ -74,10 +74,31 @@ OPTIONS
74
for "host.xz:foo/.git"). Cloning into an existing directory
75
is not allowed.
76
77
+Examples
78
+~~~~~~~~
79
+
80
+Clone from upstream::
81
++
82
+------------
83
+$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
84
+$ cd my2.6
85
+$ make
86
+------------
87
+
88
+
89
+Make a local clone that borrows from the current directory, without checking things out::
90
++
91
+------------
92
+$ git clone -l -s -n . ../copy
93
+$ cd copy
94
+$ git show-branch
95
+------------
96
+
97
Author
98
------
99
Written by Linus Torvalds <torvalds@osdl.org>
100
101
+
102
Documentation
103
--------------
104
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
Documentation/git-init-db.txt
+5
-2
@@ -40,9 +40,12 @@ Start a new git repository for an existing code base::
40
+
41
----------------
42
$ cd /path/to/my/codebase
43
-$ git-init-db
44
-----------------
43
+$ git-init-db <1>
44
+$ git-add . <2>
45
46
+<1> prepare /path/to/my/codebase/.git directory
47
+<2> add all existing file to the index
48
+----------------
49
50
51
Author
Documentation/git-reset.txt
+70
@@ -42,6 +42,76 @@ OPTIONS
42
<commit-ish>::
43
Commit to make the current HEAD.
44
45
+Examples
46
+~~~~~~~~
47
+
48
+Undo a commit and redo::
49
++
50
+------------
51
+$ git commit ...
52
+$ git reset --soft HEAD^ <1>
53
+$ edit <2>
54
+$ git commit -a -c ORIG_HEAD <3>
55
+
56
+<1> This is most often done when you remembered what you
57
+just committed is incomplete, or you misspelled your commit
58
+message, or both. Leaves working tree as it was before "reset".
59
+<2> make corrections to working tree files.
60
+<3> "reset" copies the old head to .git/ORIG_HEAD; redo the
61
+commit by starting with its log message. If you do not need to
62
+edit the message further, you can give -C option instead.
63
+------------
64
+
65
+Undo commits permanently::
66
++
67
+------------
68
+$ git commit ...
69
+$ git reset --hard HEAD~3 <1>
70
+
71
+<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad
72
+and you do not want to ever see them again. Do *not* do this if
73
+you have already given these commits to somebody else.
74
+------------
75
+
76
+Undo a commit, making it a topic branch::
77
++
78
+------------
79
+$ git branch topic/wip <1>
80
+$ git reset --hard HEAD~3 <2>
81
+$ git checkout topic/wip <3>
82
+
83
+<1> You have made some commits, but realize they were premature
84
+to be in the "master" branch. You want to continue polishing
85
+them in a topic branch, so create "topic/wip" branch off of the
86
+current HEAD.
87
+<2> Rewind the master branch to get rid of those three commits.
88
+<3> Switch to "topic/wip" branch and keep working.
89
+------------
90
+
91
+Undo update-index::
92
++
93
+------------
94
+$ edit <1>
95
+$ git-update-index frotz.c filfre.c
96
+$ mailx <2>
97
+$ git reset <3>
98
+$ git pull git://info.example.com/ nitfol <4>
99
+
100
+<1> you are happily working on something, and find the changes
101
+in these files are in good order. You do not want to see them
102
+when you run "git diff", because you plan to work on other files
103
+and changes with these files are distracting.
104
+<2> somebody asks you to pull, and the changes sounds worthy of merging.
105
+<3> however, you already dirtied the index (i.e. your index does
106
+not match the HEAD commit). But you know the pull you are going
107
+to make does not affect frotz.c nor filfre.c, so you revert the
108
+index changes for these two files. Your changes in working tree
109
+remain there.
110
+<4> then you can pull and merge, leaving frotz.c and filfre.c
111
+changes still in the working tree.
112
+------------
113
+
114
+
115
Author
116
------
117
Written by Junio C Hamano <junkio@cox.net> and Linus Torvalds <torvalds@osdl.org>