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>
Jonathan Nieder committed
May 30, 2010 at 03:41 UTC
c5b41519c723ec1966e5f2d6326862095bfa7bb8
1 file changed
+17
-11
Documentation/git-checkout.txt
+17
-11
@@ -15,26 +15,32 @@ SYNOPSIS
15
16
DESCRIPTION
17
-----------
18
+Retrieves files from the index or specified tree and writes them
19
+to the working tree.
20
19
-When <paths> are not given, this command switches branches by
20
-updating the index, working tree, and HEAD to reflect the specified
21
-branch.
21
+'git checkout' [-b <new branch>] [<branch>]::
22
23
+ When <paths> are not given, this command switches branches by
24
+ updating the index, working tree, and HEAD to reflect the
25
+ specified branch.
26
++
27
If `-b` is given, a new branch is created and checked out, as if
28
linkgit:git-branch[1] were called; in this case you can
29
use the --track or --no-track options, which will be passed to `git
30
branch`. As a convenience, --track without `-b` implies branch
31
creation; see the description of --track below.
32
29
-When <paths> or --patch are given, this command does *not* switch
30
-branches. It updates the named paths in the working tree from
31
-the index file, or from a named <tree-ish> (most often a commit). In
32
-this case, the `-b` and `--track` options are meaningless and giving
33
-either of them results in an error. The <tree-ish> argument can be
34
-used to specify a specific tree-ish (i.e. commit, tag or tree)
35
-to update the index for the given paths before updating the
36
-working tree.
33
+'git checkout' [--patch] [<tree-ish>] [--] [<pathspec>...]::
34
35
+ When <paths> or --patch are given, this command does *not* switch
36
+ branches. It updates the named paths in the working tree from
37
+ the index file, or from a named <tree-ish> (most often a commit). In
38
+ this case, the `-b` and `--track` options are meaningless and giving
39
+ either of them results in an error. The <tree-ish> argument can be
40
+ used to specify a specific tree-ish (i.e. commit, tag or tree)
41
+ to update the index for the given paths before updating the
42
+ working tree.
43
++
44
The index may contain unmerged entries after a failed merge. By
45
default, if you try to check out such an entry from the index, the
46
checkout operation will fail and nothing will be checked out.