Documentation: more examples.

Signed-off-by: Junio C Hamano <junkio@cox.net>

7 files changed, 209 insertions, 26 deletions

diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
index 88df3ffc2..88bd88963 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/everyday.txt
@@ -50,6 +50,35 @@ Everybody uses these commands to feed and care git repositories.
 
   * gitlink:git-repack[1] to pack loose objects for efficiency.
 
+Examples
+~~~~~~~~
+
+Check health and remove cruft::
++
+------------
+$ git fsck-objects <1>
+$ git prune
+$ git count-objects <2>
+$ git repack <3>
+$ git prune <4>
+
+<1> running without "--full" is usually cheap and assures the
+repository health reasonably well.
+<2> check how many loose objects there are and how much
+diskspace is wasted by not repacking.
+<3> without "-a" repacks incrementally.  repacking every 4-5MB
+of loose objects accumulation may be a good rule of thumb.
+<4> after repack, prune removes the duplicate loose objects.
+------------
+
+Repack a small project into single pack::
++
+------------
+$ git repack -a -d <1>
+$ git prune
+------------
+
+
 Individual Developer (Standalone)[[Individual Developer (Standalone)]]
 ----------------------------------------------------------------------
 
@@ -88,7 +117,8 @@ following commands.
 Examples
 ~~~~~~~~
 
-* Extract a tarball and create a working tree and a new repository to keep track of it.
+Extract a tarball and create a working tree and a new repository to keep track of it::
++
 ------------
 $ tar zxf frotz.tar.gz
 $ cd frotz
@@ -101,7 +131,8 @@ $ git tag v2.43 <2>
 <2> make a lightweight, unannotated tag.
 ------------
 
-* Create a topic branch and develop
+Create a topic branch and develop::
++
 ------------
 $ git checkout -b alsa-audio <1>
 $ edit/compile/test
@@ -158,12 +189,13 @@ addition to the ones needed by a standalone developer.
 Examples
 ~~~~~~~~
 
-* Clone the upstream and work on it.  Feed changes to upstream.
+Clone the upstream and work on it.  Feed changes to upstream::
++
 ------------
 $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
 $ cd my2.6
 $ edit/compile/test; git commit -a -s <1>
-$ git format-patch master <2>
+$ git format-patch origin <2>
 $ git pull <3>
 $ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
 $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
@@ -180,7 +212,8 @@ area we are interested in.
 <7> garbage collect leftover objects from reverted pull.
 ------------
 
-* Branch off of a specific tag.
+Branch off of a specific tag::
++
 ------------
 $ git checkout -b private2.6.14 v2.6.14 <1>
 $ edit/compile/test; git commit -a
@@ -219,7 +252,8 @@ commands in addition to the ones needed by participants.
 Examples
 ~~~~~~~~
 
-* My typical GIT day.
+My typical GIT day::
++
 ------------
 $ git status <1>
 $ git show-branch <2>
@@ -231,16 +265,17 @@ $ git checkout master
 $ git am -3 -i -s -u ./+to-apply <4>
 $ compile/test
 $ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>
-$ git checkout pu && git reset --hard master <6>
-$ git pull . topic/one topic/two && git pull . hold/linus <7>
+$ git checkout topic/one && git rebase master <6>
+$ git checkout pu && git reset --hard master <7>
+$ git pull . topic/one topic/two && git pull . hold/linus <8>
 $ git fetch ko master:refs/tags/ko-master &&
-  git show-branch master ko-master <8>
-$ git push ko <9>
+  git show-branch master ko-master <9>
+$ git push ko <10>
 $ git checkout maint
-$ git cherry-pick master~4 <10>
+$ git cherry-pick master~4 <11>
 $ compile/test
-$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <11>
-$ git push ko v0.99.9x <12>
+$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <12>
+$ git push ko v0.99.9x <13>
 
 <1> see what I was in the middle of doing, if any.
 <2> see what topic branches I have and think about how ready
@@ -250,14 +285,16 @@ that are not quite ready.
 <4> apply them, interactively, with my sign-offs.
 <5> create topic branch as needed and apply, again with my
 sign-offs. 
-<6> restart "pu" every time from the master.
-<7> and bundle topic branches still cooking.
-<8> make sure I did not accidentally rewound master beyond what I
+<6> rebase internal topic branch that has not been merged to the
+master, nor exposed as a part of a stable branch.
+<7> restart "pu" every time from the master.
+<8> and bundle topic branches still cooking.
+<9> make sure I did not accidentally rewound master beyond what I
 already pushed out.
-<9> push out the bleeding edge.
-<10> backport a critical fix.
-<11> create a signed tag.
-<12> push the tag out.
+<10> push out the bleeding edge.
+<11> backport a critical fix.
+<12> create a signed tag.
+<13> push the tag out.
 ------------
 
 
@@ -276,3 +313,25 @@ and maintain access to the repository by developers.
   * link:howto/update-hook-example.txt[update hook howto] has a
     good example of managing a shared central repository.
 
+
+Examples
+~~~~~~~~
+
+Run git-daemon to serve /pub/scm from inetd::
++
+------------
+$ grep git /etc/inet.conf
+git	stream	tcp	nowait	nobody	/usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm
+------------
+
+Give push/pull only access to developers::
++
+------------
+$ grep git /etc/shells
+/usr/bin/git-shell
+$ grep git /etc/passwd
+alice:x:1000:1000::/home/alice:/usr/bin/git-shell
+bob:x:1001:1001::/home/bob:/usr/bin/git-shell
+cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
+david:x:1003:1003::/home/david:/usr/bin/git-shell
+------------
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 6645e82b8..a415fe24c 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -69,7 +69,7 @@ recover from this in one of two ways:
 
 . hand resolve the conflict in the working directory, and update
   the index file to bring it in a state that the patch should
-  have produced.  Then run the command with '--resume' option.
+  have produced.  Then run the command with '--resolved' option.
 
 The command refuses to process new mailboxes while `.dotest`
 directory exists, so if you decide to start over from scratch,
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 98014f6d9..d20b47573 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -32,6 +32,32 @@ start-point::
 	Where to create the branch; defaults to HEAD. This
 	option has no meaning with -d and -D.
 
+
+Examples
+~~~~~~~~
+
+Start development off of a know tag::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
+$ cd my2.6
+$ git branch my2.6.14 v2.6.14 <1>
+$ git checkout my2.6.14
+
+<1> These two steps are the same as "checkout -b my2.6.14 v2.6.14".
+------------
+
+Delete unneeded branch::
++
+------------
+$ git clone git://git.kernel.org/.../git.git my.git
+$ cd my.git
+$ git branch -D todo <1>
+
+<1> delete todo branch even if the "master" branch does not have all
+commits from todo branch.
+------------
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net>
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index b7bb1b4c7..9442c66b1 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -50,10 +50,14 @@ the `Makefile` to two revisions back, deletes hello.c by
 mistake, and gets it back from the index.
 
 ------------
-$ git checkout master
-$ git checkout master~2 Makefile
+$ git checkout master <1>
+$ git checkout master~2 Makefile <2>
 $ rm -f hello.c
-$ git checkout hello.c
+$ git checkout hello.c <3>
+
+<1> switch branch
+<2> take out a file out of other commit
+<3> or "git checkout -- hello.c", as in the next example.
 ------------
 
 If you have an unfortunate branch that is named `hello.c`, the
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 83f58ae53..8410a6d38 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -74,10 +74,31 @@ OPTIONS
 	for "host.xz:foo/.git").  Cloning into an existing directory
 	is not allowed.
 
+Examples
+~~~~~~~~
+
+Clone from upstream::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
+$ cd my2.6
+$ make
+------------
+
+
+Make a local clone that borrows from the current directory, without checking things out::
++
+------------
+$ git clone -l -s -n . ../copy
+$ cd copy
+$ git show-branch
+------------
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>
 
+
 Documentation
 --------------
 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt
index 4486f0c1c..6deef9250 100644
--- a/Documentation/git-init-db.txt
+++ b/Documentation/git-init-db.txt
@@ -40,9 +40,12 @@ Start a new git repository for an existing code base::
 +
 ----------------
 $ cd /path/to/my/codebase
-$ git-init-db
-----------------
+$ git-init-db <1>
+$ git-add . <2>
 
+<1> prepare /path/to/my/codebase/.git directory
+<2> add all existing file to the index
+----------------
 
 
 Author
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 6af3a4fdb..02048918b 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -42,6 +42,76 @@ OPTIONS
 <commit-ish>::
 	Commit to make the current HEAD.
 
+Examples
+~~~~~~~~
+
+Undo a commit and redo::
++
+------------
+$ git commit ...
+$ git reset --soft HEAD^ <1>
+$ edit <2>
+$ git commit -a -c ORIG_HEAD <3>
+
+<1> This is most often done when you remembered what you
+just committed is incomplete, or you misspelled your commit
+message, or both.  Leaves working tree as it was before "reset".
+<2> make corrections to working tree files.
+<3> "reset" copies the old head to .git/ORIG_HEAD; redo the
+commit by starting with its log message.  If you do not need to
+edit the message further, you can give -C option instead.
+------------
+
+Undo commits permanently::
++
+------------
+$ git commit ...
+$ git reset --hard HEAD~3 <1>
+
+<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad
+and you do not want to ever see them again.  Do *not* do this if
+you have already given these commits to somebody else.
+------------
+
+Undo a commit, making it a topic branch::
++
+------------
+$ git branch topic/wip <1>
+$ git reset --hard HEAD~3 <2>
+$ git checkout topic/wip <3>
+
+<1> You have made some commits, but realize they were premature
+to be in the "master" branch.  You want to continue polishing
+them in a topic branch, so create "topic/wip" branch off of the
+current HEAD.
+<2> Rewind the master branch to get rid of those three commits.
+<3> Switch to "topic/wip" branch and keep working.
+------------
+
+Undo update-index::
++
+------------
+$ edit <1>
+$ git-update-index frotz.c filfre.c
+$ mailx <2>
+$ git reset <3>
+$ git pull git://info.example.com/ nitfol <4>
+
+<1> you are happily working on something, and find the changes
+in these files are in good order.  You do not want to see them
+when you run "git diff", because you plan to work on other files
+and changes with these files are distracting.
+<2> somebody asks you to pull, and the changes sounds worthy of merging.
+<3> however, you already dirtied the index (i.e. your index does
+not match the HEAD commit).  But you know the pull you are going
+to make does not affect frotz.c nor filfre.c, so you revert the
+index changes for these two files.  Your changes in working tree
+remain there.
+<4> then you can pull and merge, leaving frotz.c and filfre.c
+changes still in the working tree.
+------------
+
+
 Author
 ------
 Written by Junio C Hamano <junkio@cox.net> and Linus Torvalds <torvalds@osdl.org>