[PATCH] git-stash.txt: Add new example

[PATCH] git-stash.txt: Add new example

[jari.aalto]

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(-)

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 473889a..7d9f9e1 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -230,6 +230,18 @@ $ edit/build/test remaining parts
 $ git commit foo -m 'Remaining parts'
 ----------------------------------------------------------------
 
+Saving selected files to stash::
+
+You can use `git stash save --keep-index` to put only selected files
+into the stash. Let's suppose the files A, B, C and D are modified and
+you want to stash only C and D:
++
+----------------------------------------------------------------
+$ git status			# Verify what's modified
+$ git add A B			# ...not these
+$ git stash save --keep-index   # ...but stash all the others
+----------------------------------------------------------------
+
 Recovering stashes that were cleared/dropped erroneously::
 
 If you mistakenly drop or clear stashes, they cannot be recovered
-- 
1.7.0

Re: [PATCH] git-stash.txt: Add new example

[Junio C Hamano]

jari.aalto@cante.net writes:

> 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(-)
>
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index 473889a..7d9f9e1 100644
> --- a/Documentation/git-stash.txt
> +++ b/Documentation/git-stash.txt
> @@ -230,6 +230,18 @@ $ edit/build/test remaining parts
>  $ git commit foo -m 'Remaining parts'
>  ----------------------------------------------------------------
>  
> +Saving selected files to stash::
> +
> +You can use `git stash save --keep-index` to put only selected files
> +into the stash. Let's suppose the files A, B, C and D are modified and
> +you want to stash only C and D:
> ++
> +----------------------------------------------------------------
> +$ git status			# Verify what's modified
> +$ git add A B			# ...not these
> +$ git stash save --keep-index   # ...but stash all the others
> +----------------------------------------------------------------
> +

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

[PATCH v2] git-stash.txt: Add example "Using stash selectively"

[Jari Aalto]

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(-)


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

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

> I'd perhaps suggest rephrasing it like this:
>
>         Sifting the Wheat from the Chaff::

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

    "Using stash selectively"

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

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

Jari


diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 473889a..b3fa1e7 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -243,6 +243,22 @@ grep commit | cut -d\  -f3 |
 xargs git log --merges --no-walk --grep=WIP
 ----------------------------------------------------------------
 
+Using stash selectively::
+
+The `--keep-index` option can be useful in a situation where you want
+store some, but not all, files temporarily 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 ...
+----------------------------------------------------------------
 
 SEE ALSO
 --------
-- 
1.7.0

Re: [PATCH v2] git-stash.txt: Add example "Using stash selectively"

[Johannes Sixt]

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

-- Hannes

[PATCH v3] git-stash.txt: Add example "Using stash selectively"

[Jari Aalto]

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


diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 473889a..bde5120 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -243,6 +243,28 @@ grep commit | cut -d\  -f3 |
 xargs git log --merges --no-walk --grep=WIP
 ----------------------------------------------------------------
 
+Using stash selectively::
+
+The `--keep-index` option can be useful in a situation where you want
+store some, but not all, files temporarily in the stash. But keep in
+mind that it still records the whole tree (unless --patch is
+specified). 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.
++
+So if you don't plan to reset the following workflow may be handy.
+Suppose you have changes to files A, B, C; you continue to edit A and
+B, but want to stash C:
++
+----------------------------------------------------------------
+$ git reset                     # make the index clean
+$ git add -p A C                # add necessary bits to the index
+$ git stash save --keep-index   # current index is left untouched
+... test, debug, perfect ...
+$ git commit
+$ git stash pop                 # get the remainder back
+... and continue to work ...
+----------------------------------------------------------------
 
 SEE ALSO
 --------
-- 
1.7.0

Re: [PATCH v2] git-stash.txt: Add example "Using stash selectively"

[Junio C Hamano]

Jari Aalto <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".
>
> 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".

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