[PATCH] docs: fix git stash grammar

[PATCH] docs: fix git stash grammar

[Quentin Bernet via GitGitGadget]

From: Quentin Bernet <quentin.bernet@bluewin.ch>

Grammar incorrectly did not include `git stash -m`
and other valid `git stash push` flags

Signed-off-by: Quentin Bernet <quentin.bernet@bluewin.ch>
---
    Fix git stash grammar

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2255%2FSporarum%2Fpatch-1-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2255/Sporarum/patch-1-v1
Pull-Request: https://github.com/git/git/pull/2255

 Documentation/git-stash.adoc | 4 ++--
 builtin/stash.c              | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc
index 235d57ddd8..41086c21a4 100644
--- a/Documentation/git-stash.adoc
+++ b/Documentation/git-stash.adoc
@@ -14,10 +14,10 @@ git stash drop [-q | --quiet] [<stash>]
 git stash pop [--index] [-q | --quiet] [<stash>]
 git stash apply [--index] [-q | --quiet] [<stash>]
 git stash branch <branchname> [<stash>]
-git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
 	     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
 	     [--pathspec-from-file=<file> [--pathspec-file-nul]]
-	     [--] [<pathspec>...]]
+	     [--] [<pathspec>...]
 git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
            [-u | --include-untracked] [-a | --all] [<message>]
 git stash clear
diff --git a/builtin/stash.c b/builtin/stash.c
index 95c5005b0b..0d27b2fb1f 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -50,10 +50,10 @@
 #define BUILTIN_STASH_STORE_USAGE \
 	N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>")
 #define BUILTIN_STASH_PUSH_USAGE \
-	N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
+	N_("git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
 	   "          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n" \
 	   "          [--pathspec-from-file=<file> [--pathspec-file-nul]]\n" \
-	   "          [--] [<pathspec>...]]")
+	   "          [--] [<pathspec>...]")
 #define BUILTIN_STASH_SAVE_USAGE \
 	N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
 	   "          [-u | --include-untracked] [-a | --all] [<message>]")

base-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789
-- 
gitgitgadget

Re: [PATCH] docs: fix git stash grammar

[D. Ben Knoble]

On Thu, Mar 26, 2026 at 8:46 AM Quentin Bernet via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Quentin Bernet <quentin.bernet@bluewin.ch>
>
> Grammar incorrectly did not include `git stash -m`
> and other valid `git stash push` flags

Typically commits for Git describe
- the current situation (present tense)
- commands to make the code better

In this case, something like

    The grammar for "git stash" is incorrectly bracketed; fix it.

?

>
> Signed-off-by: Quentin Bernet <quentin.bernet@bluewin.ch>
> ---
>     Fix git stash grammar
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2255%2FSporarum%2Fpatch-1-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2255/Sporarum/patch-1-v1
> Pull-Request: https://github.com/git/git/pull/2255
>
>  Documentation/git-stash.adoc | 4 ++--
>  builtin/stash.c              | 4 ++--
>  2 files changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc
> index 235d57ddd8..41086c21a4 100644
> --- a/Documentation/git-stash.adoc
> +++ b/Documentation/git-stash.adoc
> @@ -14,10 +14,10 @@ git stash drop [-q | --quiet] [<stash>]
>  git stash pop [--index] [-q | --quiet] [<stash>]
>  git stash apply [--index] [-q | --quiet] [<stash>]
>  git stash branch <branchname> [<stash>]
> -git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
> +git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
>              [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
>              [--pathspec-from-file=<file> [--pathspec-file-nul]]
> -            [--] [<pathspec>...]]
> +            [--] [<pathspec>...]
>  git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
>             [-u | --include-untracked] [-a | --all] [<message>]
>  git stash clear
> diff --git a/builtin/stash.c b/builtin/stash.c
> index 95c5005b0b..0d27b2fb1f 100644
> --- a/builtin/stash.c
> +++ b/builtin/stash.c
> @@ -50,10 +50,10 @@
>  #define BUILTIN_STASH_STORE_USAGE \
>         N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>")
>  #define BUILTIN_STASH_PUSH_USAGE \
> -       N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
> +       N_("git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
>            "          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n" \
>            "          [--pathspec-from-file=<file> [--pathspec-file-nul]]\n" \
> -          "          [--] [<pathspec>...]]")
> +          "          [--] [<pathspec>...]")
>  #define BUILTIN_STASH_SAVE_USAGE \
>         N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
>            "          [-u | --include-untracked] [-a | --all] [<message>]")
>
> base-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789
> --
> gitgitgadget

Now, _is_ the grammar bracketed wrong? "git help stash" says

           For quickly making a snapshot, you can omit "push". In this mode,
           non-option arguments are not allowed to prevent a misspelled
           subcommand from making an unwanted stash entry. The two exceptions
           to this are stash -p which acts as alias for stash push -p and
           pathspec elements, which are allowed after a double hyphen -- for
           disambiguation.

So _if_ you want to provide options (other than "-p"), the "push" is
required. I think the existing brackets indicate that.

-- 
D. Ben Knoble

Re: [PATCH] docs: fix git stash grammar

[Mirko Faina]

On Thu, Mar 26, 2026 at 12:17:46PM -0400, D. Ben Knoble wrote:
> Now, _is_ the grammar bracketed wrong? "git help stash" says
> 
>            For quickly making a snapshot, you can omit "push". In this mode,
>            non-option arguments are not allowed to prevent a misspelled
>            subcommand from making an unwanted stash entry. The two exceptions
>            to this are stash -p which acts as alias for stash push -p and
>            pathspec elements, which are allowed after a double hyphen -- for
>            disambiguation.
> 
> So _if_ you want to provide options (other than "-p"), the "push" is
> required. I think the existing brackets indicate that.

When it says "In this mode, non-option arguments are not allowed"
wouldn't -m be allowed as it is an option and not a non-option? In fact
if we do try to run "git stash -m something" it does correctly stash
while if we do something like "git stash pathspec" it does give back
"fatal: subcommand wasn't specified; 'push' can't be assumed due to
unexpected token 'pathspec'".

If that is the case then there is an issue with the way the usage
tooltip shows the optionality of "push".

Re: [PATCH] docs: fix git stash grammar

[Quentin Bernet]

This seems to be describing more the content of the patch than the 
intention behind it, what about:

The grammar for "git stash" does not contain valid combinations such as
"git stash --include-untracked"; fix it

On 3/26/26 17:17, D. Ben Knoble wrote:
> On Thu, Mar 26, 2026 at 8:46 AM Quentin Bernet via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> From: Quentin Bernet <quentin.bernet@bluewin.ch>
>>
>> Grammar incorrectly did not include `git stash -m`
>> and other valid `git stash push` flags
> Typically commits for Git describe
> - the current situation (present tense)
> - commands to make the code better
>
> In this case, something like
>
>      The grammar for "git stash" is incorrectly bracketed; fix it.
>
> ?
>
>> Signed-off-by: Quentin Bernet <quentin.bernet@bluewin.ch>
>> ---
>>      Fix git stash grammar
>>
>> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2255%2FSporarum%2Fpatch-1-v1
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2255/Sporarum/patch-1-v1
>> Pull-Request: https://github.com/git/git/pull/2255
>>
>>   Documentation/git-stash.adoc | 4 ++--
>>   builtin/stash.c              | 4 ++--
>>   2 files changed, 4 insertions(+), 4 deletions(-)
>>
>> diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc
>> index 235d57ddd8..41086c21a4 100644
>> --- a/Documentation/git-stash.adoc
>> +++ b/Documentation/git-stash.adoc
>> @@ -14,10 +14,10 @@ git stash drop [-q | --quiet] [<stash>]
>>   git stash pop [--index] [-q | --quiet] [<stash>]
>>   git stash apply [--index] [-q | --quiet] [<stash>]
>>   git stash branch <branchname> [<stash>]
>> -git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
>> +git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
>>               [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
>>               [--pathspec-from-file=<file> [--pathspec-file-nul]]
>> -            [--] [<pathspec>...]]
>> +            [--] [<pathspec>...]
>>   git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
>>              [-u | --include-untracked] [-a | --all] [<message>]
>>   git stash clear
>> diff --git a/builtin/stash.c b/builtin/stash.c
>> index 95c5005b0b..0d27b2fb1f 100644
>> --- a/builtin/stash.c
>> +++ b/builtin/stash.c
>> @@ -50,10 +50,10 @@
>>   #define BUILTIN_STASH_STORE_USAGE \
>>          N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>")
>>   #define BUILTIN_STASH_PUSH_USAGE \
>> -       N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
>> +       N_("git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
>>             "          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n" \
>>             "          [--pathspec-from-file=<file> [--pathspec-file-nul]]\n" \
>> -          "          [--] [<pathspec>...]]")
>> +          "          [--] [<pathspec>...]")
>>   #define BUILTIN_STASH_SAVE_USAGE \
>>          N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
>>             "          [-u | --include-untracked] [-a | --all] [<message>]")
>>
>> base-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789
>> --
>> gitgitgadget
> Now, _is_ the grammar bracketed wrong? "git help stash" says
>
>             For quickly making a snapshot, you can omit "push". In this mode,
>             non-option arguments are not allowed to prevent a misspelled
>             subcommand from making an unwanted stash entry. The two exceptions
>             to this are stash -p which acts as alias for stash push -p and
>             pathspec elements, which are allowed after a double hyphen -- for
>             disambiguation.
>
> So _if_ you want to provide options (other than "-p"), the "push" is
> required. I think the existing brackets indicate that.
>

Re: [PATCH] docs: fix git stash grammar

[Junio C Hamano]

Mirko Faina <mroik@delayed.space> writes:

> On Thu, Mar 26, 2026 at 12:17:46PM -0400, D. Ben Knoble wrote:
>> Now, _is_ the grammar bracketed wrong? "git help stash" says
>> 
>>            For quickly making a snapshot, you can omit "push". In this mode,
>>            non-option arguments are not allowed to prevent a misspelled
>>            subcommand from making an unwanted stash entry. The two exceptions
>>            to this are stash -p which acts as alias for stash push -p and
>>            pathspec elements, which are allowed after a double hyphen -- for
>>            disambiguation.
>> 
>> So _if_ you want to provide options (other than "-p"), the "push" is
>> required. I think the existing brackets indicate that.
>
> When it says "In this mode, non-option arguments are not allowed"
> wouldn't -m be allowed as it is an option and not a non-option? In fact
> if we do try to run "git stash -m something" it does correctly stash
> while if we do something like "git stash pathspec" it does give back
> "fatal: subcommand wasn't specified; 'push' can't be assumed due to
> unexpected token 'pathspec'".
>
> If that is the case then there is an issue with the way the usage
> tooltip shows the optionality of "push".

Yup, you're right.  The current SYNOPSIS suggests that you can omit
and say "git stash" and it does the "push" thing, but when you want
to give any "push" related options, the command name "push" becomes
mandatory before them.

If the log message said something like

    The "[optionality]" bracket is misplaced on the command line for
    "git stash push" in the synopsis section.  It is not like you
    can omit "push" only when you do not give any options and
    arguments.

we wouldn't be having this long thread, I suspect.

Re: [PATCH] docs: fix git stash grammar

[Quentin Bernet]

Please keep in mind this is my first contribution to git, and learning 
the ways things are done here, so things might take more time than usual

I believe to be fully correct, this should be the grammar:
(or some other ordering)


  [synopsis]
+git stash [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | 
--quiet]
+            [-u | --include-untracked] [-a | --all] [(-m | --message) 
<message>]
+            [--pathspec-from-file=<file> [--pathspec-file-nul]]
+            [-- <pathspec>...]
  git stash list [<log-options>]
  git stash show [-u | --include-untracked | --only-untracked] 
[<diff-options>] [<stash>]
  git stash drop [-q | --quiet] [<stash>]
  git stash pop [--index] [-q | --quiet] [<stash>]
  git stash apply [--index] [-q | --quiet] [<stash>]
  git stash branch <branchname> [<stash>]
-git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] 
[-q | --quiet]
+git stash push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] 
[-q | --quiet]
              [-u | --include-untracked] [-a | --all] [(-m | --message) 
<message>]
              [--pathspec-from-file=<file> [--pathspec-file-nul]]
-            [--] [<pathspec>...]]
+            [--] [<pathspec>...]
  git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] 
[-q | --quiet]
             [-u | --include-untracked] [-a | --all] [<message>]
  git stash clear

You'll note the difference between the "stash" and "stash push" options 
is "[-- <pathspec>...]" vs "[--] [<pathspec>...]", which corresponds to

            For quickly making a snapshot, you can omit "push". In this 
mode,
            non-option arguments are not allowed to prevent a misspelled
            subcommand from making an unwanted stash entry. The two 
exceptions
            to this are stash -p which acts as alias for stash push -p and
            pathspec elements, which are allowed after a double hyphen 
-- for
            disambiguation.

The wording seems a bit weird, since the only non-option arguments are 
"<pathspec>...", which it later explains are allowed (but require double 
hypen)


This grammar is better at highlighting `git stash` on its own is valid, 
but worse at showing that the flags are almost the same
I don't think we can do better grammar-wise, since "push" is at the very 
start, and "--" at the end, and grammars don't have memory

My previous, simpler, grammar included "git stash <pathspec>" even 
though it is not valid.
Maybe that is an acceptable trade-off for clarity (although I assume not)

On 3/27/26 16:58, Junio C Hamano wrote:
> Mirko Faina <mroik@delayed.space> writes:
>
>> On Thu, Mar 26, 2026 at 12:17:46PM -0400, D. Ben Knoble wrote:
>>> Now, _is_ the grammar bracketed wrong? "git help stash" says
>>>
>>>             For quickly making a snapshot, you can omit "push". In this mode,
>>>             non-option arguments are not allowed to prevent a misspelled
>>>             subcommand from making an unwanted stash entry. The two exceptions
>>>             to this are stash -p which acts as alias for stash push -p and
>>>             pathspec elements, which are allowed after a double hyphen -- for
>>>             disambiguation.
>>>
>>> So _if_ you want to provide options (other than "-p"), the "push" is
>>> required. I think the existing brackets indicate that.
>> When it says "In this mode, non-option arguments are not allowed"
>> wouldn't -m be allowed as it is an option and not a non-option? In fact
>> if we do try to run "git stash -m something" it does correctly stash
>> while if we do something like "git stash pathspec" it does give back
>> "fatal: subcommand wasn't specified; 'push' can't be assumed due to
>> unexpected token 'pathspec'".
>>
>> If that is the case then there is an issue with the way the usage
>> tooltip shows the optionality of "push".
> Yup, you're right.  The current SYNOPSIS suggests that you can omit
> and say "git stash" and it does the "push" thing, but when you want
> to give any "push" related options, the command name "push" becomes
> mandatory before them.
>
> If the log message said something like
>
>      The "[optionality]" bracket is misplaced on the command line for
>      "git stash push" in the synopsis section.  It is not like you
>      can omit "push" only when you do not give any options and
>      arguments.
>
> we wouldn't be having this long thread, I suspect.

Re: [PATCH] docs: fix git stash grammar

[Ben Knoble]

> 
> Le 26 mars 2026 à 20:04, Mirko Faina <mroik@delayed.space> a écrit :
> 
> On Thu, Mar 26, 2026 at 12:17:46PM -0400, D. Ben Knoble wrote:
>> Now, _is_ the grammar bracketed wrong? "git help stash" says
>> 
>>           For quickly making a snapshot, you can omit "push". In this mode,
>>           non-option arguments are not allowed to prevent a misspelled
>>           subcommand from making an unwanted stash entry. The two exceptions
>>           to this are stash -p which acts as alias for stash push -p and
>>           pathspec elements, which are allowed after a double hyphen -- for
>>           disambiguation.
>> 
>> So _if_ you want to provide options (other than "-p"), the "push" is
>> required. I think the existing brackets indicate that.
> 
> When it says "In this mode, non-option arguments are not allowed"
> wouldn't -m be allowed as it is an option and not a non-option? In fact
> if we do try to run "git stash -m something" it does correctly stash
> while if we do something like "git stash pathspec" it does give back
> "fatal: subcommand wasn't specified; 'push' can't be assumed due to
> unexpected token 'pathspec'".
> 
> If that is the case then there is an issue with the way the usage
> tooltip shows the optionality of "push".

Indeed, thanks. 

Re: [PATCH] docs: fix git stash grammar

[Junio C Hamano]

Quentin Bernet <quentin.bernet@bluewin.ch> writes:

> My previous, simpler, grammar included "git stash <pathspec>" even 
> though it is not valid.

"git stash -- path1 path2 ..." is valid and is taken as elliding the
subcommand name 'push'.  So I think your previous one is good enough
but the command line description needs to mention that.  Double dash
is used to signal the start of pathspec when ambiguous, and it is a
good example to highlight when it is useful.  Without disambiguating
"--", "path1" might be misspelt subcommand name but we cannot tell
which one.  You may even have a file whose name is "pop", and "git
stash -- pop" would be a way to save away the changes to the file
without having to say "push" explicitly ;-)

Re: [PATCH] docs: fix git stash grammar

[Quentin Bernet]

Just so we're clear: my previous grammar did allow "git stash path1 
path2" (no "push", no "--"), which is not allowed
Do you still think it is good enough ?

"the command line description needs to mention that." that is already 
the case, no ?

On 3/27/26 17:53, Junio C Hamano wrote:
> Quentin Bernet <quentin.bernet@bluewin.ch> writes:
>
>> My previous, simpler, grammar included "git stash <pathspec>" even
>> though it is not valid.
> "git stash -- path1 path2 ..." is valid and is taken as elliding the
> subcommand name 'push'.  So I think your previous one is good enough
> but the command line description needs to mention that.  Double dash
> is used to signal the start of pathspec when ambiguous, and it is a
> good example to highlight when it is useful.  Without disambiguating
> "--", "path1" might be misspelt subcommand name but we cannot tell
> which one.  You may even have a file whose name is "pop", and "git
> stash -- pop" would be a way to save away the changes to the file
> without having to say "push" explicitly ;-)
>

Re: [PATCH] docs: fix git stash grammar

[Junio C Hamano]

Quentin Bernet <quentin.bernet@bluewin.ch> writes:

> Just so we're clear: my previous grammar did allow "git stash path1 
> path2" (no "push", no "--"), which is not allowed
> Do you still think it is good enough ?

Absolutely.

It is not huge enough issue to warrant separating synopsis form for
push into two almost identical pairs, and having to maintain both of
them.  It would be sufficient to make sure the readers understand
that they may have to disambiguate pathspec with "--" like any other
command (like "git log foo" when you have both file "foo" and tag
"foo") in the description part.

One thing that we may want to fix in the code is that we probably do
not want to require "--" when doing something like

    git stash -m foo <pathspec>

to assume that it is a lazy "push" that does not say "push".
Currently we complain against the lack of subcommand name.

Once "-m" (i.e., a potential option) is seen before seeing any
subcommand, we can commit to treat it as a lazy "push", and have the
parser pretend as if we got

    git stash push -m foo <pathspec>

We may see "git stash -m foo --no-such-option garbage arge" and the
option and argument parser of "git stash push" becomes responsible
for complaining about such a command line.

#leftoverbits obviously.

Re: [PATCH] docs: fix git stash grammar

[Quentin Bernet]

I'm assuming "#leftoverbits" means "this is something that would be 
nice, but which is for another time"
And I'll leave the pleasure of implementing that to someone more 
well-versed in C and git internals !


Therefore my previous change (current status of the github PR) works, as 
a reminder, here it is:


diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc
index 235d57ddd8..41086c21a4 100644
--- a/Documentation/git-stash.adoc
+++ b/Documentation/git-stash.adoc
@@ -14,10 +14,10 @@ git stash drop [-q | --quiet] [<stash>]
  git stash pop [--index] [-q | --quiet] [<stash>]
  git stash apply [--index] [-q | --quiet] [<stash>]
  git stash branch <branchname> [<stash>]
-git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] 
[-q | --quiet]
+git stash [push] [-p | --patch] [-S | --staged] [-k | 
--[no-]keep-index] [-q | --quiet]
              [-u | --include-untracked] [-a | --all] [(-m | --message) 
<message>]
              [--pathspec-from-file=<file> [--pathspec-file-nul]]
-            [--] [<pathspec>...]]
+            [--] [<pathspec>...]
  git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] 
[-q | --quiet]
             [-u | --include-untracked] [-a | --all] [<message>]
  git stash clear
diff --git a/builtin/stash.c b/builtin/stash.c
index 95c5005b0b..0d27b2fb1f 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -50,10 +50,10 @@
  #define BUILTIN_STASH_STORE_USAGE \
         N_("git stash store [(-m | --message) <message>] [-q | --quiet] 
<commit>")
  #define BUILTIN_STASH_PUSH_USAGE \
-       N_("git stash [push [-p | --patch] [-S | --staged] [-k | 
--[no-]keep-index] [-q | --quiet]\n" \
+       N_("git stash [push] [-p | --patch] [-S | --staged] [-k | 
--[no-]keep-index] [-q | --quiet]\n" \
            "          [-u | --include-untracked] [-a | --all] [(-m | 
--message) <message>]\n" \
            "          [--pathspec-from-file=<file> 
[--pathspec-file-nul]]\n" \
-          "          [--] [<pathspec>...]]")
+          "          [--] [<pathspec>...]")
  #define BUILTIN_STASH_SAVE_USAGE \
         N_("git stash save [-p | --patch] [-S | --staged] [-k | 
--[no-]keep-index] [-q | --quiet]\n" \
            "          [-u | --include-untracked] [-a | --all] [<message>]")


Is there something else I should do ?


On 3/27/26 18:16, Junio C Hamano wrote:
> Quentin Bernet <quentin.bernet@bluewin.ch> writes:
>
>> Just so we're clear: my previous grammar did allow "git stash path1
>> path2" (no "push", no "--"), which is not allowed
>> Do you still think it is good enough ?
> Absolutely.
>
> It is not huge enough issue to warrant separating synopsis form for
> push into two almost identical pairs, and having to maintain both of
> them.  It would be sufficient to make sure the readers understand
> that they may have to disambiguate pathspec with "--" like any other
> command (like "git log foo" when you have both file "foo" and tag
> "foo") in the description part.
>
> One thing that we may want to fix in the code is that we probably do
> not want to require "--" when doing something like
>
>      git stash -m foo <pathspec>
>
> to assume that it is a lazy "push" that does not say "push".
> Currently we complain against the lack of subcommand name.
>
> Once "-m" (i.e., a potential option) is seen before seeing any
> subcommand, we can commit to treat it as a lazy "push", and have the
> parser pretend as if we got
>
>      git stash push -m foo <pathspec>
>
> We may see "git stash -m foo --no-such-option garbage arge" and the
> option and argument parser of "git stash push" becomes responsible
> for complaining about such a command line.
>
> #leftoverbits obviously.
>

Re: [PATCH] docs: fix git stash grammar

[Junio C Hamano]

Quentin Bernet <quentin.bernet@bluewin.ch> writes:

[administrivia] don't top post.

> I'm assuming "#leftoverbits" means "this is something that would be 
> nice, but which is for another time"
> And I'll leave the pleasure of implementing that to someone more 
> well-versed in C and git internals !
>
>
> Therefore my previous change (current status of the github PR) works, as 
> a reminder, here it is:
> ...
>
> diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc
> ...
>   git stash clear
> ...
> Is there something else I should do ?

Without any additional effort on top of what we saw in the previous
patch, I am not sure if ...

>> ...  It would be sufficient to make sure the readers understand
>> that they may have to disambiguate pathspec with "--" like any other
>> command (like "git log foo" when you have both file "foo" and tag
>> "foo") in the description part.

... is already achieved.

Also, my earlier "if the log message said ..., we wouldn't be having
this long thread" comment still stands.

    https://lore.kernel.org/git/xmqqqzp5mfh5.fsf@gitster.g/

Thanks.