Documentation/checkout: clarify description

To the first-time reader, it may not be obvious that ‘git checkout’
has two modes, nor that if no branch is specified it will read
from the index.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 37c1810e3fc8424868333a22094107e99764fc37..acbc2d53ed237db10fcb8dc918d275505a310e72 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -15,26 +15,32 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
 
 DESCRIPTION
 -----------

+Retrieves files from the index or specified tree and writes them
+to the working tree.

 
 

-When <paths> are not given, this command switches branches by
-updating the index, working tree, and HEAD to reflect the specified
-branch.
+'git checkout' [-b <new branch>] [<branch>]::

 
 

+       When <paths> are not given, this command switches branches by
+       updating the index, working tree, and HEAD to reflect the
+       specified branch.
++

 If `-b` is given, a new branch is created and checked out, as if
 linkgit:git-branch[1] were called; 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, a new branch is created and checked out, as if
 linkgit:git-branch[1] were called; 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.
 

-When <paths> or --patch are given, this command does *not* switch
-branches.  It updates the named paths in the working tree from
-the index file, or from a named <tree-ish> (most often a commit).  In
-this case, the `-b` and `--track` options are meaningless and giving
-either of them results in an error. The <tree-ish> argument can be
-used to specify a specific tree-ish (i.e. commit, tag or tree)
-to update the index for the given paths before updating the
-working tree.
+'git checkout' [--patch] [<tree-ish>] [--] [<pathspec>...]::

 
 

+       When <paths> or --patch are given, this command does *not* switch
+       branches.  It updates the named paths in the working tree from
+       the index file, or from a named <tree-ish> (most often a commit).  In
+       this case, the `-b` and `--track` options are meaningless and giving
+       either of them results in an error. The <tree-ish> argument can be
+       used to specify a specific tree-ish (i.e. commit, tag or tree)
+       to update the index for the given paths before updating the
+       working tree.
++

 The index may contain unmerged entries after a failed merge.  By
 default, if you try to check out such an entry from the index, the
 checkout operation will fail and nothing will be checked out.
 The index may contain unmerged entries after a failed merge.  By
 default, if you try to check out such an entry from the index, the
 checkout operation will fail and nothing will be checked out.