Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> I agree with you that sightseeing use case where you do not intend
> to make any commit is also important.  That is exactly why I said
> "further work is done on that branch" not "to that branch" in the
> message you are responding to.

Here is a work-in-progress relative to Chris's 83c9989
(Documentation/git-checkout.txt: document 70c9ac2 behavior,
2012-12-17).

Even though "switch to that specific branch" may be easy to grasp as
a concept, I do not think "switch to detached HEAD" makes much
sense, so I ended up with "switch" for the <branch> case, and
"detach" for the "--detach" one, at least for now.

diff --git c/Documentation/git-checkout.txt w/Documentation/git-checkout.txt
index db89cf7..dcf1a32 100644
--- c/Documentation/git-checkout.txt
+++ w/Documentation/git-checkout.txt
@@ -21,10 +21,12 @@ or the specified tree.  If no paths are given, 'git checkout' will
 also update `HEAD` to set the specified branch as the current
 branch.
 
-'git checkout' [<branch>]::
-
-	Update the index, working tree, and HEAD to reflect the
-	specified branch.
+'git checkout' <branch>::
+	To prepare for working on <branch>, switch to it by updating
+	the index and the files in the working tree, and by pointing
+	HEAD at the branch. Local modifications to the files in the
+	working tree are kept, so that they can be committed to the
+	<branch>.
 +
 If <branch> is not found but there does exist a tracking branch in
 exactly one remote (call it <remote>) with a matching name, treat as
@@ -33,6 +35,11 @@ equivalent to
 ------------
 $ git checkout -b <branch> --track <remote>/<branch>
 ------------
++
+You could omit <branch>, in which case the command degenerates to
+"check out the current branch", which is a glorified no-op with a
+rather expensive side-effects to show only the tracking information,
+if exists, for the current branch.
 
 'git checkout' -b|-B <new_branch> [<start point>]::
 
@@ -54,12 +61,17 @@ $ git checkout <branch>
 that is to say, the branch is not reset/created unless "git checkout" is
 successful.
 
-'git checkout' [--detach] [<commit>]::
+'git checkout' --detach [<commit>]::
+'git checkout' <commit>::
 
-	Update the index and working tree to reflect the specified
-	commit and set HEAD to point directly to <commit> (see
-	"DETACHED HEAD" section.)  Passing `--detach` forces this
-	behavior even if <commit> is a branch.
+	Prepare to work on top of <commit>, by detaching HEAD at it
+	(see "DETACHED HEAD" section), and updating the index and the
+	files in the working tree.  Local modifications to the files
+	in the working tree are kept, so that the resulting working
+	tree will be the state recorded in the commit plus the local
+	modifications.
++
+Passing `--detach` forces this behavior even if <commit> is a branch.
 
 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::