From: Jonathan Nieder <jrnieder@gmail.com>
Date: Wed, 11 Sep 2013 19:06:41 GMT
Subject: Re: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command
Message-ID: <20130911190641.GF4326@google.com>
In-Reply-To: <xmqq1u4vuw4y.fsf@gitster.dls.corp.google.com>

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