patchdoc: add that '-' is the same as '@{-1}'

From: ryicoh <ryicoh@gmail.com>

Signed-off-by: ryicoh <ryicoh@gmail.com>
---
    doc: add that '-' is the same as '@{-1}'
    
    Now, the document of '-' is written only git-switch.txt.
    
    https://github.com/git/git/blob/6369acd968d02899973a9a853c48029b92cea401/Documentation/git-switch.txt#L51
    
    I want same one in revisions.txt.
    
    Thank you.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1484%2Fryicoh%2Fdoc-hyphen-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1484/ryicoh/doc-hyphen-v1
Pull-Request: https://github.com/git/git/pull/1484

 Documentation/revisions.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

On Fri, Mar 31, 2023 at 10:11:43AM +0000, ryicoh via GitGitGadget wrote:

i'd recommend quoting the dash as you do in the summary (or adding some markup?), as otherwise it's way too easy to misread.

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

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.

Hi Oswald, Junio and Phillip.

Thank you for your reviews. Let me reply to each comments.

That's good. I'll fix it.

That's correct. Your examples helped me understand.

That's correct too.

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

Other commands also seem to accept '-', such as `cherry-pick`. It's not good idea to write all commands that accepted it.

Best Wishes

ryicoh <ryicoh@gmail.com> writes:

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?

Hi ryicoh

On 31/03/2023 11:11, ryicoh via GitGitGadget wrote:

A few commands (checkout, merge, rebase and switch spring to mind) accept '-' as a shorthand for '@{-1}' but I don't think it is universally accepted.

Best Wishes

Phillip