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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 31, 2023, 16:12 UTC
Message-ID: <xmqqlejchpct.fsf@gitster.g>
In-Reply-To: <pull.1484.git.git.1680257503697.gitgitgadget@gmail.com>

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

Show 11 quoted lines

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