[PATCH] Documentation: reset: describe new "--keep" option

[PATCH] Documentation: reset: describe new "--keep" option

[Christian Couder]

and give an example to show how it can be used.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-reset.txt |   49 ++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 48 insertions(+), 1 deletions(-)

This patch replaces the patch with the same name currently in pu.
The example given at then end is much improved, thanks to Junio.

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 168db08..1e9ae0a 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -8,7 +8,7 @@ git-reset - Reset current HEAD to the specified state
 SYNOPSIS
 --------
 [verse]
-'git reset' [--mixed | --soft | --hard | --merge] [-q] [<commit>]
+'git reset' [--mixed | --soft | --hard | --merge | --keep] [-q] [<commit>]
 'git reset' [-q] [<commit>] [--] <paths>...
 'git reset' --patch [<commit>] [--] [<paths>...]
 
@@ -52,6 +52,11 @@ OPTIONS
 	and updates the files that are different between the named commit
 	and the current commit in the working tree.
 
+--keep::
+	Resets the index to match the tree recorded by the named commit,
+	but keep changes in the working tree. Aborts if the reset would
+	change files that are already modified in the working tree.
+
 -p::
 --patch::
 	Interactively select hunks in the difference between the index
@@ -93,6 +98,7 @@ in the index and in state D in HEAD.
 				--mixed  A       D     D
 				--hard   D       D     D
 				--merge (disallowed)
+				--keep  (disallowed)
 
       working index HEAD target         working index HEAD
       ----------------------------------------------------
@@ -100,6 +106,7 @@ in the index and in state D in HEAD.
 				--mixed  A       C     C
 				--hard   C       C     C
 				--merge (disallowed)
+				--keep   A       C     C
 
       working index HEAD target         working index HEAD
       ----------------------------------------------------
@@ -107,6 +114,7 @@ in the index and in state D in HEAD.
 				--mixed  B       D     D
 				--hard   D       D     D
 				--merge  D       D     D
+				--keep  (disallowed)
 
       working index HEAD target         working index HEAD
       ----------------------------------------------------
@@ -114,6 +122,7 @@ in the index and in state D in HEAD.
 				--mixed  B       C     C
 				--hard   C       C     C
 				--merge  C       C     C
+				--keep   B       C     C
 
       working index HEAD target         working index HEAD
       ----------------------------------------------------
@@ -121,6 +130,7 @@ in the index and in state D in HEAD.
 				--mixed  B       D     D
 				--hard   D       D     D
 				--merge (disallowed)
+				--keep  (disallowed)
 
       working index HEAD target         working index HEAD
       ----------------------------------------------------
@@ -128,6 +138,7 @@ in the index and in state D in HEAD.
 				--mixed  B       C     C
 				--hard   C       C     C
 				--merge  B       C     C
+				--keep   B       C     C
 
 "reset --merge" is meant to be used when resetting out of a conflicted
 merge. Any mergy operation guarantees that the work tree file that is
@@ -138,6 +149,14 @@ between the index and the work tree, then it means that we are not
 resetting out from a state that a mergy operation left after failing
 with a conflict. That is why we disallow --merge option in this case.
 
+"reset --keep" is meant to be used when removing some of the last
+commits in the current branch while keeping changes in the working
+tree. If there could be conflicts between the changes in the commit we
+want to remove and the changes in the working tree we want to keep,
+the reset is disallowed. That's why it is disallowed if there are both
+changes between the working tree and HEAD, and between HEAD and the
+target.
+
 The following tables show what happens when there are unmerged
 entries:
 
@@ -147,6 +166,7 @@ entries:
 				--mixed  X       B     B
 				--hard   B       B     B
 				--merge  B       B     B
+				--keep  (disallowed)
 
       working index HEAD target         working index HEAD
       ----------------------------------------------------
@@ -154,6 +174,7 @@ entries:
 				--mixed  X       A     A
 				--hard   A       A     A
 				--merge  A       A     A
+				--keep   X       A     A
 
 X means any state and U means an unmerged index.
 
@@ -325,6 +346,32 @@ $ git add frotz.c                           <3>
 <2> This commits all other changes in the index.
 <3> Adds the file to the index again.
 
+Keep changes in working tree while discarding some previous commits::
++
+Suppose you are working on something and you commit it, and then you
+continue working a bit more, but now you think that what you have in
+your working tree should be in another branch that has nothing to do
+with what you commited previously. You can start a new branch and
+reset it while keeping the changes in your work tree.
++
+------------
+$ git tag start
+$ git checkout -b branch1
+$ edit
+$ git commit ...                            <1>
+$ edit
+$ git checkout -b branch2                   <2>
+$ git reset --keep start                    <3>
+------------
++
+<1> This commits your first edits in branch1.
+<2> In the ideal world, you could have realized that the earlier
+    commit did not belong to the new topic when you created and switched
+    to branch2 (i.e. "git checkout -b branch2 start"), but nobody is
+    perfect.
+<3> But you can use "reset --keep" to remove the unwanted commit after
+    you switched to "branch2".
+
 Author
 ------
 Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds <torvalds@osdl.org>
-- 
1.7.0.1.335.g17865

Re: [PATCH] Documentation: reset: describe new "--keep" option

[Peter Baumann]

On Fri, Mar 05, 2010 at 09:25:36PM +0100, Christian Couder wrote:
> and give an example to show how it can be used.
> 
> +--keep::
> +	Resets the index to match the tree recorded by the named commit,
> +	but keep changes in the working tree. Aborts if the reset would
> +	change files that are already modified in the working tree.
> +
 
Huh? Keep changes (by not touching the worktree) and then aborting if we
touch the worktree. Seems like a contradiction to me.

--
Peter

Re: [PATCH] Documentation: reset: describe new "--keep" option

[Christian Couder]

On Saturday 06 March 2010 09:10:34 Peter Baumann wrote:
> On Fri, Mar 05, 2010 at 09:25:36PM +0100, Christian Couder wrote:
> > and give an example to show how it can be used.
> >
> > +--keep::
> > +	Resets the index to match the tree recorded by the named commit,
> > +	but keep changes in the working tree. Aborts if the reset would
> > +	change files that are already modified in the working tree.
> > +
> 
> Huh? Keep changes (by not touching the worktree)

Keep uncommited changes in the working tree does not mean not touching the 
working tree.

> and then aborting if we
> touch the worktree.

We abort if the commit we reset touch some files that have uncommited changes.

> Seems like a contradiction to me.

There is no contradiction. We repeat "working tree" too much perhaps, but what 
is important is to focus on "changes" and "files".

Regards,
Christian.

Re: [PATCH] Documentation: reset: describe new "--keep" option

[Junio C Hamano]

Christian Couder <chriscool@tuxfamily.org> writes:

> and give an example to show how it can be used.
>
> Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---

Thanks.  With the example I think I can tell others that this at least has
one known use case that is not totally whacky.

I haven't re-read Peter Baumann's comments that you dismissed as a
mis-reading of your added documentation, but if somebody _can_ misread
what you wrote, that is a sign that it has a room to be improved for
clarity.

Re: [PATCH] Documentation: reset: describe new "--keep" option

[Christian Couder]

On Sunday 07 March 2010 06:52:46 Junio C Hamano wrote:
> Christian Couder <chriscool@tuxfamily.org> writes:
> > and give an example to show how it can be used.
> >
> > Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> > Signed-off-by: Junio C Hamano <gitster@pobox.com>
> > ---
> 
> Thanks.  With the example I think I can tell others that this at least has
> one known use case that is not totally whacky.
> 
> I haven't re-read Peter Baumann's comments that you dismissed as a
> mis-reading of your added documentation, but if somebody _can_ misread
> what you wrote, that is a sign that it has a room to be improved for
> clarity.

Ok, so instead of:

> +--keep::
> +     Resets the index to match the tree recorded by the named commit,
> +     but keep changes in the working tree. Aborts if the reset would
> +     change files that are already modified in the working tree.

what about:

--keep::
     Resets the index to match the tree recorded by the named commit,
     but changed files in the working tree are kept untouched. Aborts if the
     reset would touch any of them.

?

Thanks,
Christian.

Re: [PATCH] Documentation: reset: describe new "--keep" option

[Junio C Hamano]

Peter Baumann <waste.manager@gmx.de> writes:

> On Fri, Mar 05, 2010 at 09:25:36PM +0100, Christian Couder wrote:
>> and give an example to show how it can be used.
>> 
>> +--keep::
>> +	Resets the index to match the tree recorded by the named commit,
>> +	but keep changes in the working tree. Aborts if the reset would
>> +	change files that are already modified in the working tree.
>> +
>  
> Huh? Keep changes (by not touching the worktree) and then aborting if we
> touch the worktree. Seems like a contradiction to me.

Here is my try...

    Reset the index to the given commit, keeping local changes in the working
    tree since the current commit, while updating working tree files without
    local changes to what appears in the given commit.  If a file that is
    different between the current commit and the given commit has local
    changes, reset is aborted.

Re: [PATCH] Documentation: reset: describe new "--keep" option

[Peter Baumann]

On Sun, Mar 07, 2010 at 09:38:18PM +0100, Christian Couder wrote:
> On Sunday 07 March 2010 06:52:46 Junio C Hamano wrote:
> > Christian Couder <chriscool@tuxfamily.org> writes:
> > > and give an example to show how it can be used.
> > >
> > > Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> > > Signed-off-by: Junio C Hamano <gitster@pobox.com>
> > > ---
> > 
> > Thanks.  With the example I think I can tell others that this at least has
> > one known use case that is not totally whacky.
> > 
> > I haven't re-read Peter Baumann's comments that you dismissed as a
> > mis-reading of your added documentation, but if somebody _can_ misread
> > what you wrote, that is a sign that it has a room to be improved for
> > clarity.
> 
> Ok, so instead of:
> 
> > +--keep::
> > +     Resets the index to match the tree recorded by the named commit,
> > +     but keep changes in the working tree. Aborts if the reset would
> > +     change files that are already modified in the working tree.
> 
> what about:
> 
> --keep::
>      Resets the index to match the tree recorded by the named commit,

My reading of this (non native english speaker): Given the --keep flag,
*only* the index is updated.

>      but changed files in the working tree are kept untouched. 
>      Aborts if the reset would touch any of them.

Huh? Does it touch the work tree, too? You propably know by now where this
leads :-)

I have to admit I like Junio's version better, because at least it is clear
that the worktree is also touched.

--
Peter

Re: [PATCH] Documentation: reset: describe new "--keep" option

[Christian Couder]

On Mon, Mar 8, 2010 at 9:31 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Peter Baumann <waste.manager@gmx.de> writes:
>
>> Huh? Keep changes (by not touching the worktree) and then aborting if we
>> touch the worktree. Seems like a contradiction to me.
>
> Here is my try...
>
>    Reset the index to the given commit, keeping local changes in the working
>    tree since the current commit, while updating working tree files without
>    local changes to what appears in the given commit.  If a file that is
>    different between the current commit and the given commit has local
>    changes, reset is aborted.

I agree that it is better. I will post a patch with this change this
evening if you don't do it before.

Thanks,
Christian.