Re: [PATCH v2] docs: fix "git stash [push]" documentation

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

"Quentin Bernet via GitGitGadget" <gitgitgadget@gmail.com> writes:

> But it also adds "-p" to the list of exceptions, even though it is an
> option argument.

This point I did not notice before, and you are right.  We already
said that we reject non-option arguments, and "-p" is by no means
special among other options.  Good spotting.

>
> -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>...]

OK.  So the first '[' was closed after the entire thing, but now it
closes after [push], making it clear that the command word can be
omitted without affecting the remainder.

> @@ -60,10 +60,8 @@ COMMANDS
>  	the description along with the stashed state.
>  +
>  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.
> +pathspec elements are only allowed after a double hyphen `--`
> +to prevent a misspelled subcommand from making an unwanted stash entry.

OK.  I personally think "for disambiguation" in the original is
clear enough, but the rephrased version is not excessively verbose,
so let's take it.

> -	N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
> +	N_("git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
>  	   "          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n" \
>  	   "          [--pathspec-from-file=<file> [--pathspec-file-nul]]\n" \
> -	   "          [--] [<pathspec>...]]")
> +	   "          [--] [<pathspec>...]")

OK.  Looking ver good.  Does this excatly match what we have in the
documentation?  I think we have a test for it, but I do not offhand
recall it covers "git stash".

Thanks.  Will queue.


>  #define BUILTIN_STASH_SAVE_USAGE \
>  	N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
>  	   "          [-u | --include-untracked] [-a | --all] [<message>]")
>
> base-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789