{"thread":{"id":"46916","subject":"[RFC] deprecate git stash save? (was: Re: [PATCH 2/3] http-push: fix construction of hex value from path)","startedAt":"2017-10-05T20:00:07Z","lastAt":"2017-10-23T06:32:35Z","messageCount":30,"participants":["Thomas Gummerer","Junio C Hamano","Jeff King","Robert P. J. Day"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"329783","messageId":"20171005200049.GF30301@hank","threadId":"46916","inReplyTo":null,"subject":"[RFC] deprecate git stash save? (was: Re: [PATCH 2/3] http-push: fix construction of hex value from path)","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-05T20:00:49Z","receivedAt":"2017-10-05T20:00:07Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 10/04, Junio C Hamano wrote:\n> I do not object with such a well designed deprecation plan for any\n> other features, if there are other \"favourite\" ones people would\n> want to deprecate and eventually remove, by the way.\n\nSince you were asking :) With the introduction of 'git stash push',\nmy hope was always that we could eventually get rid of 'git stash\nsave' and only keep one interface around.\n\nAs there still many references to it around on the internet, it\nprobably requires a bit of a longer deprecation plan. What do you\nthink about the following:\n\n- Change docs/man pages to use 'git stash push' everywhere instead of\n 'git stash save'.\n- Mention the deprecation in the release notes and in the man page.\n- Print a warning when 'git stash save' is used.\n- Eventually get rid of it (maybe something for 3.0?)\n\nThe steps above would all occur sequentially with a few releases\nbetween each of them.\n\nA patch for the first step below. I think that even makes sense if we\ndon't want to follow through with the deprecation.\n\n--- >8 ---\nSubject: [PATCH] replace git stash save with git stash push in the documentation\n\ngit stash push is the newer interface for creating a stash. While we\nare still keeping git stash save around for the time being, it's better\nto point new users of git stash to the more modern (and more feature\nrich) interface, instead of teaching them the older version that we\nmight want to phase out in the future.\n\nSigned-off-by: Thomas Gummerer \n---\n Documentation/git-stash.txt | 12 ++++++------\n Documentation/gitworkflows.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n git-stash.sh | 10 +++++-----\n 4 files changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 00f95fee1f..53b2e60aeb 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -33,7 +33,7 @@ and reverts the working directory to match the `HEAD` commit.\n The modifications stashed away by this command can be listed with\n `git stash list`, inspected with `git stash show`, and restored\n (potentially on top of a different commit) with `git stash apply`.\n-Calling `git stash` without any arguments is equivalent to `git stash save`.\n+Calling `git stash` without any arguments is equivalent to `git stash push`.\n A stash is by default listed as \"WIP on 'branchname' ...\", but\n you can give a more descriptive message on the command line when\n you create one.\n@@ -118,7 +118,7 @@ pop [--index] [-q|--quiet] []::\n \n \tRemove a single stashed state from the stash list and apply it\n \ton top of the current working tree state, i.e., do the inverse\n-\toperation of `git stash save`. The working directory must\n+\toperation of `git stash push`. The working directory must\n \tmatch the index.\n +\n Applying the state can fail with conflicts; in this case, it is not\n@@ -137,7 +137,7 @@ apply [--index] [-q|--quiet] []::\n \n \tLike `pop`, but do not remove the state from the stash list. Unlike `pop`,\n \t`` may be any commit that looks like a commit created by\n-\t`stash save` or `stash create`.\n+\t`stash push` or `stash create`.\n \n branch []::\n \n@@ -148,7 +148,7 @@ branch []::\n \t`stash@{}`, it then drops the ``. When no ``\n \tis given, applies the latest one.\n +\n-This is useful if the branch on which you ran `git stash save` has\n+This is useful if the branch on which you ran `git stash push` has\n changed enough that `git stash apply` fails due to conflicts. Since\n the stash entry is applied on top of the commit that was HEAD at the\n time `git stash` was run, it restores the originally stashed state\n@@ -255,14 +255,14 @@ $ git stash pop\n \n Testing partial commits::\n \n-You can use `git stash save --keep-index` when you want to make two or\n+You can use `git stash push --keep-index` when you want to make two or\n more commits out of the changes in the work tree, and you want to test\n each change before committing:\n +\n ----------------------------------------------------------------\n # ... hack hack hack ...\n $ git add --patch foo # add just first part to the index\n-$ git stash save --keep-index # save all other changes to the stash\n+$ git stash push --keep-index # save all other changes to the stash\n $ edit/build/test first part\n $ git commit -m 'First part' # commit fully tested change\n $ git stash pop # prepare to work on all other changes\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 177610e44e..02569d0614 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -40,7 +40,7 @@ beginning. It is always easier to squash a few commits together than\n to split one big commit into several. Don't be afraid of making too\n small or imperfect steps along the way. You can always go back later\n and edit the commits with `git rebase --interactive` before you\n-publish them. You can use `git stash save --keep-index` to run the\n+publish them. You can use `git stash push --keep-index` to run the\n test suite independent of other uncommitted changes; see the EXAMPLES\n section of linkgit:git-stash[1].\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex b4d88af133..1c4e44892d 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1556,7 +1556,7 @@ so on a different branch and then coming back), unstash the\n work-in-progress changes.\n \n ------------------------------------------------\n-$ git stash save \"work in progress for foo feature\"\n+$ git stash push \"work in progress for foo feature\"\n ------------------------------------------------\n \n This command will save your changes away to the `stash`, and\ndiff --git a/git-stash.sh b/git-stash.sh\nindex 8b2ce9afda..8ce6929d7f 100755\n--- a/git-stash.sh\n+++ b/git-stash.sh\n@@ -267,11 +267,11 @@ push_stash () {\n \t\t\t# translation of \"error: \" takes in your language. E.g. in\n \t\t\t# English this is:\n \t\t\t#\n-\t\t\t# $ git stash save --blah-blah 2>&1 | head -n 2\n-\t\t\t# error: unknown option for 'stash save': --blah-blah\n-\t\t\t# To provide a message, use git stash save -- '--blah-blah'\n-\t\t\teval_gettextln \"error: unknown option for 'stash save': \\$option\n- To provide a message, use git stash save -- '\\$option'\"\n+\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n+\t\t\t# error: unknown option for 'stash push': --blah-blah\n+\t\t\t# To provide a message, use git stash push -- '--blah-blah'\n+\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n+ To provide a message, use git stash push -- '\\$option'\"\n \t\t\tusage\n \t\t\t;;\n \t\t*)\n-- \n2.14.1.480.gb18f417b89\n\n"},{"id":"329785","messageId":"20171005201029.4173-1-t.gummerer@gmail.com","threadId":"46916","inReplyTo":"20171005200049.GF30301@hank","subject":"[PATCH 2/1] mention git stash push first in the man page","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-05T20:10:29Z","receivedAt":"2017-10-05T20:09:52Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"Because 'stash push' and 'stash save' are so closely related they share one\nsection in the man page. Currently 'stash save' comes first, as that\nwas the command that people were historically using. However this makes\nthe newer, more feature rich git stash push very easy to overlook.\nChange the order to give the newer interface for creating a stash the\nmore prominent position.\n\nSigned-off-by: Thomas Gummerer \n---\n Documentation/git-stash.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 53b2e60aeb..a1ddfb8eae 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -48,8 +48,8 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).\n OPTIONS\n -------\n \n-save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message ] [--] [...]::\n+save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n \n \tSave your local modifications to a new 'stash entry' and roll them\n \tback to HEAD (in the working tree and in the index).\n-- \n2.14.1.480.gb18f417b89\n\n"},{"id":"330220","messageId":"xmqqmv4x2ngs.fsf@gitster.mtv.corp.google.com","threadId":"46916","inReplyTo":"20171005200049.GF30301@hank","subject":"Re: [RFC] deprecate git stash save?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-12T00:56:19Z","receivedAt":"2017-10-12T00:56:26Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Gummerer writes:\n\n> git stash push is the newer interface for creating a stash. While we\n> are still keeping git stash save around for the time being, it's better\n> to point new users of git stash to the more modern (and more feature\n> rich) interface, instead of teaching them the older version that we\n> might want to phase out in the future.\n\nWith devil's advocate hat on, because the primary point of \"stash\"\nbeing \"clear the desk quickly\", I do not necessarily agree that\n\"more feature rich\" is a plus and something we should nudge newbies\ntowards.\n\n\n"},{"id":"330268","messageId":"xmqqy3ogy5wf.fsf@gitster.mtv.corp.google.com","threadId":"46916","inReplyTo":"xmqqmv4x2ngs.fsf@gitster.mtv.corp.google.com","subject":"Re: [RFC] deprecate git stash save?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-12T11:14:40Z","receivedAt":"2017-10-12T11:14:47Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Thomas Gummerer writes:\n>\n>> git stash push is the newer interface for creating a stash. While we\n>> are still keeping git stash save around for the time being, it's better\n>> to point new users of git stash to the more modern (and more feature\n>> rich) interface, instead of teaching them the older version that we\n>> might want to phase out in the future.\n>\n> With devil's advocate hat on, because the primary point of \"stash\"\n> being \"clear the desk quickly\", I do not necessarily agree that\n> \"more feature rich\" is a plus and something we should nudge newbies\n> towards.\n\nI do not particulary view \"feature richness\" is the primary benefit\nof 'push' that makes it shine. 'save' has a quirk in the command\nline option syntax, but 'push' corrects it, and that is why we want\nto move users towards the latter.\n\nIOW, I do not object to the agenda; it is just I found the\njustification used to push the agenda forward was flawed.\n\nThanks.\n"},{"id":"330475","messageId":"20171016181947.GE15399@hank","threadId":"46916","inReplyTo":"xmqqy3ogy5wf.fsf@gitster.mtv.corp.google.com","subject":"Re: [RFC] deprecate git stash save?","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-16T18:19:47Z","receivedAt":"2017-10-16T18:18:54Z","isPatch":false,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 10/12, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> \n> > Thomas Gummerer writes:\n> >\n> >> git stash push is the newer interface for creating a stash. While we\n> >> are still keeping git stash save around for the time being, it's better\n> >> to point new users of git stash to the more modern (and more feature\n> >> rich) interface, instead of teaching them the older version that we\n> >> might want to phase out in the future.\n> >\n> > With devil's advocate hat on, because the primary point of \"stash\"\n> > being \"clear the desk quickly\", I do not necessarily agree that\n> > \"more feature rich\" is a plus and something we should nudge newbies\n> > towards.\n> \n> I do not particulary view \"feature richness\" is the primary benefit\n> of 'push' that makes it shine. 'save' has a quirk in the command\n> line option syntax, but 'push' corrects it, and that is why we want\n> to move users towards the latter.\n\nI agree it's not the primary benefit (hence why it's in braces :)),\nbut I at least some users will eventually want the features 'git stash\npush' has to offer, and it's better if they don't have to re-train\ntheir fingers at that point.\n\nBut yeah, fixing the quirky command line interface is definitely the\nstronger reason for deprecating it.\n\n> IOW, I do not object to the agenda; it is just I found the\n> justification used to push the agenda forward was flawed.\n\nI'm happy as long as we agree on the agenda here. Any opinions about\nthe patches themselves? Would you prefer me to resend with an updated\ndescription?\n\n> Thanks.\n"},{"id":"330515","messageId":"20171017041332.ooybecmonvssko2k@sigill.intra.peff.net","threadId":"46916","inReplyTo":"20171005200049.GF30301@hank","subject":"Re: [RFC] deprecate git stash save? (was: Re: [PATCH 2/3] http-push: fix construction of hex value from path)","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-17T04:13:33Z","receivedAt":"2017-10-17T04:13:39Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 05, 2017 at 09:00:49PM +0100, Thomas Gummerer wrote:\n\n> Since you were asking :) With the introduction of 'git stash push',\n> my hope was always that we could eventually get rid of 'git stash\n> save' and only keep one interface around.\n> \n> As there still many references to it around on the internet, it\n> probably requires a bit of a longer deprecation plan. What do you\n> think about the following:\n> \n> - Change docs/man pages to use 'git stash push' everywhere instead of\n> 'git stash save'.\n> - Mention the deprecation in the release notes and in the man page.\n> - Print a warning when 'git stash save' is used.\n> - Eventually get rid of it (maybe something for 3.0?)\n> \n> The steps above would all occur sequentially with a few releases\n> between each of them.\n\nThat sounds like a pretty good plan.\n\n> A patch for the first step below. I think that even makes sense if we\n> don't want to follow through with the deprecation.\n\nAgreed. The patch mostly looks good, except:\n\n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index b4d88af133..1c4e44892d 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -1556,7 +1556,7 @@ so on a different branch and then coming back), unstash the\n> work-in-progress changes.\n> \n> ------------------------------------------------\n> -$ git stash save \"work in progress for foo feature\"\n> +$ git stash push \"work in progress for foo feature\"\n> ------------------------------------------------\n\nThis needs \"-m\", doesn't it?\n\n> \n> This command will save your changes away to the `stash`, and\n> diff --git a/git-stash.sh b/git-stash.sh\n> index 8b2ce9afda..8ce6929d7f 100755\n> --- a/git-stash.sh\n> +++ b/git-stash.sh\n> @@ -267,11 +267,11 @@ push_stash () {\n> \t\t\t# translation of \"error: \" takes in your language. E.g. in\n> \t\t\t# English this is:\n> \t\t\t#\n> -\t\t\t# $ git stash save --blah-blah 2>&1 | head -n 2\n> -\t\t\t# error: unknown option for 'stash save': --blah-blah\n> -\t\t\t# To provide a message, use git stash save -- '--blah-blah'\n> -\t\t\teval_gettextln \"error: unknown option for 'stash save': \\$option\n> - To provide a message, use git stash save -- '\\$option'\"\n> +\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n> +\t\t\t# error: unknown option for 'stash push': --blah-blah\n> +\t\t\t# To provide a message, use git stash push -- '--blah-blah'\n> +\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n> + To provide a message, use git stash push -- '\\$option'\"\n\nAnd here, too?\n\n-Peff\n"},{"id":"330516","messageId":"20171017041405.eavuutzgzgs4ppk2@sigill.intra.peff.net","threadId":"46916","inReplyTo":"20171005201029.4173-1-t.gummerer@gmail.com","subject":"Re: [PATCH 2/1] mention git stash push first in the man page","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-17T04:14:05Z","receivedAt":"2017-10-17T04:14:11Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 05, 2017 at 09:10:29PM +0100, Thomas Gummerer wrote:\n\n> Because 'stash push' and 'stash save' are so closely related they share one\n> section in the man page. Currently 'stash save' comes first, as that\n> was the command that people were historically using. However this makes\n> the newer, more feature rich git stash push very easy to overlook.\n> Change the order to give the newer interface for creating a stash the\n> more prominent position.\n\nSeems reasonable, though if we are deprecating \"save\" should we demote\nit from being in the synopsis entirely?\n\n-Peff\n"},{"id":"330577","messageId":"20171017214515.GG15399@hank","threadId":"46916","inReplyTo":"20171017041405.eavuutzgzgs4ppk2@sigill.intra.peff.net","subject":"Re: [PATCH 2/1] mention git stash push first in the man page","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-17T21:45:15Z","receivedAt":"2017-10-17T21:44:21Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 10/17, Jeff King wrote:\n> On Thu, Oct 05, 2017 at 09:10:29PM +0100, Thomas Gummerer wrote:\n> \n> > Because 'stash push' and 'stash save' are so closely related they share one\n> > section in the man page. Currently 'stash save' comes first, as that\n> > was the command that people were historically using. However this makes\n> > the newer, more feature rich git stash push very easy to overlook.\n> > Change the order to give the newer interface for creating a stash the\n> > more prominent position.\n> \n> Seems reasonable, though if we are deprecating \"save\" should we demote\n> it from being in the synopsis entirely?\n\nI saw that as a next step, with the \"official\" deprecation of \"save\".\nI thought we might want to advertise \"push\" a bit more before actually\nofficially deprecating \"save\" and sending the deprecation notice out\nin the release notes.\n\nOTOH, dropping it from the synopsis in the man page probably wouldn't\ncause much issue, as \"push\" directly replaces it, and is easily\nvisible. Not sure how slow we want to take the deprecation?\n\n> -Peff\n"},{"id":"330578","messageId":"20171017214716.GH15399@hank","threadId":"46916","inReplyTo":"20171017041332.ooybecmonvssko2k@sigill.intra.peff.net","subject":"Re: [RFC] deprecate git stash save? (was: Re: [PATCH 2/3] http-push: fix construction of hex value from path)","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-17T21:47:16Z","receivedAt":"2017-10-17T21:46:23Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 10/17, Jeff King wrote:\n> On Thu, Oct 05, 2017 at 09:00:49PM +0100, Thomas Gummerer wrote:\n> \n> > Since you were asking :) With the introduction of 'git stash push',\n> > my hope was always that we could eventually get rid of 'git stash\n> > save' and only keep one interface around.\n> > \n> > As there still many references to it around on the internet, it\n> > probably requires a bit of a longer deprecation plan. What do you\n> > think about the following:\n> > \n> > - Change docs/man pages to use 'git stash push' everywhere instead of\n> > 'git stash save'.\n> > - Mention the deprecation in the release notes and in the man page.\n> > - Print a warning when 'git stash save' is used.\n> > - Eventually get rid of it (maybe something for 3.0?)\n> > \n> > The steps above would all occur sequentially with a few releases\n> > between each of them.\n> \n> That sounds like a pretty good plan.\n> \n> > A patch for the first step below. I think that even makes sense if we\n> > don't want to follow through with the deprecation.\n> \n> Agreed. The patch mostly looks good, except:\n\nThanks for the review.\n\n> > diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> > index b4d88af133..1c4e44892d 100644\n> > --- a/Documentation/user-manual.txt\n> > +++ b/Documentation/user-manual.txt\n> > @@ -1556,7 +1556,7 @@ so on a different branch and then coming back), unstash the\n> > work-in-progress changes.\n> > \n> > ------------------------------------------------\n> > -$ git stash save \"work in progress for foo feature\"\n> > +$ git stash push \"work in progress for foo feature\"\n> > ------------------------------------------------\n> \n> This needs \"-m\", doesn't it?\n\nYeah, this definitely needs \"-m\". Will change.\n\n> > \n> > This command will save your changes away to the `stash`, and\n> > diff --git a/git-stash.sh b/git-stash.sh\n> > index 8b2ce9afda..8ce6929d7f 100755\n> > --- a/git-stash.sh\n> > +++ b/git-stash.sh\n> > @@ -267,11 +267,11 @@ push_stash () {\n> > \t\t\t# translation of \"error: \" takes in your language. E.g. in\n> > \t\t\t# English this is:\n> > \t\t\t#\n> > -\t\t\t# $ git stash save --blah-blah 2>&1 | head -n 2\n> > -\t\t\t# error: unknown option for 'stash save': --blah-blah\n> > -\t\t\t# To provide a message, use git stash save -- '--blah-blah'\n> > -\t\t\teval_gettextln \"error: unknown option for 'stash save': \\$option\n> > - To provide a message, use git stash save -- '\\$option'\"\n> > +\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n> > +\t\t\t# error: unknown option for 'stash push': --blah-blah\n> > +\t\t\t# To provide a message, use git stash push -- '--blah-blah'\n> > +\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n> > + To provide a message, use git stash push -- '\\$option'\"\n> \n> And here, too?\n\nIndeed, thanks for catching these. Will change and re-roll the\npatches.\n\n> -Peff\n"},{"id":"330579","messageId":"20171017214708.ixc2hnut2virarzh@sigill.intra.peff.net","threadId":"46916","inReplyTo":"20171017214515.GG15399@hank","subject":"Re: [PATCH 2/1] mention git stash push first in the man page","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-17T21:47:08Z","receivedAt":"2017-10-17T21:47:15Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Oct 17, 2017 at 10:45:15PM +0100, Thomas Gummerer wrote:\n\n> > Seems reasonable, though if we are deprecating \"save\" should we demote\n> > it from being in the synopsis entirely?\n> \n> I saw that as a next step, with the \"official\" deprecation of \"save\".\n> I thought we might want to advertise \"push\" a bit more before actually\n> officially deprecating \"save\" and sending the deprecation notice out\n> in the release notes.\n\nRight, my thinking was that it would still be documented in the manpage,\njust lower down. And that would probably say something like \"save is a\nhistorical synonym for push, except that it differs in these ways...\".\n\n> OTOH, dropping it from the synopsis in the man page probably wouldn't\n> cause much issue, as \"push\" directly replaces it, and is easily\n> visible. Not sure how slow we want to take the deprecation?\n\nI don't think there's any reason to go slow in marking something as\ndeprecated. It's the part where we follow up and remove or change the\nfeature that must take a while.\n\n-Peff\n"},{"id":"330655","messageId":"20171019180801.GI15399@hank","threadId":"46916","inReplyTo":"20171017214708.ixc2hnut2virarzh@sigill.intra.peff.net","subject":"Re: [PATCH 2/1] mention git stash push first in the man page","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-19T18:08:01Z","receivedAt":"2017-10-19T18:07:07Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 10/17, Jeff King wrote:\n> On Tue, Oct 17, 2017 at 10:45:15PM +0100, Thomas Gummerer wrote:\n> \n> > > Seems reasonable, though if we are deprecating \"save\" should we demote\n> > > it from being in the synopsis entirely?\n> > \n> > I saw that as a next step, with the \"official\" deprecation of \"save\".\n> > I thought we might want to advertise \"push\" a bit more before actually\n> > officially deprecating \"save\" and sending the deprecation notice out\n> > in the release notes.\n> \n> Right, my thinking was that it would still be documented in the manpage,\n> just lower down. And that would probably say something like \"save is a\n> historical synonym for push, except that it differs in these ways...\".\n> \n> > OTOH, dropping it from the synopsis in the man page probably wouldn't\n> > cause much issue, as \"push\" directly replaces it, and is easily\n> > visible. Not sure how slow we want to take the deprecation?\n> \n> I don't think there's any reason to go slow in marking something as\n> deprecated. It's the part where we follow up and remove or change the\n> feature that must take a while.\n\nMakes sense, let me drop it from the synopsis then.\n\nThanks!\n\n> -Peff\n"},{"id":"330659","messageId":"20171019183304.26748-1-t.gummerer@gmail.com","threadId":"46916","inReplyTo":"20171005200049.GF30301@hank","subject":"[PATCH v2 1/2] replace git stash save with git stash push in the documentation","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-19T18:33:03Z","receivedAt":"2017-10-19T18:32:11Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"git stash push is the newer interface for creating a stash. While we\nare still keeping git stash save around for the time being, it's better\nto point new users of git stash to the more modern (and more feature\nrich) interface, instead of teaching them the older version that we\nmight want to phase out in the future.\n\nSigned-off-by: Thomas Gummerer \n---\n Documentation/git-stash.txt | 12 ++++++------\n Documentation/gitworkflows.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n git-stash.sh | 10 +++++-----\n 4 files changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 00f95fee1f..53b2e60aeb 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -33,7 +33,7 @@ and reverts the working directory to match the `HEAD` commit.\n The modifications stashed away by this command can be listed with\n `git stash list`, inspected with `git stash show`, and restored\n (potentially on top of a different commit) with `git stash apply`.\n-Calling `git stash` without any arguments is equivalent to `git stash save`.\n+Calling `git stash` without any arguments is equivalent to `git stash push`.\n A stash is by default listed as \"WIP on 'branchname' ...\", but\n you can give a more descriptive message on the command line when\n you create one.\n@@ -118,7 +118,7 @@ pop [--index] [-q|--quiet] []::\n \n \tRemove a single stashed state from the stash list and apply it\n \ton top of the current working tree state, i.e., do the inverse\n-\toperation of `git stash save`. The working directory must\n+\toperation of `git stash push`. The working directory must\n \tmatch the index.\n +\n Applying the state can fail with conflicts; in this case, it is not\n@@ -137,7 +137,7 @@ apply [--index] [-q|--quiet] []::\n \n \tLike `pop`, but do not remove the state from the stash list. Unlike `pop`,\n \t`` may be any commit that looks like a commit created by\n-\t`stash save` or `stash create`.\n+\t`stash push` or `stash create`.\n \n branch []::\n \n@@ -148,7 +148,7 @@ branch []::\n \t`stash@{}`, it then drops the ``. When no ``\n \tis given, applies the latest one.\n +\n-This is useful if the branch on which you ran `git stash save` has\n+This is useful if the branch on which you ran `git stash push` has\n changed enough that `git stash apply` fails due to conflicts. Since\n the stash entry is applied on top of the commit that was HEAD at the\n time `git stash` was run, it restores the originally stashed state\n@@ -255,14 +255,14 @@ $ git stash pop\n \n Testing partial commits::\n \n-You can use `git stash save --keep-index` when you want to make two or\n+You can use `git stash push --keep-index` when you want to make two or\n more commits out of the changes in the work tree, and you want to test\n each change before committing:\n +\n ----------------------------------------------------------------\n # ... hack hack hack ...\n $ git add --patch foo # add just first part to the index\n-$ git stash save --keep-index # save all other changes to the stash\n+$ git stash push --keep-index # save all other changes to the stash\n $ edit/build/test first part\n $ git commit -m 'First part' # commit fully tested change\n $ git stash pop # prepare to work on all other changes\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 177610e44e..02569d0614 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -40,7 +40,7 @@ beginning. It is always easier to squash a few commits together than\n to split one big commit into several. Don't be afraid of making too\n small or imperfect steps along the way. You can always go back later\n and edit the commits with `git rebase --interactive` before you\n-publish them. You can use `git stash save --keep-index` to run the\n+publish them. You can use `git stash push --keep-index` to run the\n test suite independent of other uncommitted changes; see the EXAMPLES\n section of linkgit:git-stash[1].\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex b4d88af133..3a03e63eb0 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1556,7 +1556,7 @@ so on a different branch and then coming back), unstash the\n work-in-progress changes.\n \n ------------------------------------------------\n-$ git stash save \"work in progress for foo feature\"\n+$ git stash push -m \"work in progress for foo feature\"\n ------------------------------------------------\n \n This command will save your changes away to the `stash`, and\ndiff --git a/git-stash.sh b/git-stash.sh\nindex 8b2ce9afda..16919277ba 100755\n--- a/git-stash.sh\n+++ b/git-stash.sh\n@@ -267,11 +267,11 @@ push_stash () {\n \t\t\t# translation of \"error: \" takes in your language. E.g. in\n \t\t\t# English this is:\n \t\t\t#\n-\t\t\t# $ git stash save --blah-blah 2>&1 | head -n 2\n-\t\t\t# error: unknown option for 'stash save': --blah-blah\n-\t\t\t# To provide a message, use git stash save -- '--blah-blah'\n-\t\t\teval_gettextln \"error: unknown option for 'stash save': \\$option\n- To provide a message, use git stash save -- '\\$option'\"\n+\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n+\t\t\t# error: unknown option for 'stash push': --blah-blah\n+\t\t\t# To provide a message, use git stash push -- '--blah-blah'\n+\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n+ To provide a message, use git stash push -m '\\$option'\"\n \t\t\tusage\n \t\t\t;;\n \t\t*)\n-- \n2.15.0.rc1.65.g660fb3dfa8\n\n"},{"id":"330660","messageId":"20171019183304.26748-2-t.gummerer@gmail.com","threadId":"46916","inReplyTo":"20171019183304.26748-1-t.gummerer@gmail.com","subject":"[PATCH v2 2/2] mark git stash push deprecated in the man page","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-19T18:33:04Z","receivedAt":"2017-10-19T18:32:13Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"'git stash push' fixes a historical wart in the interface of 'git stash\nsave'. As 'git stash push' has all functionality of 'git stash save',\nwith a nicer, more consistent user interface deprecate 'git stash\nsave'. To do this, remove it from the synopsis of the man page, and\nmove it to a separate section, stating that it is deprecated.\n\nHelped-by: Robert P. J. Day \nSigned-off-by: Thomas Gummerer \n---\n Documentation/git-stash.txt | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 53b2e60aeb..89b6a0e672 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -13,8 +13,6 @@ SYNOPSIS\n 'git stash' drop [-q|--quiet] []\n 'git stash' ( pop | apply ) [--index] [-q|--quiet] []\n 'git stash' branch []\n-'git stash' save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n-\t [-u|--include-untracked] [-a|--all] []\n 'git stash' [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n \t [-u|--include-untracked] [-a|--all] [-m|--message ]]\n \t [--] [...]]\n@@ -48,7 +46,6 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).\n OPTIONS\n -------\n \n-save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message ] [--] [...]::\n \n \tSave your local modifications to a new 'stash entry' and roll them\n@@ -87,6 +84,10 @@ linkgit:git-add[1] to learn how to operate the `--patch` mode.\n The `--patch` option implies `--keep-index`. You can use\n `--no-keep-index` to override this.\n \n+save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n+\n+\tThis option is deprecated in favour of 'git stash push'.\n+\n list []::\n \n \tList the stash entries that you currently have. Each 'stash entry' is\n-- \n2.15.0.rc1.65.g660fb3dfa8\n\n"},{"id":"330720","messageId":"alpine.LFD.2.21.1710200403260.30185@localhost.localdomain","threadId":"46916","inReplyTo":"20171019180801.GI15399@hank","subject":"Re: [PATCH 2/1] mention git stash push first in the man page","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-10-20T08:04:10Z","receivedAt":"2017-10-20T08:04:22Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Thu, 19 Oct 2017, Thomas Gummerer wrote:\n\n> On 10/17, Jeff King wrote:\n> > On Tue, Oct 17, 2017 at 10:45:15PM +0100, Thomas Gummerer wrote:\n> >\n> > > > Seems reasonable, though if we are deprecating \"save\" should we demote\n> > > > it from being in the synopsis entirely?\n> > >\n> > > I saw that as a next step, with the \"official\" deprecation of \"save\".\n> > > I thought we might want to advertise \"push\" a bit more before actually\n> > > officially deprecating \"save\" and sending the deprecation notice out\n> > > in the release notes.\n> >\n> > Right, my thinking was that it would still be documented in the manpage,\n> > just lower down. And that would probably say something like \"save is a\n> > historical synonym for push, except that it differs in these ways...\".\n> >\n> > > OTOH, dropping it from the synopsis in the man page probably wouldn't\n> > > cause much issue, as \"push\" directly replaces it, and is easily\n> > > visible. Not sure how slow we want to take the deprecation?\n> >\n> > I don't think there's any reason to go slow in marking something as\n> > deprecated. It's the part where we follow up and remove or change the\n> > feature that must take a while.\n>\n> Makes sense, let me drop it from the synopsis then.\n\n what, exactly, is the oft-referred-to issue with how \"git stash\nsave\" works that is being addressed with the new syntax of \"git stash\npush\"?\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"330777","messageId":"20171021062050.wp2fdjwmjhwcorln@sigill.intra.peff.net","threadId":"46916","inReplyTo":"alpine.LFD.2.21.1710200403260.30185@localhost.localdomain","subject":"Re: [PATCH 2/1] mention git stash push first in the man page","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-21T06:20:51Z","receivedAt":"2017-10-21T06:20:57Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 20, 2017 at 04:04:10AM -0400, Robert P. J. Day wrote:\n\n> > > I don't think there's any reason to go slow in marking something as\n> > > deprecated. It's the part where we follow up and remove or change the\n> > > feature that must take a while.\n> >\n> > Makes sense, let me drop it from the synopsis then.\n> \n> what, exactly, is the oft-referred-to issue with how \"git stash\n> save\" works that is being addressed with the new syntax of \"git stash\n> push\"?\n\n\"stash save\" soaks up all arguments as the stash message, so it's not\npossible to specify pathspecs. \"push\" uses \"-m \" for the stash\nmessage, and can accept pathspecs.\n\n-Peff\n"},{"id":"330778","messageId":"20171021062617.yajqusruqanjnicb@sigill.intra.peff.net","threadId":"46916","inReplyTo":"20171019183304.26748-1-t.gummerer@gmail.com","subject":"Re: [PATCH v2 1/2] replace git stash save with git stash push in the documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-21T06:26:17Z","receivedAt":"2017-10-21T06:26:23Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 19, 2017 at 07:33:03PM +0100, Thomas Gummerer wrote:\n\n> diff --git a/git-stash.sh b/git-stash.sh\n> index 8b2ce9afda..16919277ba 100755\n> --- a/git-stash.sh\n> +++ b/git-stash.sh\n> @@ -267,11 +267,11 @@ push_stash () {\n> \t\t\t# translation of \"error: \" takes in your language. E.g. in\n> \t\t\t# English this is:\n> \t\t\t#\n> -\t\t\t# $ git stash save --blah-blah 2>&1 | head -n 2\n> -\t\t\t# error: unknown option for 'stash save': --blah-blah\n> -\t\t\t# To provide a message, use git stash save -- '--blah-blah'\n> -\t\t\teval_gettextln \"error: unknown option for 'stash save': \\$option\n> - To provide a message, use git stash save -- '\\$option'\"\n> +\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n> +\t\t\t# error: unknown option for 'stash push': --blah-blah\n> +\t\t\t# To provide a message, use git stash push -- '--blah-blah'\n> +\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n> + To provide a message, use git stash push -m '\\$option'\"\n\nThe user message is fixed here, but doesn't the message for translators\nneed the same treatment? I guess it's just talking about the spacing,\nso it doesn't need to be completely accurate. But it probably makes\nsense to update it at the same time.\n\nAs an aside, I do kind of wonder if the right advice for \"push\" is\ndifferent than for \"save\" here. I.e., should it say \"to provide a\npathspec that starts with --, use push -- --blah-blah\". I'm not sure it\nmatters that much. Second-guessing what a user meant seems likely to go\nwrong (e.g., \"--icnlude-untracked\" would trigger this message, which is\njust silly). But that's largely orthogonal to what you're doing here.\n\n-Peff\n"},{"id":"330779","messageId":"20171021062846.s6rzo2hxmeqigk3e@sigill.intra.peff.net","threadId":"46916","inReplyTo":"20171019183304.26748-2-t.gummerer@gmail.com","subject":"Re: [PATCH v2 2/2] mark git stash push deprecated in the man page","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-21T06:28:46Z","receivedAt":"2017-10-21T06:28:52Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 19, 2017 at 07:33:04PM +0100, Thomas Gummerer wrote:\n\n> 'git stash push' fixes a historical wart in the interface of 'git stash\n> save'. As 'git stash push' has all functionality of 'git stash save',\n> with a nicer, more consistent user interface deprecate 'git stash\n> save'. To do this, remove it from the synopsis of the man page, and\n> move it to a separate section, stating that it is deprecated.\n\nThis looks fine.\n\n> @@ -87,6 +84,10 @@ linkgit:git-add[1] to learn how to operate the `--patch` mode.\n> The `--patch` option implies `--keep-index`. You can use\n> `--no-keep-index` to override this.\n> \n> +save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n> +\n> +\tThis option is deprecated in favour of 'git stash push'.\n> +\n\nWe could possibly go into more detail, like:\n\n It differs from \"stash push\" in that it cannot take pathspecs, and any\n non-option arguments form the message.\n\nor something. Since we don't want people to use it, it probably doesn't\nmatter much. I just wondered if people would peer at the (long) synopsis\nline trying to figure out how it's different.\n\n-Peff\n"},{"id":"330780","messageId":"alpine.LFD.2.21.1710210242580.8217@localhost.localdomain","threadId":"46916","inReplyTo":"20171021062050.wp2fdjwmjhwcorln@sigill.intra.peff.net","subject":"Re: [PATCH 2/1] mention git stash push first in the man page","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-10-21T06:43:40Z","receivedAt":"2017-10-21T06:43:48Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Sat, 21 Oct 2017, Jeff King wrote:\n\n> On Fri, Oct 20, 2017 at 04:04:10AM -0400, Robert P. J. Day wrote:\n>\n> > > > I don't think there's any reason to go slow in marking something as\n> > > > deprecated. It's the part where we follow up and remove or change the\n> > > > feature that must take a while.\n> > >\n> > > Makes sense, let me drop it from the synopsis then.\n> >\n> > what, exactly, is the oft-referred-to issue with how \"git stash\n> > save\" works that is being addressed with the new syntax of \"git stash\n> > push\"?\n>\n> \"stash save\" soaks up all arguments as the stash message, so it's not\n> possible to specify pathspecs. \"push\" uses \"-m \" for the stash\n> message, and can accept pathspecs.\n\n ah, i knew that, yeah, that's the ticket. :-)\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"330804","messageId":"20171022162858.GJ15399@hank","threadId":"46916","inReplyTo":"20171021062617.yajqusruqanjnicb@sigill.intra.peff.net","subject":"Re: [PATCH v2 1/2] replace git stash save with git stash push in the documentation","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-22T16:28:58Z","receivedAt":"2017-10-22T16:28:01Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 10/21, Jeff King wrote:\n> On Thu, Oct 19, 2017 at 07:33:03PM +0100, Thomas Gummerer wrote:\n> \n> > diff --git a/git-stash.sh b/git-stash.sh\n> > index 8b2ce9afda..16919277ba 100755\n> > --- a/git-stash.sh\n> > +++ b/git-stash.sh\n> > @@ -267,11 +267,11 @@ push_stash () {\n> > \t\t\t# translation of \"error: \" takes in your language. E.g. in\n> > \t\t\t# English this is:\n> > \t\t\t#\n> > -\t\t\t# $ git stash save --blah-blah 2>&1 | head -n 2\n> > -\t\t\t# error: unknown option for 'stash save': --blah-blah\n> > -\t\t\t# To provide a message, use git stash save -- '--blah-blah'\n> > -\t\t\teval_gettextln \"error: unknown option for 'stash save': \\$option\n> > - To provide a message, use git stash save -- '\\$option'\"\n> > +\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n> > +\t\t\t# error: unknown option for 'stash push': --blah-blah\n> > +\t\t\t# To provide a message, use git stash push -- '--blah-blah'\n> > +\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n> > + To provide a message, use git stash push -m '\\$option'\"\n> \n> The user message is fixed here, but doesn't the message for translators\n> need the same treatment? I guess it's just talking about the spacing,\n> so it doesn't need to be completely accurate. But it probably makes\n> sense to update it at the same time.\n\nYeah, I was completely blind here, that should definitely have been\nupdated as well. Thanks for catching.\n\n> As an aside, I do kind of wonder if the right advice for \"push\" is\n> different than for \"save\" here. I.e., should it say \"to provide a\n> pathspec that starts with --, use push -- --blah-blah\". I'm not sure it\n> matters that much. Second-guessing what a user meant seems likely to go\n> wrong (e.g., \"--icnlude-untracked\" would trigger this message, which is\n> just silly). But that's largely orthogonal to what you're doing here.\n\nThe best advice for it might indeed be different for \"save\" and\n\"push\". The slight weirdness we have here is that both \"save\" and\n\"push\" are using the same option parsing.\n\nNow that we're deprecating \"save\", I don't think it's worth the effort\nto try to get rid of this weirdness.\n\nI think using \"--\" to distinguish the the pathspec from the command\nline options is a common enough pattern that we don't need to give\nadvice to the users. I feel like that second line was mostly there\nbecause of the weirdness in the user interface for \"stash save\".\nMaybe we should just get rid of that part alltogether?\n\n> -Peff\n"},{"id":"330805","messageId":"20171022163127.GK15399@hank","threadId":"46916","inReplyTo":"20171021062846.s6rzo2hxmeqigk3e@sigill.intra.peff.net","subject":"Re: [PATCH v2 2/2] mark git stash push deprecated in the man page","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-22T16:31:27Z","receivedAt":"2017-10-22T16:30:28Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 10/21, Jeff King wrote:\n> On Thu, Oct 19, 2017 at 07:33:04PM +0100, Thomas Gummerer wrote:\n> \n> > 'git stash push' fixes a historical wart in the interface of 'git stash\n> > save'. As 'git stash push' has all functionality of 'git stash save',\n> > with a nicer, more consistent user interface deprecate 'git stash\n> > save'. To do this, remove it from the synopsis of the man page, and\n> > move it to a separate section, stating that it is deprecated.\n> \n> This looks fine.\n> \n> > @@ -87,6 +84,10 @@ linkgit:git-add[1] to learn how to operate the `--patch` mode.\n> > The `--patch` option implies `--keep-index`. You can use\n> > `--no-keep-index` to override this.\n> > \n> > +save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n> > +\n> > +\tThis option is deprecated in favour of 'git stash push'.\n> > +\n> \n> We could possibly go into more detail, like:\n> \n> It differs from \"stash push\" in that it cannot take pathspecs, and any\n> non-option arguments form the message.\n> \n> or something. Since we don't want people to use it, it probably doesn't\n> matter much. I just wondered if people would peer at the (long) synopsis\n> line trying to figure out how it's different.\n\nYeah, feels like it could potentially help somebody. I'll add that, thanks!\n\n> -Peff\n"},{"id":"330806","messageId":"20171022170409.8565-1-t.gummerer@gmail.com","threadId":"46916","inReplyTo":"20171019183304.26748-2-t.gummerer@gmail.com","subject":"[PATCH v3 0/3] deprecate git stash save","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-22T17:04:06Z","receivedAt":"2017-10-22T17:03:14Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"Thanks Peff for the review of the previous rounds.\n\nIn addition to addressing the review comments, this round adds another\npatch getting rid of the extra help with an unknown option to git\nstash push.\n\nInterdiff below:\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 89b6a0e672..8be661007d 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -86,7 +86,9 @@ The `--patch` option implies `--keep-index`. You can use\n \n save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n \n-\tThis option is deprecated in favour of 'git stash push'.\n+\tThis option is deprecated in favour of 'git stash push'. It\n+\tdiffers from \"stash push\" in that it cannot take pathspecs,\n+\tand any non-option arguments form the message.\n \n list []::\n \ndiff --git a/git-stash.sh b/git-stash.sh\nindex 16919277ba..4b74951440 100755\n--- a/git-stash.sh\n+++ b/git-stash.sh\n@@ -260,18 +260,7 @@ push_stash () {\n \t\t\t;;\n \t\t-*)\n \t\t\toption=\"$1\"\n-\t\t\t# TRANSLATORS: $option is an invalid option, like\n-\t\t\t# `--blah-blah'. The 7 spaces at the beginning of the\n-\t\t\t# second line correspond to \"error: \". So you should line\n-\t\t\t# up the second line with however many characters the\n-\t\t\t# translation of \"error: \" takes in your language. E.g. in\n-\t\t\t# English this is:\n-\t\t\t#\n-\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n-\t\t\t# error: unknown option for 'stash push': --blah-blah\n-\t\t\t# To provide a message, use git stash push -- '--blah-blah'\n-\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n- To provide a message, use git stash push -m '\\$option'\"\n+\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\"\n \t\t\tusage\n \t\t\t;;\n \t\t*)\n\n\nThomas Gummerer (3):\n replace git stash save with git stash push in the documentation\n mark git stash push deprecated in the man page\n stash: remove now superfluos help for \"stash push\"\n\n Documentation/git-stash.txt | 21 ++++++++++++---------\n Documentation/gitworkflows.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n git-stash.sh | 13 +------------\n 4 files changed, 15 insertions(+), 23 deletions(-)\n\n-- \n2.15.0.rc0.2.g8fac3e73c8.dirty\n\n"},{"id":"330807","messageId":"20171022170409.8565-2-t.gummerer@gmail.com","threadId":"46916","inReplyTo":"20171022170409.8565-1-t.gummerer@gmail.com","subject":"[PATCH v3 1/3] replace git stash save with git stash push in the documentation","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-22T17:04:07Z","receivedAt":"2017-10-22T17:03:17Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"git stash push is the newer interface for creating a stash. While we\nare still keeping git stash save around for the time being, it's better\nto point new users of git stash to the more modern (and more feature\nrich) interface, instead of teaching them the older version that we\nmight want to phase out in the future.\n\nSigned-off-by: Thomas Gummerer \n---\n Documentation/git-stash.txt | 12 ++++++------\n Documentation/gitworkflows.txt | 2 +-\n Documentation/user-manual.txt | 2 +-\n git-stash.sh | 10 +++++-----\n 4 files changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 00f95fee1f..53b2e60aeb 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -33,7 +33,7 @@ and reverts the working directory to match the `HEAD` commit.\n The modifications stashed away by this command can be listed with\n `git stash list`, inspected with `git stash show`, and restored\n (potentially on top of a different commit) with `git stash apply`.\n-Calling `git stash` without any arguments is equivalent to `git stash save`.\n+Calling `git stash` without any arguments is equivalent to `git stash push`.\n A stash is by default listed as \"WIP on 'branchname' ...\", but\n you can give a more descriptive message on the command line when\n you create one.\n@@ -118,7 +118,7 @@ pop [--index] [-q|--quiet] []::\n \n \tRemove a single stashed state from the stash list and apply it\n \ton top of the current working tree state, i.e., do the inverse\n-\toperation of `git stash save`. The working directory must\n+\toperation of `git stash push`. The working directory must\n \tmatch the index.\n +\n Applying the state can fail with conflicts; in this case, it is not\n@@ -137,7 +137,7 @@ apply [--index] [-q|--quiet] []::\n \n \tLike `pop`, but do not remove the state from the stash list. Unlike `pop`,\n \t`` may be any commit that looks like a commit created by\n-\t`stash save` or `stash create`.\n+\t`stash push` or `stash create`.\n \n branch []::\n \n@@ -148,7 +148,7 @@ branch []::\n \t`stash@{}`, it then drops the ``. When no ``\n \tis given, applies the latest one.\n +\n-This is useful if the branch on which you ran `git stash save` has\n+This is useful if the branch on which you ran `git stash push` has\n changed enough that `git stash apply` fails due to conflicts. Since\n the stash entry is applied on top of the commit that was HEAD at the\n time `git stash` was run, it restores the originally stashed state\n@@ -255,14 +255,14 @@ $ git stash pop\n \n Testing partial commits::\n \n-You can use `git stash save --keep-index` when you want to make two or\n+You can use `git stash push --keep-index` when you want to make two or\n more commits out of the changes in the work tree, and you want to test\n each change before committing:\n +\n ----------------------------------------------------------------\n # ... hack hack hack ...\n $ git add --patch foo # add just first part to the index\n-$ git stash save --keep-index # save all other changes to the stash\n+$ git stash push --keep-index # save all other changes to the stash\n $ edit/build/test first part\n $ git commit -m 'First part' # commit fully tested change\n $ git stash pop # prepare to work on all other changes\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 177610e44e..02569d0614 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -40,7 +40,7 @@ beginning. It is always easier to squash a few commits together than\n to split one big commit into several. Don't be afraid of making too\n small or imperfect steps along the way. You can always go back later\n and edit the commits with `git rebase --interactive` before you\n-publish them. You can use `git stash save --keep-index` to run the\n+publish them. You can use `git stash push --keep-index` to run the\n test suite independent of other uncommitted changes; see the EXAMPLES\n section of linkgit:git-stash[1].\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex b4d88af133..3a03e63eb0 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1556,7 +1556,7 @@ so on a different branch and then coming back), unstash the\n work-in-progress changes.\n \n ------------------------------------------------\n-$ git stash save \"work in progress for foo feature\"\n+$ git stash push -m \"work in progress for foo feature\"\n ------------------------------------------------\n \n This command will save your changes away to the `stash`, and\ndiff --git a/git-stash.sh b/git-stash.sh\nindex 8b2ce9afda..3a4e5d157c 100755\n--- a/git-stash.sh\n+++ b/git-stash.sh\n@@ -267,11 +267,11 @@ push_stash () {\n \t\t\t# translation of \"error: \" takes in your language. E.g. in\n \t\t\t# English this is:\n \t\t\t#\n-\t\t\t# $ git stash save --blah-blah 2>&1 | head -n 2\n-\t\t\t# error: unknown option for 'stash save': --blah-blah\n-\t\t\t# To provide a message, use git stash save -- '--blah-blah'\n-\t\t\teval_gettextln \"error: unknown option for 'stash save': \\$option\n- To provide a message, use git stash save -- '\\$option'\"\n+\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n+\t\t\t# error: unknown option for 'stash push': --blah-blah\n+\t\t\t# To provide a message, use git stash push -m '--blah-blah'\n+\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n+ To provide a message, use git stash push -m '\\$option'\"\n \t\t\tusage\n \t\t\t;;\n \t\t*)\n-- \n2.15.0.rc0.2.g8fac3e73c8.dirty\n\n"},{"id":"330808","messageId":"20171022170409.8565-3-t.gummerer@gmail.com","threadId":"46916","inReplyTo":"20171022170409.8565-1-t.gummerer@gmail.com","subject":"[PATCH v3 2/3] mark git stash push deprecated in the man page","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-22T17:04:08Z","receivedAt":"2017-10-22T17:03:19Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"'git stash push' fixes a historical wart in the interface of 'git stash\nsave'. As 'git stash push' has all functionality of 'git stash save',\nwith a nicer, more consistent user interface deprecate 'git stash\nsave'. To do this, remove it from the synopsis of the man page, and\nmove it to a separate section, stating that it is deprecated.\n\nHelped-by: Robert P. J. Day \nHelped-by: Jeff King \nSigned-off-by: Thomas Gummerer \n---\n Documentation/git-stash.txt | 9 ++++++---\n 1 file changed, 6 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 53b2e60aeb..8be661007d 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -13,8 +13,6 @@ SYNOPSIS\n 'git stash' drop [-q|--quiet] []\n 'git stash' ( pop | apply ) [--index] [-q|--quiet] []\n 'git stash' branch []\n-'git stash' save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n-\t [-u|--include-untracked] [-a|--all] []\n 'git stash' [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n \t [-u|--include-untracked] [-a|--all] [-m|--message ]]\n \t [--] [...]]\n@@ -48,7 +46,6 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).\n OPTIONS\n -------\n \n-save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message ] [--] [...]::\n \n \tSave your local modifications to a new 'stash entry' and roll them\n@@ -87,6 +84,12 @@ linkgit:git-add[1] to learn how to operate the `--patch` mode.\n The `--patch` option implies `--keep-index`. You can use\n `--no-keep-index` to override this.\n \n+save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n+\n+\tThis option is deprecated in favour of 'git stash push'. It\n+\tdiffers from \"stash push\" in that it cannot take pathspecs,\n+\tand any non-option arguments form the message.\n+\n list []::\n \n \tList the stash entries that you currently have. Each 'stash entry' is\n-- \n2.15.0.rc0.2.g8fac3e73c8.dirty\n\n"},{"id":"330809","messageId":"20171022170409.8565-4-t.gummerer@gmail.com","threadId":"46916","inReplyTo":"20171022170409.8565-1-t.gummerer@gmail.com","subject":"[PATCH v3 3/3] stash: remove now superfluos help for \"stash push\"","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2017-10-22T17:04:09Z","receivedAt":"2017-10-22T17:03:21Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"With the 'git stash save' interface, it was easily possible for users to\ntry to add a message which would start with \"-\", which 'git stash save'\nwould interpret as a command line argument, and fail. For this case we\nadded some extra help on how to create a stash with a message starting\nwith \"-\".\n\nFor 'stash push', messages are passed with the -m flag, avoiding this\npotential pitfall. Now only pathspecs starting with \"-\" would have to\nbe distinguished from command line parameters by using\n\"-- --\". This is fairly common in the git command line\ninterface, and we don't try to guess what the users wanted in the other\ncases.\n\nBecause this way of passing pathspecs is quite common in other git\ncommands, and we don't provide any extra help there, do the same in the\nerror message for 'git stash push'.\n\nSigned-off-by: Thomas Gummerer \n---\n git-stash.sh | 13 +------------\n 1 file changed, 1 insertion(+), 12 deletions(-)\n\ndiff --git a/git-stash.sh b/git-stash.sh\nindex 3a4e5d157c..4b74951440 100755\n--- a/git-stash.sh\n+++ b/git-stash.sh\n@@ -260,18 +260,7 @@ push_stash () {\n \t\t\t;;\n \t\t-*)\n \t\t\toption=\"$1\"\n-\t\t\t# TRANSLATORS: $option is an invalid option, like\n-\t\t\t# `--blah-blah'. The 7 spaces at the beginning of the\n-\t\t\t# second line correspond to \"error: \". So you should line\n-\t\t\t# up the second line with however many characters the\n-\t\t\t# translation of \"error: \" takes in your language. E.g. in\n-\t\t\t# English this is:\n-\t\t\t#\n-\t\t\t# $ git stash push --blah-blah 2>&1 | head -n 2\n-\t\t\t# error: unknown option for 'stash push': --blah-blah\n-\t\t\t# To provide a message, use git stash push -m '--blah-blah'\n-\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\n- To provide a message, use git stash push -m '\\$option'\"\n+\t\t\teval_gettextln \"error: unknown option for 'stash push': \\$option\"\n \t\t\tusage\n \t\t\t;;\n \t\t*)\n-- \n2.15.0.rc0.2.g8fac3e73c8.dirty\n\n"},{"id":"330812","messageId":"20171023003922.h3hr3y5ap2tk7byu@sigill.intra.peff.net","threadId":"46916","inReplyTo":"20171022170409.8565-1-t.gummerer@gmail.com","subject":"Re: [PATCH v3 0/3] deprecate git stash save","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-23T00:39:22Z","receivedAt":"2017-10-23T00:39:28Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Oct 22, 2017 at 06:04:06PM +0100, Thomas Gummerer wrote:\n\n> Thanks Peff for the review of the previous rounds.\n> \n> In addition to addressing the review comments, this round adds another\n> patch getting rid of the extra help with an unknown option to git\n> stash push.\n\nYeah, the reasoning in the commit message of patch 3 makes sense to me.\n\n> Thomas Gummerer (3):\n> replace git stash save with git stash push in the documentation\n> mark git stash push deprecated in the man page\n> stash: remove now superfluos help for \"stash push\"\n\nThe whole thing looks good. Thanks!\n\n-Peff\n"},{"id":"330814","messageId":"xmqqwp3md5jp.fsf@gitster.mtv.corp.google.com","threadId":"46916","inReplyTo":"20171022170409.8565-1-t.gummerer@gmail.com","subject":"Re: [PATCH v3 0/3] deprecate git stash save","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-23T01:19:38Z","receivedAt":"2017-10-23T01:19:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Gummerer writes:\n\n> Interdiff below:\n\nThanks. Looks much more polished.\n\n>\n> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\n> index 89b6a0e672..8be661007d 100644\n> --- a/Documentation/git-stash.txt\n> +++ b/Documentation/git-stash.txt\n> @@ -86,7 +86,9 @@ The `--patch` option implies `--keep-index`. You can use\n> \n> save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n> \n> -\tThis option is deprecated in favour of 'git stash push'.\n> +\tThis option is deprecated in favour of 'git stash push'. It\n> +\tdiffers from \"stash push\" in that it cannot take pathspecs,\n> +\tand any non-option arguments form the message.\n\nEvery time I saw this line, I misread s/form/from/ and got\nconfused.\n\nI know the below is what the above wants the readers to eventually\n[*1*] know:\n\n 'git stash save' cannot take pathspecs (nor it can be\n enhanced with new options in the future) because any\n non-option argument to it is treated as the message and has\n been deprecated. 'git stash push' supersedes 'git stash\n save'; it corrects the command line syntax by requiring '-m'\n before the message.\n\nbut I feel that the text in your patch still does not read clearly\nenough. But it may only be me.\n\nThanks.\n\n\n[Footnote]\n\n*1* By \"eventually\" what I mean is that it may not be necessarily a\ngood idea to lay it out all to the reader here at this point in the\ndocument---they may not care why a subcommand is being deprecated,\nbut for those who want to know, we need to write it down somewhere.\n"},{"id":"330815","messageId":"xmqqpo9ed4yo.fsf@gitster.mtv.corp.google.com","threadId":"46916","inReplyTo":"20171022170409.8565-1-t.gummerer@gmail.com","subject":"Re: [PATCH v3 0/3] deprecate git stash save","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-23T01:32:15Z","receivedAt":"2017-10-23T01:32:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Overall the result looks reasonable and get us closer to the ideal\nworld where nobody recalls \"stash save\" has ever existed ;-)\n\nWill queue; thanks.\n"},{"id":"330819","messageId":"20171023051850.vil3p5pmu3jb2a5y@sigill.intra.peff.net","threadId":"46916","inReplyTo":"xmqqwp3md5jp.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 0/3] deprecate git stash save","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-23T05:18:51Z","receivedAt":"2017-10-23T05:18:59Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Oct 23, 2017 at 10:19:38AM +0900, Junio C Hamano wrote:\n\n> > -\tThis option is deprecated in favour of 'git stash push'.\n> > +\tThis option is deprecated in favour of 'git stash push'. It\n> > +\tdiffers from \"stash push\" in that it cannot take pathspecs,\n> > +\tand any non-option arguments form the message.\n> \n> Every time I saw this line, I misread s/form/from/ and got\n> confused.\n\nWe could reverse the order:\n\n ...and the message is taken from any non-option arguments.\n\n-Peff\n"},{"id":"330821","messageId":"xmqqh8uqbcsc.fsf@gitster.mtv.corp.google.com","threadId":"46916","inReplyTo":"20171023051850.vil3p5pmu3jb2a5y@sigill.intra.peff.net","subject":"Re: [PATCH v3 0/3] deprecate git stash save","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-23T06:26:11Z","receivedAt":"2017-10-23T06:26:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Mon, Oct 23, 2017 at 10:19:38AM +0900, Junio C Hamano wrote:\n>\n>> > -\tThis option is deprecated in favour of 'git stash push'.\n>> > +\tThis option is deprecated in favour of 'git stash push'. It\n>> > +\tdiffers from \"stash push\" in that it cannot take pathspecs,\n>> > +\tand any non-option arguments form the message.\n>> \n>> Every time I saw this line, I misread s/form/from/ and got\n>> confused.\n>\n> We could reverse the order:\n>\n> ...and the message is taken from any non-option arguments.\n\nYeah, that makes it slightly less confusing. Or \"any non-option\narguments become the message\", perhaps? I dunno.\n\nLet's queue the version as posted; perhaps somebody new comes and\nsays it is confusing in three months, at which time we may be able\nto come up with a better phrasing with a fresh mind ;-)\n\n"},{"id":"330822","messageId":"alpine.LFD.2.21.1710230147240.32043@localhost.localdomain","threadId":"46916","inReplyTo":"xmqqwp3md5jp.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 0/3] deprecate git stash save","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-10-23T05:47:56Z","receivedAt":"2017-10-23T06:32:35Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Mon, 23 Oct 2017, Junio C Hamano wrote:\n\n> Thomas Gummerer writes:\n>\n> > Interdiff below:\n>\n> Thanks. Looks much more polished.\n>\n> >\n> > diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\n> > index 89b6a0e672..8be661007d 100644\n> > --- a/Documentation/git-stash.txt\n> > +++ b/Documentation/git-stash.txt\n> > @@ -86,7 +86,9 @@ The `--patch` option implies `--keep-index`. You can use\n> >\n> > save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] []::\n> >\n> > -\tThis option is deprecated in favour of 'git stash push'.\n> > +\tThis option is deprecated in favour of 'git stash push'. It\n> > +\tdiffers from \"stash push\" in that it cannot take pathspecs,\n> > +\tand any non-option arguments form the message.\n>\n> Every time I saw this line, I misread s/form/from/ and got\n> confused.\n\n \"constitute\"?\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"}]}