Re: [PATCH] docs: fix git stash grammar

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

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.