git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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
Previous: Quentin Bernet via GitGitGadgetNext: Quentin Bernet
Message 14 of 15 in “docs: fix git stash grammar”
  1. docs: fix git stash grammarQuentin Bernet via GitGitGadget, Mar 26, 2026
  2. D. Ben KnobleMar 26, 2026
  3. Mirko FainaMar 27, 2026
  4. Junio C HamanoMar 27, 2026
  5. Quentin BernetMar 27, 2026
  6. Junio C HamanoMar 27, 2026
  7. Quentin BernetMar 27, 2026
  8. Junio C HamanoMar 27, 2026
  9. Quentin BernetMar 27, 2026
  10. Junio C HamanoMar 27, 2026
  11. Ben KnobleMar 27, 2026
  12. Quentin BernetMar 27, 2026
  13. docs: fix "git stash [push]" documentationQuentin Bernet via GitGitGadget, Mar 30, 2026
  14. Junio C HamanoMar 30, 2026
  15. Quentin BernetMar 30, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.