Re: [PATCH] docs: fix git stash grammar
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 27, 2026, 15:58 UTC
- Message-ID
- <xmqqqzp5mfh5.fsf@gitster.g>
- In-Reply-To
- <acXIl2cuBv0ifiK6@exploit>
Mirko Faina <mroik@delayed.space> writes:
Show 22 quoted lines
> 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.