git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] docs: fix git stash grammar

From
Quentin Bernet <quentin.bernet@bluewin.ch>
Date
Mar 27, 2026, 16:28 UTC
Message-ID
<fbe531eb-b742-4cd1-ab6a-2eaaf8d236c5@bluewin.ch>
In-Reply-To
<xmqqqzp5mfh5.fsf@gitster.g>

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:
Show 36 quoted lines
> 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.
Previous: Junio C HamanoNext: Junio C Hamano
Message 5 of 15 in “docs: fix git stash grammar”
  1. docs: fix git stash grammarQuentin Bernet via GitGitGadget, Mar 26, 2026
  2. D. Ben KnobleMar 26, 2026
  3. Mirko FainaMar 27, 2026
  4. Junio C HamanoMar 27, 2026
  5. Quentin BernetMar 27, 2026
  6. Junio C HamanoMar 27, 2026
  7. Quentin BernetMar 27, 2026
  8. Junio C HamanoMar 27, 2026
  9. Quentin BernetMar 27, 2026
  10. Junio C HamanoMar 27, 2026
  11. Ben KnobleMar 27, 2026
  12. Quentin BernetMar 27, 2026
  13. docs: fix "git stash [push]" documentationQuentin Bernet via GitGitGadget, Mar 30, 2026
  14. Junio C HamanoMar 30, 2026
  15. Quentin BernetMar 30, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.