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, 17:36 UTC
Message-ID
<6b5a5bd8-0631-4c1b-b87b-c75d99dc9c50@bluewin.ch>
In-Reply-To
<xmqqtsu1jipp.fsf@gitster.g>

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
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>]")


Is there something else I should do ?


On 3/27/26 18:16, Junio C Hamano wrote:
> 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: Junio C HamanoNext: Junio C Hamano
Message 9 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.