From: Quentin Bernet Date: Fri, 27 Mar 2026 17:36:54 GMT Subject: Re: [PATCH] docs: fix git stash grammar Message-ID: <6b5a5bd8-0631-4c1b-b87b-c75d99dc9c50@bluewin.ch> In-Reply-To: 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] []  git stash pop [--index] [-q | --quiet] []  git stash apply [--index] [-q | --quiet] []  git stash branch [] -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) ]              [--pathspec-from-file= [--pathspec-file-nul]] -            [--] [...]] +            [--] [...]  git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]             [-u | --include-untracked] [-a | --all] []  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) ] [-q | --quiet] ")  #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) ]\n" \            "          [--pathspec-from-file= [--pathspec-file-nul]]\n" \ -          "          [--] [...]]") +          "          [--] [...]")  #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] []") Is there something else I should do ? On 3/27/26 18:16, Junio C Hamano wrote: > Quentin Bernet 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 > > 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 > > 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. >