From: Quentin Bernet Date: Fri, 27 Mar 2026 16:28:05 GMT Subject: Re: [PATCH] docs: fix git stash grammar Message-ID: In-Reply-To: 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) ] +            [--pathspec-from-file= [--pathspec-file-nul]] +            [-- ...]  git stash list []  git stash show [-u | --include-untracked | --only-untracked] [] []  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 You'll note the difference between the "stash" and "stash push" options is "[-- ...]" vs "[--] [...]", 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 "...", 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 " 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: > Mirko Faina 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.