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

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

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.