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

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

ryicoh <ryicoh@gmail.com> writes:

>> 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?