checkout: update synopsys and documentation on detaching HEAD
In the synopsis, the second form to detach HEAD at the named commit labelled the argument as '<commit>'. While this is technically more correct, because the feature to detach is not limited to the tip of a named branch, it was found confusing and did not express the fact that you have to give `--detach` if you are naming the commit you want to detach HEAD at with a branch name. Separate this case into two syntactical forms, mimicking the way how the DESCRIPTION section shows this usage. Also update the text that explains the syntax to name the commit to detach HEAD at to clarify. Suggested-by: Benjamin Bergman <ben@benbergman.ca> Helped-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Sep 11, 2013 at 10:05 UTC
26776c9737a6b5b0e7aab142aef6ba856d8b46ca
1 file changed
+8
-6
Documentation/git-checkout.txt
+8
-6
@@ -9,7 +9,8 @@ SYNOPSIS
9
--------
10
[verse]
11
'git checkout' [-q] [-f] [-m] [<branch>]
12
-'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
12
+'git checkout' [-q] [-f] [-m] --detach [<branch>]
13
+'git checkout' [-q] [-f] [-m] [--detach] <commit>
14
'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
15
'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
16
'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]
@@ -62,7 +63,7 @@ that is to say, the branch is not reset/created unless "git checkout" is
63
successful.
64
65
'git checkout' --detach [<branch>]::
65
-'git checkout' <commit>::
66
+'git checkout' [--detach] <commit>::
67
68
Prepare to work on top of <commit>, by detaching HEAD at it
69
(see "DETACHED HEAD" section), and updating the index and the
@@ -71,10 +72,11 @@ successful.
72
tree will be the state recorded in the commit plus the local
73
modifications.
74
+
74
-Passing `--detach` forces this behavior in the case of a <branch> (without
75
-the option, giving a branch name to the command would check out the branch,
76
-instead of detaching HEAD at it), or the current commit,
77
-if no <branch> is specified.
75
+When the <commit> argument is a branch name, the `--detach` option can
76
+be used to detach HEAD at the tip of the branch (`git checkout
77
+<branch>` would check out that branch without detaching HEAD).
78
++
79
+Omitting <branch> detaches HEAD at the tip of the current branch.
80
81
'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
82