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

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

[ryicoh via GitGitGadget]

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(-)

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}.
 
 '[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
   A branch B may be set up to build on top of a branch X (configured with

base-commit: 6369acd968d02899973a9a853c48029b92cea401
-- 
gitgitgadget

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

[Oswald Buddenhagen]

On Fri, Mar 31, 2023 at 10:11:43AM +0000, ryicoh via GitGitGadget wrote:
>+  before the current one. You may also specify - which is synonymous
>+  to @{-1}.
> 
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.

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

[Junio C Hamano]

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

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

[ryicoh]

Hi Oswald, Junio and Phillip.

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

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

That's good. I'll fix it.

> It is certainly *not* synonymous in general and I
> doubt we want to make it to.

That's correct. Your examples helped me understand.

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

That's correct too.


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

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

Best Wishes

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

[Junio C Hamano]

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?

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

[Phillip Wood]

Hi ryicoh

On 31/03/2023 11:11, ryicoh via GitGitGadget wrote:
> From: ryicoh <ryicoh@gmail.com>
> 
> Signed-off-by: ryicoh <ryicoh@gmail.com>
> ---
>      doc: add that '-' is the same as '@{-1}'

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

>      
>      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(-)
> 
> 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}.
>   
>   '[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
>     A branch B may be set up to build on top of a branch X (configured with
> 
> base-commit: 6369acd968d02899973a9a853c48029b92cea401