Subject: Re: [PATCH] docs: fix git stash grammar

From: Quentin Bernet <[email-masked]>
Date: Fri, 27 Mar 2026 17:28:05 +0100

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 <[email-masked]> 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.