{"thread":{"id":"48515","subject":"error(?) in \"man git-stash\" regarding \"--keep-index\"","startedAt":"2018-05-18T09:39:00Z","lastAt":"2018-05-19T10:05:35Z","messageCount":9,"participants":["Robert P. J. Day","Martin Ågren","Sybille Peters"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"347976","messageId":"alpine.LFD.2.21.1805180534170.6786@localhost.localdomain","threadId":"48515","inReplyTo":null,"subject":"error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-18T09:37:28Z","receivedAt":"2018-05-18T09:39:00Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\n  toward the bottom of \"man git-stash\", one reads part of an example:\n\n  # ... hack hack hack ...\n  $ git add --patch foo            # add just first part to the index\n  $ git stash push --keep-index    # save all other changes to the stash\n                                              ^^^^^ ???\n\ni thought that, even if \"--keep-index\" left staged changes in the\nindex, it still included those staged changes in the stash. that's not\nthe impression one gets from the above.\n\nrday\n"},{"id":"347977","messageId":"CAN0heSrJMFij9xt6RstLD16+2CxJ_HALer4iRL74AZQvH0VWRQ@mail.gmail.com","threadId":"48515","inReplyTo":"alpine.LFD.2.21.1805180534170.6786@localhost.localdomain","subject":"Re: error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-05-18T10:41:51Z","receivedAt":"2018-05-18T10:41:55Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 18 May 2018 at 11:37, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n>\n>   toward the bottom of \"man git-stash\", one reads part of an example:\n>\n>   # ... hack hack hack ...\n>   $ git add --patch foo            # add just first part to the index\n>   $ git stash push --keep-index    # save all other changes to the stash\n>                                               ^^^^^ ???\n>\n> i thought that, even if \"--keep-index\" left staged changes in the\n> index, it still included those staged changes in the stash. that's not\n> the impression one gets from the above.\n\nSo would the error be in the part of the man-page quoted below?\n\n  If the --keep-index option is used, all changes already added to\n  the index are left intact.\n\nThat is, this doesn't say *where* things are left intact (in the index?\nin the working tree?). The man-page does start with\n\n  git-stash - Stash the changes in a dirty working directory away\n\nwhich to me suggests that \"leaving something intact\" refers to precisely\nthis -- the working directory.\n\nOr is it the name of the option that trips you up? That is, you read the\nname as `--keep-the-index-as-is-but-stash-as-usual`, as opposed to\n`--keep-what-is-already-in-the-index-around`?\n\nWhile I'm sure that some clarification could be provided, I'm tempted to\nargue that is exactly what the example provides that you quoted from.\n\nMartin\n"},{"id":"347978","messageId":"alpine.LFD.2.21.1805180648020.10270@localhost.localdomain","threadId":"48515","inReplyTo":"CAN0heSrJMFij9xt6RstLD16+2CxJ_HALer4iRL74AZQvH0VWRQ@mail.gmail.com","subject":"Re: error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-18T10:51:27Z","receivedAt":"2018-05-18T10:53:04Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Fri, 18 May 2018, Martin Ågren wrote:\n\n> On 18 May 2018 at 11:37, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n> >\n> >   toward the bottom of \"man git-stash\", one reads part of an example:\n> >\n> >   # ... hack hack hack ...\n> >   $ git add --patch foo            # add just first part to the index\n> >   $ git stash push --keep-index    # save all other changes to the stash\n> >                                               ^^^^^ ???\n> >\n> > i thought that, even if \"--keep-index\" left staged changes in the\n> > index, it still included those staged changes in the stash. that's\n> > not the impression one gets from the above.\n>\n> So would the error be in the part of the man-page quoted below?\n>\n>   If the --keep-index option is used, all changes already added to\n>   the index are left intact.\n\n  no, that part is correct, it clearly(?) states that staged changes\nare left where they are, in the index. i submit that the misleading\npart is in the example i quoted, which suggests that only the \"other\"\nchanges are saved to the stash -- that is, the changes other than what\nis already in the index.\n\n> That is, this doesn't say *where* things are left intact (in the\n> index? in the working tree?).\n\n  in that case, that's something that could obviously be clarified.\n\n> The man-page does start with\n>\n>   git-stash - Stash the changes in a dirty working directory away\n>\n> which to me suggests that \"leaving something intact\" refers to\n> precisely this -- the working directory.\n>\n> Or is it the name of the option that trips you up? That is, you read\n> the name as `--keep-the-index-as-is-but-stash-as-usual`, as opposed\n> to `--keep-what-is-already-in-the-index-around`?\n>\n> While I'm sure that some clarification could be provided, I'm tempted to\n> argue that is exactly what the example provides that you quoted from.\n\n  i guess we can agree to disagree, since i think the snippet of the\nexample i provided gives a misleading explanation.\n\nrday"},{"id":"347982","messageId":"CAN0heSpVKd=-Dpdk09LVtTd0vC2dLUwg0=hbxhKskM3RencsYA@mail.gmail.com","threadId":"48515","inReplyTo":"alpine.LFD.2.21.1805180648020.10270@localhost.localdomain","subject":"Re: error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-05-18T12:25:26Z","receivedAt":"2018-05-18T12:25:31Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 18 May 2018 at 12:51, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n> On Fri, 18 May 2018, Martin Ågren wrote:\n>\n>> On 18 May 2018 at 11:37, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n>> >\n>> >   toward the bottom of \"man git-stash\", one reads part of an example:\n>> >\n>> >   # ... hack hack hack ...\n>> >   $ git add --patch foo            # add just first part to the index\n>> >   $ git stash push --keep-index    # save all other changes to the stash\n>> >                                               ^^^^^ ???\n>> >\n>> > i thought that, even if \"--keep-index\" left staged changes in the\n>> > index, it still included those staged changes in the stash. that's\n>> > not the impression one gets from the above.\n\nIf I try to follow the example, it does exactly what it purports to do\nand I understand why I would want to use this exact technique with\n`--keep-index` in the situation outlined: \"you want to make two or more\ncommits out of the changes in the work tree, and you want to test each\nchange before committing\"\n\nSo I claim that the example is correct in the sense that it describes\nwhat happens when one uses git in the real world. Another question is\nwhether the example and the real-world behavior match the impression\nyou have from elsewhere, e.g., from earlier in the man-page.\n\nThat's why I asked this:\n\n>> So would the error be in the part of the man-page quoted below?\n>>\n>>   If the --keep-index option is used, all changes already added to\n>>   the index are left intact.\n>\n>   no, that part is correct, it clearly(?) states that staged changes\n> are left where they are, in the index. i submit that the misleading\n> part is in the example i quoted, which suggests that only the \"other\"\n> changes are saved to the stash -- that is, the changes other than what\n> is already in the index.\n\nCould you try the example? I think it is important that we find whether\nthe source of confusion is the example or the earlier explanation\nquoted just here.\n\n>> That is, this doesn't say *where* things are left intact (in the\n>> index? in the working tree?).\n>\n>   in that case, that's something that could obviously be clarified.\n\nWould you suggest adding something like \"both in the index and in the\nworking tree\" to what I quoted above?\n\n>> The man-page does start with\n>>\n>>   git-stash - Stash the changes in a dirty working directory away\n>>\n>> which to me suggests that \"leaving something intact\" refers to\n>> precisely this -- the working directory.\n>>\n>> Or is it the name of the option that trips you up? That is, you read\n>> the name as `--keep-the-index-as-is-but-stash-as-usual`, as opposed\n>> to `--keep-what-is-already-in-the-index-around`?\n>>\n>> While I'm sure that some clarification could be provided, I'm tempted to\n>> argue that is exactly what the example provides that you quoted from.\n>\n>   i guess we can agree to disagree, since i think the snippet of the\n> example i provided gives a misleading explanation.\n\nWe can disagree on many things, but I would very much like us to agree\non whether the example correctly describes what the command does, or\nnot.\n\nThen, if the error or source of confusion is not there, then let's\nidentify it and see if we can find out how to address it.\n\nI suggest that the source of confusion is here:\n\n  If the --keep-index option is used, all changes already added to\n  the index are left intact.\n\nMartin\n"},{"id":"347987","messageId":"96486abe-cf13-ef10-7513-2d6c20a9dc1e@gmx.de","threadId":"48515","inReplyTo":"CAN0heSpVKd=-Dpdk09LVtTd0vC2dLUwg0=hbxhKskM3RencsYA@mail.gmail.com","subject":"Re: error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Sybille Peters","fromEmail":"sypets@gmx.de","sentAt":"2018-05-18T15:37:44Z","receivedAt":"2018-05-18T15:37:49Z","isPatch":false,"sender":{"key":"sypets@gmx.de","avatar":null},"body":"My 2c on this:\n\n1) \"If the --keep-index option is used, all changes already added to the \nindex are left intact\" (manpage git stash)\n\nThat appears to be correct and clear\n\n\n2) \"$ git stash push --keep-index    # save *all other* changes to the \nstash\" (manpage git stash)\n\nThat is either not correct or misleading. \"All other\" implies in my \nopinion all changes\n\nexcept the ones that were already added. *\"All changes including already \nstaged changes\"*\n\nmight be a better choice.\n\n\nPlease also see open question on StackOverflow:\n\nhttps://stackoverflow.com/questions/50242489/how-to-ignore-added-hunks-in-git-stash-p/\n\n\n"},{"id":"347989","messageId":"alpine.LFD.2.21.1805181141030.10462@localhost.localdomain","threadId":"48515","inReplyTo":"96486abe-cf13-ef10-7513-2d6c20a9dc1e@gmx.de","subject":"Re: error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-18T15:43:48Z","receivedAt":"2018-05-18T15:45:21Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Fri, 18 May 2018, Sybille Peters wrote:\n\n> My 2c on this:\n>\n> 1) \"If the --keep-index option is used, all changes already added to\n>    the index are left intact\" (manpage git stash)\n>\n> That appears to be correct and clear\n\n  yup, that's not the issue.\n\n> 2) \"$ git stash push --keep-index # save *all other* changes to the\n>    stash\"  (manpage git stash)\n>\n> That is either not correct or misleading. \"All other\" implies in my\n> opinion all changes except the ones that were already added. *\"All\n> changes including already staged changes\"* might be a better choice.\n\n  yup, that is *exactly* the point i was trying to make.\n\nrday\n"},{"id":"347991","messageId":"CAN0heSq6YLarECVtHiPFNyUMNb-XwLQqTULpB_pSW+JZsCMw0Q@mail.gmail.com","threadId":"48515","inReplyTo":"alpine.LFD.2.21.1805181141030.10462@localhost.localdomain","subject":"Re: error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-05-18T17:14:31Z","receivedAt":"2018-05-18T17:14:36Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 18 May 2018 at 17:43, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n> On Fri, 18 May 2018, Sybille Peters wrote:\n>\n>> My 2c on this:\n>>\n>> 1) \"If the --keep-index option is used, all changes already added to\n>>    the index are left intact\" (manpage git stash)\n>>\n>> That appears to be correct and clear\n>\n>   yup, that's not the issue.\n>\n>> 2) \"$ git stash push --keep-index # save *all other* changes to the\n>>    stash\"  (manpage git stash)\n>>\n>> That is either not correct or misleading. \"All other\" implies in my\n>> opinion all changes except the ones that were already added. *\"All\n>> changes including already staged changes\"* might be a better choice.\n\nThank you Sybille for formulating these two points.\n\n>   yup, that is *exactly* the point i was trying to make.\n\nAh, this is about saving to the stash vs stashing away. The latter is\nwhat `git stash` is all about -- stashing changes *away*. At least\naccording to my mental model and the top of the man-page.\n\nBut testing this -- not only from the point of view of the example, by\npushing and popping, but by actually investigating what is in the stash\n-- finally makes me see what you mean. Yes, the whole lot gets saved to\nthe stash.\n\nSo there is a difference between what gets saved to the stash and what\ngets removed from the working directory. The comment in the example\nplaces itself somewhere in the middle by using the word \"save\" but\nreally talking about what gets dropped from the working tree.\n\nThe proposed wording does not really address that. It could be taken to\nmean \"all changes are saved to the stash; none are removed from the\nworking tree\".\n\nThe work flow in the example is about temporarily stashing a few changes\n(changes B) to test a couple of others (changes A). Whether the stash\nentry contains changes A or not is practically irrelevant to the use\ncase. At pop-time, auto-merging will do the correct thing.\n\nSo how about \"All changes are saved to the stash. Those that have been\nadded to the index are left intact in the working tree, all others are\nremoved from the working tree.\"? That's quite a lot of text. Maybe\n\"save all changes to the stash, make the working tree match the index\"?\n\nOr more to the point: \"make the working directory match the index\" or\n\"keep only what is in the index\"?\n\nMartin\n"},{"id":"348001","messageId":"alpine.LFD.2.21.1805181544240.18185@localhost.localdomain","threadId":"48515","inReplyTo":"96486abe-cf13-ef10-7513-2d6c20a9dc1e@gmx.de","subject":"Re: error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-18T20:24:35Z","receivedAt":"2018-05-18T20:26:09Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Fri, 18 May 2018, Sybille Peters wrote:\n\n> My 2c on this:\n>\n> 1) \"If the --keep-index option is used, all changes already added to\n>    the index are left intact\" (manpage git stash)\n>\n> That appears to be correct and clear\n>\n>\n> 2) \"$ git stash push --keep-index # save *all other* changes to the\n>    stash\"  (manpage git stash)\n>\n> That is either not correct or misleading. \"All other\" implies in my\n> opinion all changes except the ones that were already added. *\"All\n> changes including already staged changes\"* might be a better choice.\n>\n> Please also see open question on StackOverflow:\n>\n> https://stackoverflow.com/questions/50242489/how-to-ignore-added-hunks-in-git-stash-p/\n\n  hilariously, that SO piece refers to an issue posted to github here:\n\nhttps://github.com/progit/progit2/issues/822\n\nwhich was, in fact, posted by me. :-) in any event, let me summarize a\ncouple things here.\n\n  when i first read up on git stash, it was just that section in the\nman page that threw me, and once i figured out how it worked, i\nthought of how *i* would have explained it, and it would have gone\nlike this (assuming i do, in fact, now understand it correctly, which\nis by no means guaranteed).\n\n  first, when you do \"git stash push\", what *always* happens is that\nwhat is stashed is, in two parts, changes in the working directory,\nand what is staged in the index. clearly, the staged changes are a\nsubset of the overall working directory changes, but what's important\nis that the stash contains *all* of those changes and, more\nimportantly, distinguishes between the two categories. that's the\ncrucial part -- what is stashed (regardless of \"--keep-index\" or not)\nis:\n\n  1) staged changes\n  2) unstaged changes\n\ncan we agree on that? the only difference made by \"--keep-index\" is\nthat the staged changes, in addition to being stashed, are left in the\nindex. but that makes no difference to what is stashed, do i have that\nright?\n\n  now, when popping (or applying), what is popped are all of the\nchanges in the stash, back into the working directory. period. that\nalways happens, correct? the only difference introduced by \"--index\"\nis that the pop/apply *also* tries to restage what was staged before.\n\n  is all of the above correct? if it had been explained that way, i\nwouldn't have spent several confused hours trying to figure out why i\nwasn't getting the results i was expecting.\n\nrday\n\n"},{"id":"348076","messageId":"2472f005-4d60-7342-2e59-f60da036f622@gmx.de","threadId":"48515","inReplyTo":"CAN0heSq6YLarECVtHiPFNyUMNb-XwLQqTULpB_pSW+JZsCMw0Q@mail.gmail.com","subject":"Re: error(?) in \"man git-stash\" regarding \"--keep-index\"","fromName":"Sybille Peters","fromEmail":"sypets@gmx.de","sentAt":"2018-05-19T10:05:29Z","receivedAt":"2018-05-19T10:05:35Z","isPatch":false,"sender":{"key":"sypets@gmx.de","avatar":null},"body":"On 18.05.2018 19:14, Martin Ågren wrote:\n> On 18 May 2018 at 17:43, Robert P. J. Day <rpjday@crashcourse.ca> wrote:\n\n...\n\n> Ah, this is about saving to the stash vs stashing away. The latter is\n> what `git stash` is all about -- stashing changes *away*. At least\n> according to my mental model and the top of the man-page.\n\nStashing changes *away* would mean a move in my mental model (as in\ncommand line mv): Whatever gets copied to stash gets removed in working \narea. And what doesn't get removed, doesn't get copied to stash.\n\nThus, --keep-index *would* ignore the index and only move working-tree\nto the stash minus the changes already staged.\n\nBUT, that might lead to other problems, I suppose.\n\nThe current behaviour can cause problems as in the Stackoverflow\nquestion where someone already staged some hunks, and on\nstashing with -p gets asked about these *again*. Which does make\nthe workflow more tedious.\n\n\n> \n> ...\n> \n> The work flow in the example is about temporarily stashing a few changes\n> (changes B) to test a couple of others (changes A). Whether the stash\n> entry contains changes A or not is practically irrelevant to the use\n> case. At pop-time, auto-merging will do the correct thing.\n\nAha, now it gets interesting. So you are saying, it doesn't matter if\nthe stash entry also contains the already staged changes A? Well in the \ncombination with -p it does (see Stackoverflow question and above).\n\nEven if auto-merging will take care of it (?), it would be good to\nhave the manpage clarify things that might confuse people.\n\nDisclaimer: I am not a git expert, so I may be getting things wrong. I\njust noticed the Stackoverflow question, answered it (only because\nan adequate answer did not exist yet) and then saw a similar topic\nbeing raised here.\n\n> \n> So how about \"All changes are saved to the stash. Those that have been\n> added to the index are left intact in the working tree, all others are\n> removed from the working tree.\"? That's quite a lot of text. Maybe\n> \"save all changes to the stash, make the working tree match the index\"?\n> \n> Or more to the point: \"make the working directory match the index\" or\n> \"keep only what is in the index\"?\n\n\nI am not sure yet about the text. Still in the clarifying phase.\n\nSybille\n\n> \n> Martin\n> \n"}]}