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>
Chris Rorvick committed
Dec 17, 2012 at 00:45 UTC
e1cdf63316348332e4e267aeaab5b510beae0227
1 file changed
+33
-10
Documentation/git-checkout.txt
+33
-10
@@ -21,18 +21,26 @@ or the specified tree. If no paths are given, 'git checkout' will
21
also update `HEAD` to set the specified branch as the current
22
branch.
23
24
-'git checkout' [<branch>]::
24
+'git checkout' <branch>::
25
+ To prepare for working on <branch>, switch to it by updating
26
+ the index and the files in the working tree, and by pointing
27
+ HEAD at the branch. Local modifications to the files in the
28
+ working tree are kept, so that they can be committed to the
29
+ <branch>.
30
++
31
+You could omit <branch>, in which case the command degenerates to
32
+"check out the current branch", which is a glorified no-op with a
33
+rather expensive side-effects to show only the tracking information,
34
+if exists, for the current branch.
35
+
36
'git checkout' -b|-B <new_branch> [<start point>]::
26
-'git checkout' [--detach] [<commit>]::
37
28
- This form switches branches by updating the index, working
29
- tree, and HEAD to reflect the specified branch or commit.
30
-+
31
-If `-b` is given, a new branch is created as if linkgit:git-branch[1]
32
-were called and then checked out; in this case you can
33
-use the `--track` or `--no-track` options, which will be passed to
34
-'git branch'. As a convenience, `--track` without `-b` implies branch
35
-creation; see the description of `--track` below.
38
+ Specifying `-b` causes a new branch to be created as if
39
+ linkgit:git-branch[1] were called and then checked out. In
40
+ this case you can use the `--track` or `--no-track` options,
41
+ which will be passed to 'git branch'. As a convenience,
42
+ `--track` without `-b` implies branch creation; see the
43
+ description of `--track` below.
44
+
45
If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it
46
is reset. This is the transactional equivalent of
@@ -45,6 +53,21 @@ $ git checkout <branch>
53
that is to say, the branch is not reset/created unless "git checkout" is
54
successful.
55
56
+'git checkout' --detach [<branch>]::
57
+'git checkout' <commit>::
58
+
59
+ Prepare to work on top of <commit>, by detaching HEAD at it
60
+ (see "DETACHED HEAD" section), and updating the index and the
61
+ files in the working tree. Local modifications to the files
62
+ in the working tree are kept, so that the resulting working
63
+ tree will be the state recorded in the commit plus the local
64
+ modifications.
65
++
66
+Passing `--detach` forces this behavior in the case of a <branch> (without
67
+the option, giving a branch name to the command would check out the branch,
68
+instead of detaching HEAD at it), or the current commit,
69
+if no <branch> is specified.
70
+
71
'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
72
73
When <paths> or `--patch` are given, 'git checkout' does *not*