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

On Monday 20 November 2017 07:39 AM, Junio C Hamano wrote:

Kaartic Sivaraam [off-list ref] writes:

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).

Thanks for the analysis. Just to be sure, I referred to 75d6e552a just 
to back up my claim, was that intention clear in my log message? Also, 
should I mention the old commit (696acf45) also in the log message?

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).

Good point. I did use your rewritten message but with some modification,

     You can also use the `@{-N}` syntax to refer to the N-th last
     branch/commit checked out using "git checkout" operation. You may
     also specify `-` which is synonymous to `@{-1}`.

I tweaked the first part of the first sentence and dropped the last part 
of it just to avoid redundancy with the paragraph above it. Hope that 
sounds good. If it seems to need some modification, let me know.


Thanks,
Kaartic