Re: [PATCH] docs: fix git stash grammar

[Junio C Hamano <gitster@pobox.com>]

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.