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. >