From 7349df1142a8dba579c015b51805cc290fcb4e6e Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Fri, 5 Mar 2010 21:25:36 +0100 Subject: Documentation: reset: describe new "--keep" option and give an example to show how it can be used. Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-reset.txt | 49 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 168db08627..1e9ae0ae9f 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] [] +'git reset' [--mixed | --soft | --hard | --merge | --keep] [-q] [] 'git reset' [-q] [] [--] ... 'git reset' --patch [] [--] [...] @@ -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 and Linus Torvalds -- cgit v1.2.1 From 812d2a3d61b1bbb1931aff2ed6d2a17e939f5bf2 Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Tue, 19 Jan 2010 05:26:01 +0100 Subject: reset: disallow using --keep when there are unmerged entries The use case for --keep option is to remove previous commits unrelated to the current changes in the working tree. So in this use case we are not supposed to have unmerged entries. This is why it seems safer to just disallow using --keep when there are unmerged entries. And this patch changes the error message when --keep was disallowed and there were some unmerged entries from: error: Entry 'file1' would be overwritten by merge. Cannot merge. fatal: Could not reset index file to revision 'HEAD^'. to: fatal: Cannot do a keep reset in the middle of a merge. which is nicer. Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-reset.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 1e9ae0ae9f..58d9b4c062 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -155,7 +155,8 @@ 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. +target. To be safe, it is also disallowed when there are unmerged +entries. The following tables show what happens when there are unmerged entries: @@ -174,7 +175,7 @@ entries: --mixed X A A --hard A A A --merge A A A - --keep X A A + --keep (disallowed) X means any state and U means an unmerged index. -- cgit v1.2.1 From eaf436c09c09a28804697c89f3ff9a7e1ad2361c Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 9 Mar 2010 02:51:16 +0100 Subject: Documentation: improve description of "git reset --keep" Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-reset.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 58d9b4c062..645f0c1748 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -53,9 +53,12 @@ OPTIONS 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. + 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. -p:: --patch:: -- cgit v1.2.1