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

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

From
Quentin Bernet via GitGitGadget <gitgitgadget@gmail.com>
Date
Mar 30, 2026, 13:24 UTC
Message-ID
<pull.2255.v2.git.git.1774877075694.gitgitgadget@gmail.com>
In-Reply-To
<pull.2255.git.git.1774529148151.gitgitgadget@gmail.com>
From: Quentin Bernet <quentin.bernet@bluewin.ch>

Both the synopsis and explanation are incorrect and contradict each other. The synopsis claims "push" can only be omitted when you do not give any options and arguments. The explanation correctly claims that non-option arguments are not allowed, except pathspec elements preceded by double hyphens. But it also adds "-p" to the list of exceptions, even though it is an option argument.

Signed-off-by: Quentin Bernet <quentin.bernet@bluewin.ch>
---
    Fix git stash grammar
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2255%2FSporarum%2Fpatch-1-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2255/Sporarum/patch-1-v2
Pull-Request: https://github.com/git/git/pull/2255
Range-diff vs v1:
 1:  e30696d3c4 ! 1:  927410a49d docs: fix git stash grammar
     @@ Metadata
      Author: Quentin Bernet <quentin.bernet@bluewin.ch>
      
       ## Commit message ##
     -    docs: fix git stash grammar
     +    docs: fix "git stash [push]" documentation
      
     -    Grammar incorrectly did not include `git stash -m`
     -    and other valid `git stash push` flags
     +    Both the synopsis and explanation are incorrect and contradict each
     +    other.
     +    The synopsis claims "push" can only be omitted when you do not give any
     +    options and arguments.
     +    The explanation correctly claims that non-option arguments are not
     +    allowed, except pathspec elements preceded by double hyphens.
     +    But it also adds "-p" to the list of exceptions, even though it is an
     +    option argument.
      
          Signed-off-by: Quentin Bernet <quentin.bernet@bluewin.ch>
      
     @@ Documentation/git-stash.adoc: git stash drop [-q | --quiet] [<stash>]
       git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
                  [-u | --include-untracked] [-a | --all] [<message>]
       git stash clear
     +@@ Documentation/git-stash.adoc: 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.
     + 
     + `save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [-a | --all] [-q | --quiet] [<message>]`::
     + 
      
       ## builtin/stash.c ##
      @@
 Documentation/git-stash.adoc | 10 ++++------
 builtin/stash.c              |  4 ++--
 2 files changed, 6 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc
index 235d57ddd8..b05c990ecd 100644
--- a/Documentation/git-stash.adoc
+++ b/Documentation/git-stash.adoc
@@ -14,10 +14,10 @@ git stash drop [-q | --quiet] [<stash>]
 git stash pop [--index] [-q | --quiet] [<stash>]
 git stash apply [--index] [-q | --quiet] [<stash>]
 git stash branch <branchname> [<stash>]
-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>...]
 git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
            [-u | --include-untracked] [-a | --all] [<message>]
 git stash clear
@@ -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.
 
 `save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [-a | --all] [-q | --quiet] [<message>]`::
 
diff --git a/builtin/stash.c b/builtin/stash.c
index 95c5005b0b..0d27b2fb1f 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -50,10 +50,10 @@
 #define BUILTIN_STASH_STORE_USAGE \
 	N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>")
 #define BUILTIN_STASH_PUSH_USAGE \
-	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>...]")
 #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
-- 
gitgitgadget
Previous: Quentin BernetNext: Junio C Hamano
Message 13 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.