Re: PATCH] Documentation: Tweak use case in "git stash save --keep-index"

[Junio C Hamano <gitster@pobox.com>]

"Eric Raible" <raible@gmail.com> writes:

> The documentation suggests using "git stash apply" in the
> --keep-index workflow even though doing so will lead to clutter
> in the stash.  And given that the changes are about to be
> committed anyway "git stash pop" is more sensible.

Yeah, I was pondering about this myself.  After popping the remaining
part, you would "git add -p" the next batch, the same "stash save -k-i" to
save the remaining bits away, and continue.  Will queue.

BUT

It is very likely that in this workflow you would sometimes find that what
you staged (and left in the working tree after "save -k-i") is faulty and
you need to tweak it in place to make it into a good enough shape for
committing.  The example probably should talk about what happens.
Editing, testing and committing is fine, but then what?  Will the "pop"
wipe that unplanned change you made after "save -k-i" out? (the answer is
no and this is safe, but the reader of the documentaiton needs it
explained)

Also this may be a good way to split an existing commit into five during a
"rebase -i" session, and the example in the documentation might want to
talk about it in that larger picture.

>  Documentation/git-stash.txt |    5 +++--
>  1 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index df26901..bf241da 100644
> --- a/Documentation/git-stash.txt
> +++ b/Documentation/git-stash.txt
> @@ -201,9 +201,10 @@ $ git add --patch foo
>  $ git stash save --keep-index
>  $ build && run tests
>  $ git commit -m 'First part'
> -$ git stash apply
> +$ git stash pop
> +... repeat above five steps until one commit remains ...
>  $ build && run tests
> -$ git commit -a -m 'Second part'
> +$ git commit foo -m 'Remaining parts'
>  ----------------------------------------------------------------