Re: [PATCH] doc: emphasize stash "--keep-index" stashes staged content

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Robert P. J. Day wrote:

> It's not immediately obvious from the man page that the "--keep-index"
> option still adds the staged content to the stash, so make that
> abundantly clear.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> ---
>
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index 00f95fee1..037144037 100644
> --- a/Documentation/git-stash.txt
> +++ b/Documentation/git-stash.txt
> @@ -68,8 +68,8 @@ entries and working tree files are then rolled back to the state in
>  HEAD only for these files, too, leaving files that do not match the
>  pathspec intact.
>  +
> -If the `--keep-index` option is used, all changes already added to the
> -index are left intact.
> +If the `--keep-index` option is used, all changes already staged in the
> +index are left intact in the index, while still being added to the stash.

Aside from Junio's note about "in the index" vs "in the working tree":

The "Testing partial commits" item in the EXAMPLES section explains
what --keep-index is useful for.  I wonder if some allusion to that
would make the explanation in the OPTIONS section easier to
understand.

Something that I end up still curious about when reading this
description is what will happen when I "git stash pop".  Will it apply
only the changes that were stashed away and removed from the working
tree, or will it apply the changes that were kept in the index, too?
If the latter, why?  Is there some way I can turn that behavior off?

E.g. in the "Testing partial commits" example, it seems like the
natural behavior for "git stash pop" would be just restore the changes
that were removed from the working tree.  That would also match an
assumption of save/push and pop being symmetrical ('inverse
operations').

Is this related to "git stash pop --index"?  I notice that the
EXAMPLES section doesn't give any examples of that option.

Thanks,
Jonathan