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, 17:16 UTC
Message-ID
<xmqqtsu1jipp.fsf@gitster.g>
In-Reply-To
<9d0befb7-4f2b-4b47-bf9c-784fcacfe418@bluewin.ch>
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.
Previous: Quentin BernetNext: Quentin Bernet
Message 8 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.