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

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

"ryicoh via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 9aa58052bc7..9e7ea2cf71e 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -94,7 +94,8 @@ some output processing may assume ref names in UTF-8.
>  
>  '@{-<n>}', e.g. '@{-1}'::
>    The construct '@{-<n>}' means the <n>th branch/commit checked out
> -  before the current one.
> +  before the current one. You may also specify - which is synonymous
> +  to @{-1}.

I know the author of the change meant well, but this change makes
the resulting text overly broad and misleading by saying `-` is
"synonymous".  It is certainly *not* synonymous in general and I
doubt we want to make it to.

  $ git switch --detach master
  $ git reset --hard maint
  $ git commit --amend -C -
  fatal: could not look up commit -
  $ git show -
  fatal: unrecognized argument: -
  $ git log ..-
  fatal: ambiguous argument '..-': unknown revision or path not in the working tree
  Use '--' to separate paths from revisions, like this:
  'git <command> [<revision>...] -- [<file...]'
  $ git log HEAD..- --
  fatal: bad revision 'HEAD..-'

There are only few selected places that treat "-" like "@{-1}".  The
primary motivation behind "-" is to allow those who are so used to
see that "cd $there && do something there && cd -" to come back to
the original place to do

  $ git switch there
  $ hack hack hack
  $ git switch -      ;# or "git checkout -"

and the intention is to use it where we do not allow arbitrary
commit object name but it is clear we are taking a branch name.

"git switch --help" and "git checkout --help" already mention them;
if there is another command that uses "-" as "@{-1}" (and not as
"the standard input" or "the standard output"), for now we should
update its documentation to mention "- can also be used in place of
@{-1}".

Thanks.