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

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

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

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

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

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

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

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

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

> @@ -60,10 +60,8 @@ COMMANDS
>  	the description along with the stashed state.
>  +
>  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.
> +pathspec elements are only allowed after a double hyphen `--`
> +to prevent a misspelled subcommand from making an unwanted stash entry.

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