Re: [PATCH v2] docs: fix "git stash [push]" documentation
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 30, 2026, 15:18 UTC
- Message-ID
- <xmqq341hfiql.fsf@gitster.g>
- In-Reply-To
- <pull.2255.v2.git.git.1774877075694.gitgitgadget@gmail.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.
Show 7 quoted lines
> > -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.
Show 10 quoted lines
> @@ -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.
Show 6 quoted lines
> - 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.
Show 5 quoted lines
> #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