Documentation/git-checkout.txt: clarify usage

The forms of checkout that do not take a path are lumped together in
the DESCRIPTION section, but the description for this group is
dominated by explanation of the -b|-B form.

Split these apart for more clarity.

Signed-off-by: Chris Rorvick <chris@rorvick.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 7958a4700642270ad3f801e314cf870331cf4512..ad33eb49ae79dd3d100b5512a696635957be1af3 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -21,18 +21,26 @@ 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>]::
+'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>.
++
+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>]::
-'git checkout' [--detach] [<commit>]::
 
-       This form switches branches by updating the index, working
-       tree, and HEAD to reflect the specified branch or commit.
-+
-If `-b` is given, a new branch is created as if linkgit:git-branch[1]
-were called and then checked out; in this case you can
-use the `--track` or `--no-track` options, which will be passed to
-'git branch'.  As a convenience, `--track` without `-b` implies branch
-creation; see the description of `--track` below.
+       Specifying `-b` causes a new branch to be created as if
+       linkgit:git-branch[1] were called and then checked out.  In
+       this case you can use the `--track` or `--no-track` options,
+       which will be passed to 'git branch'.  As a convenience,
+       `--track` without `-b` implies branch creation; see the
+       description of `--track` below.
 +
 If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it
 is reset. This is the transactional equivalent of
@@ -45,6 +53,21 @@ $ git checkout <branch>
 that is to say, the branch is not reset/created unless "git checkout" is
 successful.
 
+'git checkout' --detach [<branch>]::
+'git checkout' <commit>::
+
+       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 in the case of a <branch> (without
+the option, giving a branch name to the command would check out the branch,
+instead of detaching HEAD at it), or the current commit,
+if no <branch> is specified.
+
 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
 
        When <paths> or `--patch` are given, 'git checkout' does *not*