[PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command

[PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command

[Benjamin Bergman]

>From a33659535cb0eac92bed42d5e494dbb8f5d9ab20 Mon Sep 17 00:00:00 2001
From: Benjamin Bergman <ben@benbergman.ca>
Date: Tue, 10 Sep 2013 16:00:29 -0500
Subject: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis
 to correct command

Detailed description of `--detach` states that it is default for
`<commit>` but needs to be specified for `<branch>`. The old man page
synopsis showed the reverse.
---
 Documentation/git-checkout.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index ca118ac..dee95e8 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -8,8 +8,8 @@ git-checkout - Checkout a branch or paths to the working tree
 SYNOPSIS
 --------
 [verse]
-'git checkout' [-q] [-f] [-m] [<branch>]
-'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
+'git checkout' [-q] [-f] [-m] [--detach] [<branch>]
+'git checkout' [-q] [-f] [-m] [<commit>]
 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>]
[<tree-ish>] [--] <paths>...
 'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]
-- 
1.8.3.4

Re: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command

[Junio C Hamano]

Benjamin Bergman <ben@benbergman.ca> writes:

> From a33659535cb0eac92bed42d5e494dbb8f5d9ab20 Mon Sep 17 00:00:00 2001
> From: Benjamin Bergman <ben@benbergman.ca>
> Date: Tue, 10 Sep 2013 16:00:29 -0500
> Subject: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis
>  to correct command

These (except the first one that is a separator in the format-patch output)
go to your e-mail headers, not to the body of the message.

>
> Detailed description of `--detach` states that it is default for
> `<commit>` but needs to be specified for `<branch>`. The old man page
> synopsis showed the reverse.
> ---

Please sign-off your patch.

> -'git checkout' [-q] [-f] [-m] [<branch>]
> -'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
> +'git checkout' [-q] [-f] [-m] [--detach] [<branch>]
> +'git checkout' [-q] [-f] [-m] [<commit>]

I am actually on the fence on this change.

The original shows two operations that do different things (one goes
to a named branch, the other goes to the state in which the HEAD is
detached at the named commit).

With the updated synopsis, even with the first form, if the user
uses --detach, the end result is like the second one. I personally
find the synopsis with the patch a bit more confusing, not less.

Can we update the second form (without touching the one that shows
"how to check out a named branch" at all) in a different way to
clarify?  E.g.

        'git checkout' [-q] [-f] [-m] [<commit> | --detach <branch>]

might be one way.  If you want to detach at a named commit, you can
directly give the commit object name; a branch name usually can be
used as a commit object name, but that use conflicts with the more
usual "check out that branch" usage, so you need to give --detach
explicitly if you use a branch name to name that commit you want to
detach at.  One drawback this has is that it does not capture that
you could say --detach (even though you do not have to) when using a
form that is _not_ a branch name to name your commit, e.g.

	git checkout --detach master^0

... thinks a bit more ...

Or we can split the "detaching" usage into two, which is how the
DESCRIPTION section does.  I.e.

    'git checkout' [-q] [-f] [-m] [<branch>]
   -'git checkout' [-q] [-f] [-m] --detach [<commit>]
   +'git checkout' [-q] [-f] [-m] --detach [<branch>]
   +'git checkout' [-q] [-f] [-m] <commit>
    'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<st...

This would tell the reader that:

    - You can give "--detach" and no branch name---you would detach
      at the tip of your current branch;

    - You can give "--detach" and a branch name;

    - You can give a commit object name.

We could also throw in "[--detach]" in front of the <commit> to say
that it is accepted (even though it is not necessary.

>  'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
>  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>]
> [<tree-ish>] [--] <paths>...

Your MUA or editor line-wrapped the patch; please do not let them.

>  'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]


How about doing it this way?

-- >8 --
Subject: 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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-checkout.txt | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index ca118ac..01d9b85 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -9,7 +9,8 @@ SYNOPSIS
 --------
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]
-'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
+'git checkout' [-q] [-f] [-m] --detach [<branch>]
+'git checkout' [-q] [-f] [-m] [--detach] <commit>
 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 '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
 successful.
 
 'git checkout' --detach [<branch>]::
-'git checkout' <commit>::
+'git checkout' [--detach] <commit>::
 
 	Prepare to work on top of <commit>, by detaching HEAD at it
 	(see "DETACHED HEAD" section), and updating the index and the
@@ -71,10 +72,13 @@ successful.
 	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.
+Even though a branch name can be used to name a commit, you have to
+explicitly say `git checkout --detach <branch>` when you want to
+detach HEAD at the tip of the branch (`git checkout <branch>` will
+check out that branch without detaching HEAD).  Omitting <branch>,
+i.e. `git checkout --detach` detaches HEAD at the tip of the current
+branch.  When naming the commit in a form other than just a branch
+name, e.g. `master^0`, `HEAD~4`, `c2f3bf071e`, you can omit --detach.
 
 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
 

Re: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command

[Jonathan Nieder]

Hi,

Junio C Hamano wrote:

> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -9,7 +9,8 @@ SYNOPSIS
>  --------
>  [verse]
>  'git checkout' [-q] [-f] [-m] [<branch>]
> -'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
> +'git checkout' [-q] [-f] [-m] --detach [<branch>]
> +'git checkout' [-q] [-f] [-m] [--detach] <commit>
>  'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
>  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
>  '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
>  successful.
>  
>  'git checkout' --detach [<branch>]::
> -'git checkout' <commit>::
> +'git checkout' [--detach] <commit>::

Looks sensible.

[...]
> @@ -71,10 +72,13 @@ successful.
>  	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.
> +Even though a branch name can be used to name a commit, you have to
> +explicitly say `git checkout --detach <branch>` when you want to
> +detach HEAD at the tip of the branch (`git checkout <branch>` will
> +check out that branch without detaching HEAD).  Omitting <branch>,
> +i.e. `git checkout --detach` detaches HEAD at the tip of the current
> +branch.  When naming the commit in a form other than just a branch
> +name, e.g. `master^0`, `HEAD~4`, `c2f3bf071e`, you can omit --detach.

Hm.  I agree that the old explanation is overly convoluted, but I don't
think the replacement is clear enough yet.  The "Even though a branch
name can be used to name a commit," part forced me to pause for too
long --- why is this telling me that a branch can be used to name a
commit, and in what context?

I think the main problem with the old text is that it tried to say too
much in one sentence.

The explanation lower down of the --detach option does this rather
well:

	--detach
		Rather than checking out a branch to work on it, check
		out a commit for inspection and discardable
		experiments.  This is the default behavior of
		"git checkout <commit>" when <commit> is not a branch
		name.  See the "DETACHED HEAD" section below for
		details.

How about splitting this into multiple paragraphs, like so?  In the
suggestion below I also cleaned up the language a little.

	git checkout --detach [<branch>], git checkout [--detach] <commit>
		Prepare to work on top of <commit>, by detaching [...]

		When the <commit> argument is a branch name, the --detach
		option can be used to detach HEAD at the tip of the
		branch ('git checkout <branch>' would check out that
		branch without detaching HEAD).

		Omitting <branch> detaches HEAD at the tip of the
		current branch.

I'd leave out the last sentence about commits other than branch names,
since it is already implied by the [--detach] in the syntax.

Thanks and hope that helps,
Jonathan