Re: error(?) in "man git-stash" regarding "--keep-index"

["Robert P. J. Day" <rpjday@crashcourse.ca>]

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
>
>
> 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.
>
> Please also see open question on StackOverflow:
>
> https://stackoverflow.com/questions/50242489/how-to-ignore-added-hunks-in-git-stash-p/

  hilariously, that SO piece refers to an issue posted to github here:

https://github.com/progit/progit2/issues/822

which was, in fact, posted by me. :-) in any event, let me summarize a
couple things here.

  when i first read up on git stash, it was just that section in the
man page that threw me, and once i figured out how it worked, i
thought of how *i* would have explained it, and it would have gone
like this (assuming i do, in fact, now understand it correctly, which
is by no means guaranteed).

  first, when you do "git stash push", what *always* happens is that
what is stashed is, in two parts, changes in the working directory,
and what is staged in the index. clearly, the staged changes are a
subset of the overall working directory changes, but what's important
is that the stash contains *all* of those changes and, more
importantly, distinguishes between the two categories. that's the
crucial part -- what is stashed (regardless of "--keep-index" or not)
is:

  1) staged changes
  2) unstaged changes

can we agree on that? the only difference made by "--keep-index" is
that the staged changes, in addition to being stashed, are left in the
index. but that makes no difference to what is stashed, do i have that
right?

  now, when popping (or applying), what is popped are all of the
changes in the stash, back into the working directory. period. that
always happens, correct? the only difference introduced by "--index"
is that the pop/apply *also* tries to restage what was staged before.

  is all of the above correct? if it had been explained that way, i
wouldn't have spent several confused hours trying to figure out why i
wasn't getting the results i was expecting.

rday