Re: [PATCH] doc: add that '-' is the same as '@{-1}'

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 2, 2023, 12:26 UTC
Message-ID: <xmqqsfdia2rz.fsf@gitster.g>
In-Reply-To: <20230401155342.21230-1-ryicoh@gmail.com>

ryicoh <ryicoh@gmail.com> writes:

Show 8 quoted lines

>> for now we should
>> update its documentation to mention "- can also be used in place of
>> @{-1}".
>
> Finally, How should I update the documentation? How about following changes?
>
> - You may also specify `-` which is synonymous to `@{-1}`.
> + Only some commands (checkout, switch, etc,), you may also specify `-` which is synonymous to `@{-1}`.

I would not do the above, if I were following the "_for now_ we should". I'd instead go to Documentation/git-foo.txt and imitate how git-checkout.txt next door describes @{-<N>} and mentions its special casing of '-'.

When a user is learning the subcommand 'foo' with a feature that is commonly used in the context of 'foo' and takes a branch (e.g. "checkout" takes "which branch to check out"), they want to find how the branch is spelled (e.g. "you can give a branch name, @{-<N>}, ah by the way "-" is @{-1}") in the documentation for 'foo' where the feature related to a branch is described. It would make the feature a lot harder to discover to bury a list of names of only a handful subcommands that share the same feature, while saying the feature would not generally be available, in another section whose primary purpose is to explain how to name an arbitrary revision, not a name of a branch, no?