Re: [PATCH] docs: checking out using @{-N} can lead to detached state

[Junio C Hamano <gitster@pobox.com>]

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

> The commit message of 75d6e552a (Documentation: @{-N} can refer to
> a commit, 2014-01-19) clearly specifies how @{-N} can be used to
> refer not only to a branch but also to a commit. IOW, @{-N} is a
> syntax for the N-th last "checkout" and not the N-th last "branch"

If you define a new term "checkout" to mean "what was checked out",
yes that is correct.  After re-reading the said commit and the text
it tried to update, I agree with you that it did not go far enough.

After the first paragraph explains what happens during "checkout
<branch>" and goes from the normal case where <branch> is really a
branch name to an arbitrary commit (where "detaching" needs to be
mentioned), a commit before 75d6e552a added mention of @{-N} and
made it appear as if it were a reference to a commit (i.e. not a
branch name) and that was why it said "As a special case" and
mentioned "detaching".  The problem lies in a lot older one,
696acf45 ("checkout: implement "-" abbreviation, add docs and
tests", 2009-01-17).

I agree that a real fix should ensure that @{-N} is merely a
short-hand for what was checked out in the Nth-previous "git
checkout" operation, *and* regardless of which between a branch name
or a commit object name that Nth thing is, the previous rules we
already gave in the first paragraph apply---if the thing checked out
in the Nth-previous "git checkout" was a branch, we checkout the
branch.  If it was a commit, we detach.

So perhaps we should start from dropping that "As a special case".

    You can also use the `"@{-N}"` syntax to refer to the thing the N-th
    last "git checkout" operation checked out; if it was a branch, that
    branch is checked out, and otherwise the HEAD is detached at the
    commit.  You may also specify `-` which is synonymous to `"@{-1}"`.

or something like that.  If we do so, we'd further need to tweak "As
a further special case", as this rewrite makes it clear that "@{-N}"
is not a special case at all (instead it is merely a different way
to spell <branch> or <commit> that is already covered).

Thanks.


> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index e108b0f74..238880f10 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -272,9 +272,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
>  	commit, your HEAD becomes "detached" and you are no longer on
>  	any branch (see below for details).
>  +
> -As a special case, the `"@{-N}"` syntax for the N-th last branch/commit
> -checks out branches (instead of detaching).  You may also specify
> -`-` which is synonymous with `"@{-1}"`.
> +As a special case, the `@{-N}` syntax checks out the N-th last branch/commit(checkout).
> +You may also specify `-` which is synonymous with `@{-1}`.
>  +
>  As a further special case, you may use `"A...B"` as a shortcut for the
>  merge base of `A` and `B` if there is exactly one merge base. You can