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

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

[-- Attachment #1: Type: text/plain, Size: 1959 bytes --]

On Fri, 18 May 2018, Martin Ågren wrote:

> On 18 May 2018 at 11:37, Robert P. J. Day <rpjday@crashcourse.ca> 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.
>
> 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.

> 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.

> 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.

rday