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

Re: [PATCH] docs: fix git stash grammar

From
Junio C Hamano <gitster@pobox.com>
Date
Mar 27, 2026, 15:58 UTC
Message-ID
<xmqqqzp5mfh5.fsf@gitster.g>
In-Reply-To
<acXIl2cuBv0ifiK6@exploit>
Mirko Faina <mroik@delayed.space> writes:
Show 22 quoted lines
> 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: Mirko FainaNext: Quentin Bernet
Message 4 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.