{"thread":{"id":"46947","subject":"[PATCH] doc: emphasize stash \"--keep-index\" stashes staged content","startedAt":"2017-10-11T08:46:40Z","lastAt":"2017-10-12T07:16:18Z","messageCount":4,"participants":["Robert P. J. Day","Junio C Hamano","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"330165","messageId":"alpine.LFD.2.21.1710110443360.11205@localhost.localdomain","threadId":"46947","inReplyTo":null,"subject":"[PATCH] doc: emphasize stash \"--keep-index\" stashes staged content","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-10-11T08:46:30Z","receivedAt":"2017-10-11T08:46:40Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\nIt's not immediately obvious from the man page that the \"--keep-index\"\noption still adds the staged content to the stash, so make that\nabundantly clear.\n\nSigned-off-by: Robert P. J. Day \n\n---\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 00f95fee1..037144037 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -68,8 +68,8 @@ entries and working tree files are then rolled back to the state in\n HEAD only for these files, too, leaving files that do not match the\n pathspec intact.\n +\n-If the `--keep-index` option is used, all changes already added to the\n-index are left intact.\n+If the `--keep-index` option is used, all changes already staged in the\n+index are left intact in the index, while still being added to the stash.\n +\n If the `--include-untracked` option is used, all untracked files are also\n stashed and then cleaned up with `git clean`, leaving the working directory\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":"330218","messageId":"xmqq376p42ul.fsf@gitster.mtv.corp.google.com","threadId":"46947","inReplyTo":"alpine.LFD.2.21.1710110443360.11205@localhost.localdomain","subject":"Re: [PATCH] doc: emphasize stash \"--keep-index\" stashes staged content","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-12T00:38:42Z","receivedAt":"2017-10-12T00:38:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Robert P. J. Day\" writes:\n\n> -If the `--keep-index` option is used, all changes already added to the\n> -index are left intact.\n> +If the `--keep-index` option is used, all changes already staged in the\n> +index are left intact in the index, while still being added to the stash.\n\nI do not think \"left intact in the index\" is an improvement. The\nprimary reason why people use --keep-index is to get a working tree\nthat has _only_ the changes that are already added to the index and\nnothing else, so that the state in the index can be built and/or\ntested. So if you want to add anything to that sentence, it should\nstress the fact that changes are left intact \"in the working tree\".\nAdding \"in the index\" without doing so makes the result even more\nconfusing, not less, by allowing a mis-read \"left intact _only_ in\nthe index? so the working tree files are reverted to the HEAD's\nversion?\"\n\nI am still undecided as to the value of saying \", while still being\nadded...\".\n\n"},{"id":"330237","messageId":"20171012041631.GC155740@aiede.mtv.corp.google.com","threadId":"46947","inReplyTo":"alpine.LFD.2.21.1710110443360.11205@localhost.localdomain","subject":"Re: [PATCH] doc: emphasize stash \"--keep-index\" stashes staged content","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-10-12T04:16:31Z","receivedAt":"2017-10-12T04:16:42Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nRobert P. J. Day wrote:\n\n> It's not immediately obvious from the man page that the \"--keep-index\"\n> option still adds the staged content to the stash, so make that\n> abundantly clear.\n>\n> Signed-off-by: Robert P. J. Day \n> ---\n>\n> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\n> index 00f95fee1..037144037 100644\n> --- a/Documentation/git-stash.txt\n> +++ b/Documentation/git-stash.txt\n> @@ -68,8 +68,8 @@ entries and working tree files are then rolled back to the state in\n> HEAD only for these files, too, leaving files that do not match the\n> pathspec intact.\n> +\n> -If the `--keep-index` option is used, all changes already added to the\n> -index are left intact.\n> +If the `--keep-index` option is used, all changes already staged in the\n> +index are left intact in the index, while still being added to the stash.\n\nAside from Junio's note about \"in the index\" vs \"in the working tree\":\n\nThe \"Testing partial commits\" item in the EXAMPLES section explains\nwhat --keep-index is useful for. I wonder if some allusion to that\nwould make the explanation in the OPTIONS section easier to\nunderstand.\n\nSomething that I end up still curious about when reading this\ndescription is what will happen when I \"git stash pop\". Will it apply\nonly the changes that were stashed away and removed from the working\ntree, or will it apply the changes that were kept in the index, too?\nIf the latter, why? Is there some way I can turn that behavior off?\n\nE.g. in the \"Testing partial commits\" example, it seems like the\nnatural behavior for \"git stash pop\" would be just restore the changes\nthat were removed from the working tree. That would also match an\nassumption of save/push and pop being symmetrical ('inverse\noperations').\n\nIs this related to \"git stash pop --index\"? I notice that the\nEXAMPLES section doesn't give any examples of that option.\n\nThanks,\nJonathan\n"},{"id":"330247","messageId":"alpine.LFD.2.21.1710120257450.24121@localhost.localdomain","threadId":"46947","inReplyTo":"20171012041631.GC155740@aiede.mtv.corp.google.com","subject":"Re: [PATCH] doc: emphasize stash \"--keep-index\" stashes staged content","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-10-12T07:16:10Z","receivedAt":"2017-10-12T07:16:18Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Wed, 11 Oct 2017, Jonathan Nieder wrote:\n\n> Hi,\n>\n> Robert P. J. Day wrote:\n>\n> > It's not immediately obvious from the man page that the \"--keep-index\"\n> > option still adds the staged content to the stash, so make that\n> > abundantly clear.\n> >\n> > Signed-off-by: Robert P. J. Day \n> > ---\n> >\n> > diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\n> > index 00f95fee1..037144037 100644\n> > --- a/Documentation/git-stash.txt\n> > +++ b/Documentation/git-stash.txt\n> > @@ -68,8 +68,8 @@ entries and working tree files are then rolled back to the state in\n> > HEAD only for these files, too, leaving files that do not match the\n> > pathspec intact.\n> > +\n> > -If the `--keep-index` option is used, all changes already added to the\n> > -index are left intact.\n> > +If the `--keep-index` option is used, all changes already staged in the\n> > +index are left intact in the index, while still being added to the stash.\n>\n> Aside from Junio's note about \"in the index\" vs \"in the working tree\":\n\n yes, that was a good point, i will ponder further.\n\n> The \"Testing partial commits\" item in the EXAMPLES section explains\n> what --keep-index is useful for. I wonder if some allusion to that\n> would make the explanation in the OPTIONS section easier to\n> understand.\n>\n> Something that I end up still curious about when reading this\n> description is what will happen when I \"git stash pop\". Will it\n> apply only the changes that were stashed away and removed from the\n> working tree, or will it apply the changes that were kept in the\n> index, too? If the latter, why? Is there some way I can turn that\n> behavior off?\n\n at risk of embarrassing myself, it seems that the simplest way to\nexplain stashing WRT to those --keep-index and --index options is to\nfirst explain that, regardless of --keep-index with push, stash will\n*always* stash all of your changes in the working tree, and will\nfurther distinguish between staged and unstaged content. that's based\non the diagram in the man page:\n\n .----W\n / /\n -----H----I\n\nso the initial explanation should be that the above *always* happens,\nno matter what.\n\n the next sentence should then say, \"if you add --keep-index, then\nstaged changes are preserved in the working tree and index\", or\nsomething like that. but the use of --keep-index does not (unless i'm\nreading this incorrectly) in any way affect what is stashed, correct?\n\n in that same vein, the explanation should then go on to explain that\npopping always restores the *entire* stash to the working tree -- all\nof it -- and the use of \"--index\" simply means that the portion of\nthe stash representing what had been staged will be restaged.\n\n not to belabour the point, but i think it's important to emphasize\nearly that --keep-index and --index in no way affect what is stashed,\nand what is popped, which i think is a common misunderstanding.\n\n> E.g. in the \"Testing partial commits\" example, it seems like the\n> natural behavior for \"git stash pop\" would be just restore the\n> changes that were removed from the working tree. That would also\n> match an assumption of save/push and pop being symmetrical ('inverse\n> operations').\n>\n> Is this related to \"git stash pop --index\"? I notice that the\n> EXAMPLES section doesn't give any examples of that option.\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"}]}