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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html