On 18 May 2018 at 17:43, Robert P. J. Day <rpj...@crashcourse.ca> wrote: > On Fri, 18 May 2018, Sybille Peters wrote: > >> My 2c on this: >> >> 1) "If the --keep-index option is used, all changes already added to >> the index are left intact" (manpage git stash) >> >> That appears to be correct and clear > > yup, that's not the issue. > >> 2) "$ git stash push --keep-index # save *all other* changes to the >> stash" (manpage git stash) >> >> That is either not correct or misleading. "All other" implies in my >> opinion all changes except the ones that were already added. *"All >> changes including already staged changes"* might be a better choice.
Thank you Sybille for formulating these two points. > yup, that is *exactly* the point i was trying to make. Ah, this is about saving to the stash vs stashing away. The latter is what `git stash` is all about -- stashing changes *away*. At least according to my mental model and the top of the man-page. But testing this -- not only from the point of view of the example, by pushing and popping, but by actually investigating what is in the stash -- finally makes me see what you mean. Yes, the whole lot gets saved to the stash. So there is a difference between what gets saved to the stash and what gets removed from the working directory. The comment in the example places itself somewhere in the middle by using the word "save" but really talking about what gets dropped from the working tree. The proposed wording does not really address that. It could be taken to mean "all changes are saved to the stash; none are removed from the working tree". The work flow in the example is about temporarily stashing a few changes (changes B) to test a couple of others (changes A). Whether the stash entry contains changes A or not is practically irrelevant to the use case. At pop-time, auto-merging will do the correct thing. So how about "All changes are saved to the stash. Those that have been added to the index are left intact in the working tree, all others are removed from the working tree."? That's quite a lot of text. Maybe "save all changes to the stash, make the working tree match the index"? Or more to the point: "make the working directory match the index" or "keep only what is in the index"? Martin
