On 18 May 2018 at 12:51, Robert P. J. Day <rpjday@xxxxxxxxxxxxxx> wrote: > On Fri, 18 May 2018, Martin Ågren wrote: > >> On 18 May 2018 at 11:37, Robert P. J. Day <rpjday@xxxxxxxxxxxxxx> wrote: >> > >> > toward the bottom of "man git-stash", one reads part of an example: >> > >> > # ... hack hack hack ... >> > $ git add --patch foo # add just first part to the index >> > $ git stash push --keep-index # save all other changes to the stash >> > ^^^^^ ??? >> > >> > i thought that, even if "--keep-index" left staged changes in the >> > index, it still included those staged changes in the stash. that's >> > not the impression one gets from the above. If I try to follow the example, it does exactly what it purports to do and I understand why I would want to use this exact technique with `--keep-index` in the situation outlined: "you want to make two or more commits out of the changes in the work tree, and you want to test each change before committing" So I claim that the example is correct in the sense that it describes what happens when one uses git in the real world. Another question is whether the example and the real-world behavior match the impression you have from elsewhere, e.g., from earlier in the man-page. That's why I asked this: >> So would the error be in the part of the man-page quoted below? >> >> If the --keep-index option is used, all changes already added to >> the index are left intact. > > no, that part is correct, it clearly(?) states that staged changes > are left where they are, in the index. i submit that the misleading > part is in the example i quoted, which suggests that only the "other" > changes are saved to the stash -- that is, the changes other than what > is already in the index. Could you try the example? I think it is important that we find whether the source of confusion is the example or the earlier explanation quoted just here. >> That is, this doesn't say *where* things are left intact (in the >> index? in the working tree?). > > in that case, that's something that could obviously be clarified. Would you suggest adding something like "both in the index and in the working tree" to what I quoted above? >> The man-page does start with >> >> git-stash - Stash the changes in a dirty working directory away >> >> which to me suggests that "leaving something intact" refers to >> precisely this -- the working directory. >> >> Or is it the name of the option that trips you up? That is, you read >> the name as `--keep-the-index-as-is-but-stash-as-usual`, as opposed >> to `--keep-what-is-already-in-the-index-around`? >> >> While I'm sure that some clarification could be provided, I'm tempted to >> argue that is exactly what the example provides that you quoted from. > > i guess we can agree to disagree, since i think the snippet of the > example i provided gives a misleading explanation. We can disagree on many things, but I would very much like us to agree on whether the example correctly describes what the command does, or not. Then, if the error or source of confusion is not there, then let's identify it and see if we can find out how to address it. I suggest that the source of confusion is here: If the --keep-index option is used, all changes already added to the index are left intact. Martin
