Re: [PATCH] docs: fix git stash grammar
- From
Quentin Bernet <quentin.bernet@bluewin.ch>
- Date
- Mar 27, 2026, 16:28 UTC
- Message-ID
- <fbe531eb-b742-4cd1-ab6a-2eaaf8d236c5@bluewin.ch>
- In-Reply-To
- <xmqqqzp5mfh5.fsf@gitster.g>
Please keep in mind this is my first contribution to git, and learning the ways things are done here, so things might take more time than usual
I believe to be fully correct, this should be the grammar: (or some other ordering)
[synopsis] +git stash [-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>...] git stash list [<log-options>] git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>] 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
You'll note the difference between the "stash" and "stash push" options is "[-- <pathspec>...]" vs "[--] [<pathspec>...]", which corresponds to
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.
The wording seems a bit weird, since the only non-option arguments are "<pathspec>...", which it later explains are allowed (but require double hypen)
This grammar is better at highlighting `git stash` on its own is valid, but worse at showing that the flags are almost the same I don't think we can do better grammar-wise, since "push" is at the very start, and "--" at the end, and grammars don't have memory
My previous, simpler, grammar included "git stash <pathspec>" even though it is not valid. Maybe that is an acceptable trade-off for clarity (although I assume not)
On 3/27/26 16:58, Junio C Hamano wrote:
Show 36 quoted lines
> Mirko Faina <mroik@delayed.space> writes: > >> 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.