{"thread":{"id":"65357","subject":"[PATCH] docs: fix git stash grammar","startedAt":"2026-03-26T12:45:51Z","lastAt":"2026-03-30T17:19:38Z","messageCount":15,"participants":["Quentin Bernet via GitGitGadget","D. Ben Knoble","Mirko Faina","Quentin Bernet","Junio C Hamano","Ben Knoble"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"540069","messageId":"pull.2255.git.git.1774529148151.gitgitgadget@gmail.com","threadId":"65357","inReplyTo":null,"subject":"[PATCH] docs: fix git stash grammar","fromName":"Quentin Bernet via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-03-26T12:45:48Z","receivedAt":"2026-03-26T12:45:51Z","isPatch":true,"sender":{"key":"quentin.bernet@bluewin.ch","avatar":null},"body":"From: Quentin Bernet \n\nGrammar incorrectly did not include `git stash -m`\nand other valid `git stash push` flags\n\nSigned-off-by: Quentin Bernet \n---\n Fix git stash grammar\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2255%2FSporarum%2Fpatch-1-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2255/Sporarum/patch-1-v1\nPull-Request: https://github.com/git/git/pull/2255\n\n Documentation/git-stash.adoc | 4 ++--\n builtin/stash.c | 4 ++--\n 2 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc\nindex 235d57ddd8..41086c21a4 100644\n--- a/Documentation/git-stash.adoc\n+++ b/Documentation/git-stash.adoc\n@@ -14,10 +14,10 @@ git stash drop [-q | --quiet] []\n git stash pop [--index] [-q | --quiet] []\n git stash apply [--index] [-q | --quiet] []\n git stash branch []\n-git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n \t [-u | --include-untracked] [-a | --all] [(-m | --message) ]\n \t [--pathspec-from-file= [--pathspec-file-nul]]\n-\t [--] [...]]\n+\t [--] [...]\n git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n [-u | --include-untracked] [-a | --all] []\n git stash clear\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 95c5005b0b..0d27b2fb1f 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -50,10 +50,10 @@\n #define BUILTIN_STASH_STORE_USAGE \\\n \tN_(\"git stash store [(-m | --message) ] [-q | --quiet] \")\n #define BUILTIN_STASH_PUSH_USAGE \\\n-\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\tN_(\"git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n \t \" [-u | --include-untracked] [-a | --all] [(-m | --message) ]\\n\" \\\n \t \" [--pathspec-from-file= [--pathspec-file-nul]]\\n\" \\\n-\t \" [--] [...]]\")\n+\t \" [--] [...]\")\n #define BUILTIN_STASH_SAVE_USAGE \\\n \tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n \t \" [-u | --include-untracked] [-a | --all] []\")\n\nbase-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789\n-- \ngitgitgadget\n"},{"id":"540102","messageId":"CALnO6CD-5NBUoooMD+pQAxeyXCjkZ3Za6LJrLrJN57Nrz03xBw@mail.gmail.com","threadId":"65357","inReplyTo":"pull.2255.git.git.1774529148151.gitgitgadget@gmail.com","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-03-26T16:17:46Z","receivedAt":"2026-03-26T16:17:59Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":null},"body":"On Thu, Mar 26, 2026 at 8:46 AM Quentin Bernet via GitGitGadget\n wrote:\n>\n> From: Quentin Bernet \n>\n> Grammar incorrectly did not include `git stash -m`\n> and other valid `git stash push` flags\n\nTypically commits for Git describe\n- the current situation (present tense)\n- commands to make the code better\n\nIn this case, something like\n\n The grammar for \"git stash\" is incorrectly bracketed; fix it.\n\n?\n\n>\n> Signed-off-by: Quentin Bernet \n> ---\n> Fix git stash grammar\n>\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2255%2FSporarum%2Fpatch-1-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2255/Sporarum/patch-1-v1\n> Pull-Request: https://github.com/git/git/pull/2255\n>\n> Documentation/git-stash.adoc | 4 ++--\n> builtin/stash.c | 4 ++--\n> 2 files changed, 4 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc\n> index 235d57ddd8..41086c21a4 100644\n> --- a/Documentation/git-stash.adoc\n> +++ b/Documentation/git-stash.adoc\n> @@ -14,10 +14,10 @@ git stash drop [-q | --quiet] []\n> git stash pop [--index] [-q | --quiet] []\n> git stash apply [--index] [-q | --quiet] []\n> git stash branch []\n> -git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\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> - [--] [...]]\n> + [--] [...]\n> git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n> [-u | --include-untracked] [-a | --all] []\n> git stash clear\n> diff --git a/builtin/stash.c b/builtin/stash.c\n> index 95c5005b0b..0d27b2fb1f 100644\n> --- a/builtin/stash.c\n> +++ b/builtin/stash.c\n> @@ -50,10 +50,10 @@\n> #define BUILTIN_STASH_STORE_USAGE \\\n> N_(\"git stash store [(-m | --message) ] [-q | --quiet] \")\n> #define BUILTIN_STASH_PUSH_USAGE \\\n> - N_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n> + N_(\"git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n> \" [-u | --include-untracked] [-a | --all] [(-m | --message) ]\\n\" \\\n> \" [--pathspec-from-file= [--pathspec-file-nul]]\\n\" \\\n> - \" [--] [...]]\")\n> + \" [--] [...]\")\n> #define BUILTIN_STASH_SAVE_USAGE \\\n> N_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n> \" [-u | --include-untracked] [-a | --all] []\")\n>\n> base-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789\n> --\n> gitgitgadget\n\nNow, _is_ the grammar bracketed wrong? \"git help stash\" says\n\n For quickly making a snapshot, you can omit \"push\". In this mode,\n non-option arguments are not allowed to prevent a misspelled\n subcommand from making an unwanted stash entry. The two exceptions\n to this are stash -p which acts as alias for stash push -p and\n pathspec elements, which are allowed after a double hyphen -- for\n disambiguation.\n\nSo _if_ you want to provide options (other than \"-p\"), the \"push\" is\nrequired. I think the existing brackets indicate that.\n\n-- \nD. Ben Knoble\n"},{"id":"540157","messageId":"acXIl2cuBv0ifiK6@exploit","threadId":"65357","inReplyTo":"CALnO6CD-5NBUoooMD+pQAxeyXCjkZ3Za6LJrLrJN57Nrz03xBw@mail.gmail.com","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Mirko Faina","fromEmail":"mroik@delayed.space","sentAt":"2026-03-27T00:04:51Z","receivedAt":"2026-03-27T00:04:57Z","isPatch":true,"sender":{"key":"mroik@delayed.space","avatar":null},"body":"On Thu, Mar 26, 2026 at 12:17:46PM -0400, D. Ben Knoble wrote:\n> Now, _is_ the grammar bracketed wrong? \"git help stash\" says\n> \n> For quickly making a snapshot, you can omit \"push\". In this mode,\n> non-option arguments are not allowed to prevent a misspelled\n> subcommand from making an unwanted stash entry. The two exceptions\n> to this are stash -p which acts as alias for stash push -p and\n> pathspec elements, which are allowed after a double hyphen -- for\n> disambiguation.\n> \n> So _if_ you want to provide options (other than \"-p\"), the \"push\" is\n> required. I think the existing brackets indicate that.\n\nWhen it says \"In this mode, non-option arguments are not allowed\"\nwouldn't -m be allowed as it is an option and not a non-option? In fact\nif we do try to run \"git stash -m something\" it does correctly stash\nwhile if we do something like \"git stash pathspec\" it does give back\n\"fatal: subcommand wasn't specified; 'push' can't be assumed due to\nunexpected token 'pathspec'\".\n\nIf that is the case then there is an issue with the way the usage\ntooltip shows the optionality of \"push\".\n"},{"id":"540172","messageId":"ce083a4a-321d-4c29-af04-decfab33d237@bluewin.ch","threadId":"65357","inReplyTo":"CALnO6CD-5NBUoooMD+pQAxeyXCjkZ3Za6LJrLrJN57Nrz03xBw@mail.gmail.com","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Quentin Bernet","fromEmail":"quentin.bernet@bluewin.ch","sentAt":"2026-03-27T08:25:09Z","receivedAt":"2026-03-27T08:27:18Z","isPatch":true,"sender":{"key":"quentin.bernet@bluewin.ch","avatar":null},"body":"This seems to be describing more the content of the patch than the \nintention behind it, what about:\n\nThe grammar for \"git stash\" does not contain valid combinations such as\n\"git stash --include-untracked\"; fix it\n\nOn 3/26/26 17:17, D. Ben Knoble wrote:\n> On Thu, Mar 26, 2026 at 8:46 AM Quentin Bernet via GitGitGadget\n> wrote:\n>> From: Quentin Bernet \n>>\n>> Grammar incorrectly did not include `git stash -m`\n>> and other valid `git stash push` flags\n> Typically commits for Git describe\n> - the current situation (present tense)\n> - commands to make the code better\n>\n> In this case, something like\n>\n> The grammar for \"git stash\" is incorrectly bracketed; fix it.\n>\n> ?\n>\n>> Signed-off-by: Quentin Bernet \n>> ---\n>> Fix git stash grammar\n>>\n>> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2255%2FSporarum%2Fpatch-1-v1\n>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2255/Sporarum/patch-1-v1\n>> Pull-Request: https://github.com/git/git/pull/2255\n>>\n>> Documentation/git-stash.adoc | 4 ++--\n>> builtin/stash.c | 4 ++--\n>> 2 files changed, 4 insertions(+), 4 deletions(-)\n>>\n>> diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc\n>> index 235d57ddd8..41086c21a4 100644\n>> --- a/Documentation/git-stash.adoc\n>> +++ b/Documentation/git-stash.adoc\n>> @@ -14,10 +14,10 @@ git stash drop [-q | --quiet] []\n>> git stash pop [--index] [-q | --quiet] []\n>> git stash apply [--index] [-q | --quiet] []\n>> git stash branch []\n>> -git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\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>> - [--] [...]]\n>> + [--] [...]\n>> git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n>> [-u | --include-untracked] [-a | --all] []\n>> git stash clear\n>> diff --git a/builtin/stash.c b/builtin/stash.c\n>> index 95c5005b0b..0d27b2fb1f 100644\n>> --- a/builtin/stash.c\n>> +++ b/builtin/stash.c\n>> @@ -50,10 +50,10 @@\n>> #define BUILTIN_STASH_STORE_USAGE \\\n>> N_(\"git stash store [(-m | --message) ] [-q | --quiet] \")\n>> #define BUILTIN_STASH_PUSH_USAGE \\\n>> - N_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n>> + N_(\"git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n>> \" [-u | --include-untracked] [-a | --all] [(-m | --message) ]\\n\" \\\n>> \" [--pathspec-from-file= [--pathspec-file-nul]]\\n\" \\\n>> - \" [--] [...]]\")\n>> + \" [--] [...]\")\n>> #define BUILTIN_STASH_SAVE_USAGE \\\n>> N_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n>> \" [-u | --include-untracked] [-a | --all] []\")\n>>\n>> base-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789\n>> --\n>> gitgitgadget\n> Now, _is_ the grammar bracketed wrong? \"git help stash\" says\n>\n> For quickly making a snapshot, you can omit \"push\". In this mode,\n> non-option arguments are not allowed to prevent a misspelled\n> subcommand from making an unwanted stash entry. The two exceptions\n> to this are stash -p which acts as alias for stash push -p and\n> pathspec elements, which are allowed after a double hyphen -- for\n> disambiguation.\n>\n> So _if_ you want to provide options (other than \"-p\"), the \"push\" is\n> required. I think the existing brackets indicate that.\n>\n"},{"id":"540185","messageId":"xmqqqzp5mfh5.fsf@gitster.g","threadId":"65357","inReplyTo":"acXIl2cuBv0ifiK6@exploit","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-27T15:58:30Z","receivedAt":"2026-03-27T15:58:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":null},"body":"Mirko Faina writes:\n\n> On Thu, Mar 26, 2026 at 12:17:46PM -0400, D. Ben Knoble wrote:\n>> Now, _is_ the grammar bracketed wrong? \"git help stash\" says\n>> \n>> For quickly making a snapshot, you can omit \"push\". In this mode,\n>> non-option arguments are not allowed to prevent a misspelled\n>> subcommand from making an unwanted stash entry. The two exceptions\n>> to this are stash -p which acts as alias for stash push -p and\n>> pathspec elements, which are allowed after a double hyphen -- for\n>> disambiguation.\n>> \n>> So _if_ you want to provide options (other than \"-p\"), the \"push\" is\n>> required. I think the existing brackets indicate that.\n>\n> When it says \"In this mode, non-option arguments are not allowed\"\n> wouldn't -m be allowed as it is an option and not a non-option? In fact\n> if we do try to run \"git stash -m something\" it does correctly stash\n> while if we do something like \"git stash pathspec\" it does give back\n> \"fatal: subcommand wasn't specified; 'push' can't be assumed due to\n> unexpected token 'pathspec'\".\n>\n> If that is the case then there is an issue with the way the usage\n> tooltip shows the optionality of \"push\".\n\nYup, you're right. The current SYNOPSIS suggests that you can omit\nand say \"git stash\" and it does the \"push\" thing, but when you want\nto give any \"push\" related options, the command name \"push\" becomes\nmandatory before them.\n\nIf the log message said something like\n\n The \"[optionality]\" bracket is misplaced on the command line for\n \"git stash push\" in the synopsis section. It is not like you\n can omit \"push\" only when you do not give any options and\n arguments.\n\nwe wouldn't be having this long thread, I suspect.\n"},{"id":"540197","messageId":"fbe531eb-b742-4cd1-ab6a-2eaaf8d236c5@bluewin.ch","threadId":"65357","inReplyTo":"xmqqqzp5mfh5.fsf@gitster.g","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Quentin Bernet","fromEmail":"quentin.bernet@bluewin.ch","sentAt":"2026-03-27T16:28:05Z","receivedAt":"2026-03-27T16:30:14Z","isPatch":true,"sender":{"key":"quentin.bernet@bluewin.ch","avatar":null},"body":"Please keep in mind this is my first contribution to git, and learning \nthe ways things are done here, so things might take more time than usual\n\nI believe to be fully correct, this should be the grammar:\n(or some other ordering)\n\n\n  [synopsis]\n+git stash [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | \n--quiet]\n+            [-u | --include-untracked] [-a | --all] [(-m | --message) \n]\n+            [--pathspec-from-file= [--pathspec-file-nul]]\n+            [-- ...]\n  git stash list []\n  git stash show [-u | --include-untracked | --only-untracked] \n[] []\n  git stash drop [-q | --quiet] []\n  git stash pop [--index] [-q | --quiet] []\n  git stash apply [--index] [-q | --quiet] []\n  git stash branch []\n-git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] \n[-q | --quiet]\n+git stash push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] \n[-q | --quiet]\n              [-u | --include-untracked] [-a | --all] [(-m | --message) \n]\n              [--pathspec-from-file= [--pathspec-file-nul]]\n-            [--] [...]]\n+            [--] [...]\n  git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] \n[-q | --quiet]\n             [-u | --include-untracked] [-a | --all] []\n  git stash clear\n\nYou'll note the difference between the \"stash\" and \"stash push\" options \nis \"[-- ...]\" vs \"[--] [...]\", which corresponds to\n\n            For quickly making a snapshot, you can omit \"push\". In this \nmode,\n            non-option arguments are not allowed to prevent a misspelled\n            subcommand from making an unwanted stash entry. The two \nexceptions\n            to this are stash -p which acts as alias for stash push -p and\n            pathspec elements, which are allowed after a double hyphen \n-- for\n            disambiguation.\n\nThe wording seems a bit weird, since the only non-option arguments are \n\"...\", which it later explains are allowed (but require double \nhypen)\n\n\nThis grammar is better at highlighting `git stash` on its own is valid, \nbut worse at showing that the flags are almost the same\nI don't think we can do better grammar-wise, since \"push\" is at the very \nstart, and \"--\" at the end, and grammars don't have memory\n\nMy previous, simpler, grammar included \"git stash \" even \nthough it is not valid.\nMaybe that is an acceptable trade-off for clarity (although I assume not)\n\nOn 3/27/26 16:58, Junio C Hamano wrote:\n> Mirko Faina writes:\n>\n>> On Thu, Mar 26, 2026 at 12:17:46PM -0400, D. Ben Knoble wrote:\n>>> Now, _is_ the grammar bracketed wrong? \"git help stash\" says\n>>>\n>>> For quickly making a snapshot, you can omit \"push\". In this mode,\n>>> non-option arguments are not allowed to prevent a misspelled\n>>> subcommand from making an unwanted stash entry. The two exceptions\n>>> to this are stash -p which acts as alias for stash push -p and\n>>> pathspec elements, which are allowed after a double hyphen -- for\n>>> disambiguation.\n>>>\n>>> So _if_ you want to provide options (other than \"-p\"), the \"push\" is\n>>> required. I think the existing brackets indicate that.\n>> When it says \"In this mode, non-option arguments are not allowed\"\n>> wouldn't -m be allowed as it is an option and not a non-option? In fact\n>> if we do try to run \"git stash -m something\" it does correctly stash\n>> while if we do something like \"git stash pathspec\" it does give back\n>> \"fatal: subcommand wasn't specified; 'push' can't be assumed due to\n>> unexpected token 'pathspec'\".\n>>\n>> If that is the case then there is an issue with the way the usage\n>> tooltip shows the optionality of \"push\".\n> Yup, you're right. The current SYNOPSIS suggests that you can omit\n> and say \"git stash\" and it does the \"push\" thing, but when you want\n> to give any \"push\" related options, the command name \"push\" becomes\n> mandatory before them.\n>\n> If the log message said something like\n>\n> The \"[optionality]\" bracket is misplaced on the command line for\n> \"git stash push\" in the synopsis section. It is not like you\n> can omit \"push\" only when you do not give any options and\n> arguments.\n>\n> we wouldn't be having this long thread, I suspect.\n"},{"id":"540202","messageId":"4B4B5BCF-BC0C-42A1-A6F1-52FF96EF0BFC@gmail.com","threadId":"65357","inReplyTo":"acXIl2cuBv0ifiK6@exploit","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-03-27T16:47:48Z","receivedAt":"2026-03-27T16:48:00Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":null},"body":"\n> \n> Le 26 mars 2026 à 20:04, Mirko Faina a écrit :\n> \n> On Thu, Mar 26, 2026 at 12:17:46PM -0400, D. Ben Knoble wrote:\n>> Now, _is_ the grammar bracketed wrong? \"git help stash\" says\n>> \n>> For quickly making a snapshot, you can omit \"push\". In this mode,\n>> non-option arguments are not allowed to prevent a misspelled\n>> subcommand from making an unwanted stash entry. The two exceptions\n>> to this are stash -p which acts as alias for stash push -p and\n>> pathspec elements, which are allowed after a double hyphen -- for\n>> disambiguation.\n>> \n>> So _if_ you want to provide options (other than \"-p\"), the \"push\" is\n>> required. I think the existing brackets indicate that.\n> \n> When it says \"In this mode, non-option arguments are not allowed\"\n> wouldn't -m be allowed as it is an option and not a non-option? In fact\n> if we do try to run \"git stash -m something\" it does correctly stash\n> while if we do something like \"git stash pathspec\" it does give back\n> \"fatal: subcommand wasn't specified; 'push' can't be assumed due to\n> unexpected token 'pathspec'\".\n> \n> If that is the case then there is an issue with the way the usage\n> tooltip shows the optionality of \"push\".\n\nIndeed, thanks. "},{"id":"540204","messageId":"xmqq7bqxkyd5.fsf@gitster.g","threadId":"65357","inReplyTo":"fbe531eb-b742-4cd1-ab6a-2eaaf8d236c5@bluewin.ch","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-27T16:53:26Z","receivedAt":"2026-03-27T16:53:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":null},"body":"Quentin Bernet writes:\n\n> My previous, simpler, grammar included \"git stash \" even \n> though it is not valid.\n\n\"git stash -- path1 path2 ...\" is valid and is taken as elliding the\nsubcommand name 'push'. So I think your previous one is good enough\nbut the command line description needs to mention that. Double dash\nis used to signal the start of pathspec when ambiguous, and it is a\ngood example to highlight when it is useful. Without disambiguating\n\"--\", \"path1\" might be misspelt subcommand name but we cannot tell\nwhich one. You may even have a file whose name is \"pop\", and \"git\nstash -- pop\" would be a way to save away the changes to the file\nwithout having to say \"push\" explicitly ;-)\n\n"},{"id":"540205","messageId":"9d0befb7-4f2b-4b47-bf9c-784fcacfe418@bluewin.ch","threadId":"65357","inReplyTo":"xmqq7bqxkyd5.fsf@gitster.g","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Quentin Bernet","fromEmail":"quentin.bernet@bluewin.ch","sentAt":"2026-03-27T16:58:19Z","receivedAt":"2026-03-27T17:00:28Z","isPatch":true,"sender":{"key":"quentin.bernet@bluewin.ch","avatar":null},"body":"Just so we're clear: my previous grammar did allow \"git stash path1 \npath2\" (no \"push\", no \"--\"), which is not allowed\nDo you still think it is good enough ?\n\n\"the command line description needs to mention that.\" that is already \nthe case, no ?\n\nOn 3/27/26 17:53, Junio C Hamano wrote:\n> Quentin Bernet writes:\n>\n>> My previous, simpler, grammar included \"git stash \" even\n>> though it is not valid.\n> \"git stash -- path1 path2 ...\" is valid and is taken as elliding the\n> subcommand name 'push'. So I think your previous one is good enough\n> but the command line description needs to mention that. Double dash\n> is used to signal the start of pathspec when ambiguous, and it is a\n> good example to highlight when it is useful. Without disambiguating\n> \"--\", \"path1\" might be misspelt subcommand name but we cannot tell\n> which one. You may even have a file whose name is \"pop\", and \"git\n> stash -- pop\" would be a way to save away the changes to the file\n> without having to say \"push\" explicitly ;-)\n>\n"},{"id":"540207","messageId":"xmqqtsu1jipp.fsf@gitster.g","threadId":"65357","inReplyTo":"9d0befb7-4f2b-4b47-bf9c-784fcacfe418@bluewin.ch","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-27T17:16:50Z","receivedAt":"2026-03-27T17:16:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":null},"body":"Quentin Bernet writes:\n\n> Just so we're clear: my previous grammar did allow \"git stash path1 \n> path2\" (no \"push\", no \"--\"), which is not allowed\n> Do you still think it is good enough ?\n\nAbsolutely.\n\nIt is not huge enough issue to warrant separating synopsis form for\npush into two almost identical pairs, and having to maintain both of\nthem. It would be sufficient to make sure the readers understand\nthat they may have to disambiguate pathspec with \"--\" like any other\ncommand (like \"git log foo\" when you have both file \"foo\" and tag\n\"foo\") in the description part.\n\nOne thing that we may want to fix in the code is that we probably do\nnot want to require \"--\" when doing something like\n\n git stash -m foo \n\nto assume that it is a lazy \"push\" that does not say \"push\".\nCurrently we complain against the lack of subcommand name.\n\nOnce \"-m\" (i.e., a potential option) is seen before seeing any\nsubcommand, we can commit to treat it as a lazy \"push\", and have the\nparser pretend as if we got\n\n git stash push -m foo \n\nWe may see \"git stash -m foo --no-such-option garbage arge\" and the\noption and argument parser of \"git stash push\" becomes responsible\nfor complaining about such a command line.\n\n#leftoverbits obviously.\n\n"},{"id":"540208","messageId":"6b5a5bd8-0631-4c1b-b87b-c75d99dc9c50@bluewin.ch","threadId":"65357","inReplyTo":"xmqqtsu1jipp.fsf@gitster.g","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Quentin Bernet","fromEmail":"quentin.bernet@bluewin.ch","sentAt":"2026-03-27T17:36:54Z","receivedAt":"2026-03-27T17:36:56Z","isPatch":true,"sender":{"key":"quentin.bernet@bluewin.ch","avatar":null},"body":"I'm assuming \"#leftoverbits\" means \"this is something that would be \nnice, but which is for another time\"\nAnd I'll leave the pleasure of implementing that to someone more \nwell-versed in C and git internals !\n\n\nTherefore my previous change (current status of the github PR) works, as \na reminder, here it is:\n\n\ndiff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc\nindex 235d57ddd8..41086c21a4 100644\n--- a/Documentation/git-stash.adoc\n+++ b/Documentation/git-stash.adoc\n@@ -14,10 +14,10 @@ git stash drop [-q | --quiet] []\n  git stash pop [--index] [-q | --quiet] []\n  git stash apply [--index] [-q | --quiet] []\n  git stash branch []\n-git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] \n[-q | --quiet]\n+git stash [push] [-p | --patch] [-S | --staged] [-k | \n--[no-]keep-index] [-q | --quiet]\n              [-u | --include-untracked] [-a | --all] [(-m | --message) \n]\n              [--pathspec-from-file= [--pathspec-file-nul]]\n-            [--] [...]]\n+            [--] [...]\n  git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] \n[-q | --quiet]\n             [-u | --include-untracked] [-a | --all] []\n  git stash clear\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 95c5005b0b..0d27b2fb1f 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -50,10 +50,10 @@\n  #define BUILTIN_STASH_STORE_USAGE \\\n         N_(\"git stash store [(-m | --message) ] [-q | --quiet] \n\")\n  #define BUILTIN_STASH_PUSH_USAGE \\\n-       N_(\"git stash [push [-p | --patch] [-S | --staged] [-k | \n--[no-]keep-index] [-q | --quiet]\\n\" \\\n+       N_(\"git stash [push] [-p | --patch] [-S | --staged] [-k | \n--[no-]keep-index] [-q | --quiet]\\n\" \\\n            \"          [-u | --include-untracked] [-a | --all] [(-m | \n--message) ]\\n\" \\\n            \"          [--pathspec-from-file= \n[--pathspec-file-nul]]\\n\" \\\n-          \"          [--] [...]]\")\n+          \"          [--] [...]\")\n  #define BUILTIN_STASH_SAVE_USAGE \\\n         N_(\"git stash save [-p | --patch] [-S | --staged] [-k | \n--[no-]keep-index] [-q | --quiet]\\n\" \\\n            \"          [-u | --include-untracked] [-a | --all] []\")\n\n\nIs there something else I should do ?\n\n\nOn 3/27/26 18:16, Junio C Hamano wrote:\n> Quentin Bernet writes:\n>\n>> Just so we're clear: my previous grammar did allow \"git stash path1\n>> path2\" (no \"push\", no \"--\"), which is not allowed\n>> Do you still think it is good enough ?\n> Absolutely.\n>\n> It is not huge enough issue to warrant separating synopsis form for\n> push into two almost identical pairs, and having to maintain both of\n> them. It would be sufficient to make sure the readers understand\n> that they may have to disambiguate pathspec with \"--\" like any other\n> command (like \"git log foo\" when you have both file \"foo\" and tag\n> \"foo\") in the description part.\n>\n> One thing that we may want to fix in the code is that we probably do\n> not want to require \"--\" when doing something like\n>\n> git stash -m foo \n>\n> to assume that it is a lazy \"push\" that does not say \"push\".\n> Currently we complain against the lack of subcommand name.\n>\n> Once \"-m\" (i.e., a potential option) is seen before seeing any\n> subcommand, we can commit to treat it as a lazy \"push\", and have the\n> parser pretend as if we got\n>\n> git stash push -m foo \n>\n> We may see \"git stash -m foo --no-such-option garbage arge\" and the\n> option and argument parser of \"git stash push\" becomes responsible\n> for complaining about such a command line.\n>\n> #leftoverbits obviously.\n>\n"},{"id":"540209","messageId":"xmqqpl4pjhef.fsf@gitster.g","threadId":"65357","inReplyTo":"6b5a5bd8-0631-4c1b-b87b-c75d99dc9c50@bluewin.ch","subject":"Re: [PATCH] docs: fix git stash grammar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-27T17:45:12Z","receivedAt":"2026-03-27T17:45:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":null},"body":"Quentin Bernet writes:\n\n[administrivia] don't top post.\n\n> I'm assuming \"#leftoverbits\" means \"this is something that would be \n> nice, but which is for another time\"\n> And I'll leave the pleasure of implementing that to someone more \n> well-versed in C and git internals !\n>\n>\n> Therefore my previous change (current status of the github PR) works, as \n> a reminder, here it is:\n> ...\n>\n> diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc\n> ...\n>  git stash clear\n> ...\n> Is there something else I should do ?\n\nWithout any additional effort on top of what we saw in the previous\npatch, I am not sure if ...\n\n>> ... It would be sufficient to make sure the readers understand\n>> that they may have to disambiguate pathspec with \"--\" like any other\n>> command (like \"git log foo\" when you have both file \"foo\" and tag\n>> \"foo\") in the description part.\n\n... is already achieved.\n\nAlso, my earlier \"if the log message said ..., we wouldn't be having\nthis long thread\" comment still stands.\n\n https://lore.kernel.org/git/xmqqqzp5mfh5.fsf@gitster.g/\n\nThanks.\n"},{"id":"540388","messageId":"pull.2255.v2.git.git.1774877075694.gitgitgadget@gmail.com","threadId":"65357","inReplyTo":"pull.2255.git.git.1774529148151.gitgitgadget@gmail.com","subject":"[PATCH v2] docs: fix \"git stash [push]\" documentation","fromName":"Quentin Bernet via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-03-30T13:24:35Z","receivedAt":"2026-03-30T13:24:39Z","isPatch":true,"sender":{"key":"quentin.bernet@bluewin.ch","avatar":null},"body":"From: Quentin Bernet \n\nBoth the synopsis and explanation are incorrect and contradict each\nother.\nThe synopsis claims \"push\" can only be omitted when you do not give any\noptions and arguments.\nThe explanation correctly claims that non-option arguments are not\nallowed, except pathspec elements preceded by double hyphens.\nBut it also adds \"-p\" to the list of exceptions, even though it is an\noption argument.\n\nSigned-off-by: Quentin Bernet \n---\n Fix git stash grammar\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2255%2FSporarum%2Fpatch-1-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2255/Sporarum/patch-1-v2\nPull-Request: https://github.com/git/git/pull/2255\n\nRange-diff vs v1:\n\n 1: e30696d3c4 ! 1: 927410a49d docs: fix git stash grammar\n @@ Metadata\n Author: Quentin Bernet \n \n ## Commit message ##\n - docs: fix git stash grammar\n + docs: fix \"git stash [push]\" documentation\n \n - Grammar incorrectly did not include `git stash -m`\n - and other valid `git stash push` flags\n + Both the synopsis and explanation are incorrect and contradict each\n + other.\n + The synopsis claims \"push\" can only be omitted when you do not give any\n + options and arguments.\n + The explanation correctly claims that non-option arguments are not\n + allowed, except pathspec elements preceded by double hyphens.\n + But it also adds \"-p\" to the list of exceptions, even though it is an\n + option argument.\n \n Signed-off-by: Quentin Bernet \n \n @@ Documentation/git-stash.adoc: git stash drop [-q | --quiet] []\n git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n [-u | --include-untracked] [-a | --all] []\n git stash clear\n +@@ Documentation/git-stash.adoc: COMMANDS\n + \tthe description along with the stashed state.\n + +\n + For quickly making a snapshot, you can omit \"push\". In this mode,\n +-non-option arguments are not allowed to prevent a misspelled\n +-subcommand from making an unwanted stash entry. The two exceptions to this\n +-are `stash -p` which acts as alias for `stash push -p` and pathspec elements,\n +-which are allowed after a double hyphen `--` for disambiguation.\n ++pathspec elements are only allowed after a double hyphen `--`\n ++to prevent a misspelled subcommand from making an unwanted stash entry.\n + \n + `save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [-a | --all] [-q | --quiet] []`::\n + \n \n ## builtin/stash.c ##\n @@\n\n\n Documentation/git-stash.adoc | 10 ++++------\n builtin/stash.c | 4 ++--\n 2 files changed, 6 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc\nindex 235d57ddd8..b05c990ecd 100644\n--- a/Documentation/git-stash.adoc\n+++ b/Documentation/git-stash.adoc\n@@ -14,10 +14,10 @@ git stash drop [-q | --quiet] []\n git stash pop [--index] [-q | --quiet] []\n git stash apply [--index] [-q | --quiet] []\n git stash branch []\n-git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n \t [-u | --include-untracked] [-a | --all] [(-m | --message) ]\n \t [--pathspec-from-file= [--pathspec-file-nul]]\n-\t [--] [...]]\n+\t [--] [...]\n git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n [-u | --include-untracked] [-a | --all] []\n git stash clear\n@@ -60,10 +60,8 @@ COMMANDS\n \tthe description along with the stashed state.\n +\n For quickly making a snapshot, you can omit \"push\". In this mode,\n-non-option arguments are not allowed to prevent a misspelled\n-subcommand from making an unwanted stash entry. The two exceptions to this\n-are `stash -p` which acts as alias for `stash push -p` and pathspec elements,\n-which are allowed after a double hyphen `--` for disambiguation.\n+pathspec elements are only allowed after a double hyphen `--`\n+to prevent a misspelled subcommand from making an unwanted stash entry.\n \n `save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [-a | --all] [-q | --quiet] []`::\n \ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 95c5005b0b..0d27b2fb1f 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -50,10 +50,10 @@\n #define BUILTIN_STASH_STORE_USAGE \\\n \tN_(\"git stash store [(-m | --message) ] [-q | --quiet] \")\n #define BUILTIN_STASH_PUSH_USAGE \\\n-\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\tN_(\"git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n \t \" [-u | --include-untracked] [-a | --all] [(-m | --message) ]\\n\" \\\n \t \" [--pathspec-from-file= [--pathspec-file-nul]]\\n\" \\\n-\t \" [--] [...]]\")\n+\t \" [--] [...]\")\n #define BUILTIN_STASH_SAVE_USAGE \\\n \tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n \t \" [-u | --include-untracked] [-a | --all] []\")\n\nbase-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789\n-- \ngitgitgadget\n"},{"id":"540393","messageId":"xmqq341hfiql.fsf@gitster.g","threadId":"65357","inReplyTo":"pull.2255.v2.git.git.1774877075694.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] docs: fix \"git stash [push]\" documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-30T15:18:58Z","receivedAt":"2026-03-30T15:19:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":null},"body":"\"Quentin Bernet via GitGitGadget\" writes:\n\n> But it also adds \"-p\" to the list of exceptions, even though it is an\n> option argument.\n\nThis point I did not notice before, and you are right. We already\nsaid that we reject non-option arguments, and \"-p\" is by no means\nspecial among other options. Good spotting.\n\n>\n> -git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n> +git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n> \t [-u | --include-untracked] [-a | --all] [(-m | --message) ]\n> \t [--pathspec-from-file= [--pathspec-file-nul]]\n> -\t [--] [...]]\n> +\t [--] [...]\n\nOK. So the first '[' was closed after the entire thing, but now it\ncloses after [push], making it clear that the command word can be\nomitted without affecting the remainder.\n\n> @@ -60,10 +60,8 @@ COMMANDS\n> \tthe description along with the stashed state.\n> +\n> For quickly making a snapshot, you can omit \"push\". In this mode,\n> -non-option arguments are not allowed to prevent a misspelled\n> -subcommand from making an unwanted stash entry. The two exceptions to this\n> -are `stash -p` which acts as alias for `stash push -p` and pathspec elements,\n> -which are allowed after a double hyphen `--` for disambiguation.\n> +pathspec elements are only allowed after a double hyphen `--`\n> +to prevent a misspelled subcommand from making an unwanted stash entry.\n\nOK. I personally think \"for disambiguation\" in the original is\nclear enough, but the rephrased version is not excessively verbose,\nso let's take it.\n\n> -\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n> +\tN_(\"git stash [push] [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n> \t \" [-u | --include-untracked] [-a | --all] [(-m | --message) ]\\n\" \\\n> \t \" [--pathspec-from-file= [--pathspec-file-nul]]\\n\" \\\n> -\t \" [--] [...]]\")\n> +\t \" [--] [...]\")\n\nOK. Looking ver good. Does this excatly match what we have in the\ndocumentation? I think we have a test for it, but I do not offhand\nrecall it covers \"git stash\".\n\nThanks. Will queue.\n\n\n> #define BUILTIN_STASH_SAVE_USAGE \\\n> \tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n> \t \" [-u | --include-untracked] [-a | --all] []\")\n>\n> base-commit: ce74208c2fa13943fffa58f168ac27a76d0eb789\n"},{"id":"540403","messageId":"d99d841f-4284-4734-a34f-4cd1d5c36938@bluewin.ch","threadId":"65357","inReplyTo":"xmqq341hfiql.fsf@gitster.g","subject":"Re: [PATCH v2] docs: fix \"git stash [push]\" documentation","fromName":"Quentin Bernet","fromEmail":"quentin.bernet@bluewin.ch","sentAt":"2026-03-30T17:19:30Z","receivedAt":"2026-03-30T17:19:38Z","isPatch":true,"sender":{"key":"quentin.bernet@bluewin.ch","avatar":null},"body":" > Looking ver good.  Does this excatly match what we have in the\n > documentation?  I think we have a test for it, but I do not offhand\n > recall it covers \"git stash\".\n\nThere is a test for it, at least on the github repo (I wouldn't have \nknown to change the c file otherwise)\n\n > Thanks.  Will queue.\n\nNice perfect !\n\n"}]}