From: Junio C Hamano Date: Mon, 30 Mar 2026 15:18:58 GMT Subject: Re: [PATCH v2] docs: fix "git stash [push]" documentation Message-ID: In-Reply-To: "Quentin Bernet via GitGitGadget" 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) ] > [--pathspec-from-file= [--pathspec-file-nul]] > - [--] [...]] > + [--] [...] 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) ]\n" \ > " [--pathspec-from-file= [--pathspec-file-nul]]\n" \ > - " [--] [...]]") > + " [--] [...]") 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] []") > > base-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789