patchgit-stash.txt: Add new example

From: Jari Aalto <jari.aalto@cante.net>

Add new example "Saving selected files to stash" thanks to ideas by Johan Sageryd <j416@1616.se>.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-stash.txt |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)

jari.aalto@cante.net writes:

While the above is not _wrong_ per-se, it was somewhat hard to understand for me without a description on _why_ you might want to do this. It didn't help that "put only selected files" really meant "get rid of selected _changes_ from the working tree and the index temporarily".

I'd perhaps suggest rephrasing it like this:

        Sifting the Wheat from the Chaff::

        When you have changes to the working tree that mix what are
        necessary for the immediate task at hand, and what are needed
        later but not right now, you can first `git add` only the former
        and use `git stash save --keep-index` to get rid of the latter.
        The latter is temporarily stored in the stash.  

        Suppose you have changes to file A, B, and C, but only the half of
        changes to file A and C are necessary for what you are doing:

        $ git reset                     # make the index clean
        $ git add -p A C                # add necessary bits to the index
        $ git stash save --keep-index   # the remainder goes to the stash
        ... test, debug, perfect ...
        $ git commit
        $ git stash pop                 # get the remainder back
        ... and continue to work ...

Add a new example to demonstrate the use of --keep-index. Idea by Johan Sageryd <j416@1616.se>.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-stash.txt |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)

This demonstrates the difference between the end-user and developer. The end-used think in term of tangible objects: "I have files, I need to stash some of them".

As a non-native, to my regret, I'm unable to compherend this Heading, my suggestion in patch v2:

    "Using stash selectively"

I've rewritten the patch based on the comments. Please review.

Jari

Am 5/6/2010 10:40, schrieb Jari Aalto:

Isn't "the remainder goes to the stash" wrong? I thought that both worktree changes and index go to stash; only that changes recorded in the index are not undone in the index and worktree.

And here both changes are unstashed, but since the changes that previously were only in the index are already commited, it looks as if no index changes were unstashed.

The distinction is important because if you 'stash --keep-index', but then change your mind and 'reset --hard', you actually do *not* lose data because the index changes are still in the stash.

Or spelled in a different way: you cannot undo the index changes and keep only the worktree changes by 'stash --keep-index', 'reset --hard', 'stash pop'.

-- Hannes

Add a new example to demonstrate the use of --keep-index. Idea by Johan Sageryd <j416@1616.se> and Johannes Sixt <j.sixt@viscovery.net>.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-stash.txt |   22 ++++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)

    Johannes Sixt <j.sixt@viscovery.net> writes:

    > Am 5/6/2010 10:40, schrieb Jari Aalto:
    >
    >> +$ git reset                     # make the index clean
    >> +$ git add -p A C                # add necessary bits to the index
    >> +$ git stash save --keep-index   # the remainder goes to the stash
    >
    > Isn't "the remainder goes to the stash" wrong? I thought that both
    > worktree changes and index go to stash; only that changes recorded in the
    > index are not undone in the index and worktree.
    >
    >> +... test, debug, perfect ...
    >> +$ git commit
    >> +$ git stash pop                 # get the remainder back
    >
    > And here both changes are unstashed, but since the changes that previously
    > were only in the index are already commited, it looks as if no index
    > changes were unstashed.
    >
    > The distinction is important because if you 'stash --keep-index', but then
    > change your mind and 'reset --hard', you actually do *not* lose data
    > because the index changes are still in the stash.
    >
    > Or spelled in a different way: you cannot undo the index changes and keep
    > only the worktree changes by 'stash --keep-index', 'reset --hard', 'stash
    > pop'.

    Reworked based on comments. Let me know if more is needed.

    Jari

Jari Aalto <jari.aalto@cante.net> writes:

Not really. You just demonstrated that you ignored "partial add". It is not so unusual for a user to need to express "I have a file, and I have two kinds of changes to it. The ones that I need now and the ones I need to postpone".