From 4086010c7c83d907321ae1357569dfcc01710cb6 Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Wed, 30 Dec 2009 06:54:45 +0100 Subject: Documentation: reset: add some tables to describe the different options This patch adds a DISCUSSION section that contains some tables to show how the different "git reset" options work depending on the states of the files in the working tree, the index, HEAD and the target commit. Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-reset.txt | 66 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) (limited to 'Documentation') diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 2d27e405a3..2198c8ebd6 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -67,6 +67,72 @@ linkgit:git-add[1]). :: Commit to make the current HEAD. If not given defaults to HEAD. +DISCUSSION +---------- + +The tables below show what happens when running: + +---------- +git reset --option target +---------- + +to reset the HEAD to another commit (`target`) with the different +reset options depending on the state of the files. + + working index HEAD target working index HEAD + ---------------------------------------------------- + A B C D --soft A B D + --mixed A D D + --hard D D D + --merge (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + A B C C --soft A B C + --mixed A C C + --hard C C C + --merge (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + B B C D --soft B B D + --mixed B D D + --hard D D D + --merge D D D + + working index HEAD target working index HEAD + ---------------------------------------------------- + B B C C --soft B B C + --mixed B C C + --hard C C C + --merge C C C + +In these tables, A, B, C and D are some different states of a +file. For example, the last line of the last table means that if a +file is in state B in the working tree and the index, and in a +different state C in HEAD and in the target, then "git reset +--merge target" will put the file in state C in the working tree, +in the index and in HEAD. + +The following tables show what happens when there are unmerged +entries: + + working index HEAD target working index HEAD + ---------------------------------------------------- + X U A B --soft (disallowed) + --mixed X B B + --hard B B B + --merge (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + X U A A --soft (disallowed) + --mixed X A A + --hard A A A + --merge (disallowed) + +X means any state and U means an unmerged index. + Examples -------- -- cgit v1.2.3 From d0f379c2dcf7198d373b3c64444019bed2e24336 Mon Sep 17 00:00:00 2001 From: Stephan Beyer Date: Wed, 30 Dec 2009 06:54:47 +0100 Subject: reset: use "unpack_trees()" directly instead of "git read-tree" This patch makes "reset_index_file()" call "unpack_trees()" directly instead of forking and execing "git read-tree". So the code is more efficient. And it's also easier to see which unpack_tree() options will be used, as we don't need to follow "git read-tree"'s command line parsing which is quite complex. As Daniel Barkalow found, there is a difference between this new version and the old one. The old version gives an error for "git reset --merge" with unmerged entries, and the new version does not when we reset the entries to some states that differ from HEAD. Instead, it resets the index entry and succeeds, while leaving the conflict markers in the corresponding file in the work tree (which will be corrected by the next patch). The code comes from the sequencer GSoC project: git://repo.or.cz/git/sbeyer.git (at commit 5a78908b70ceb5a4ea9fd4b82f07ceba1f019079) Mentored-by: Daniel Barkalow Mentored-by: Christian Couder Signed-off-by: Stephan Beyer Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-reset.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 2198c8ebd6..cf2433d52c 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -122,7 +122,7 @@ entries: X U A B --soft (disallowed) --mixed X B B --hard B B B - --merge (disallowed) + --merge X B B working index HEAD target working index HEAD ---------------------------------------------------- -- cgit v1.2.3 From e11d7b5969704cd5ce39d053414d905bb203886b Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 31 Dec 2009 23:04:04 -0800 Subject: "reset --merge": fix unmerged case Commit 9e8ecea (Add 'merge' mode to 'git reset', 2008-12-01) disallowed "git reset --merge" when there was unmerged entries. But it wished if unmerged entries were reset as if --hard (instead of --merge) has been used. This makes sense because all "mergy" operations makes sure that any path involved in the merge does not have local modifications before starting, so resetting such a path away won't lose any information. The previous commit changed the behavior of --merge to accept resetting unmerged entries if they are reset to a different state than HEAD, but it did not reset the changes in the work tree, leaving the conflict markers in the resulting file in the work tree. Fix it by doing three things: - Update the documentation to match the wish of original "reset --merge" better, namely, "An unmerged entry is a sign that the path didn't have any local modification and can be safely resetted to whatever the new HEAD records"; - Update read_index_unmerged(), which reads the index file into the cache while dropping any higher-stage entries down to stage #0, not to copy the object name from the higher stage entry. The code used to take the object name from the a stage entry ("base" if you happened to have stage #1, or "ours" if both sides added, etc.), which essentially meant that you are getting random results depending on what the merge did. The _only_ reason we want to keep a previously unmerged entry in the index at stage #0 is so that we don't forget the fact that we have corresponding file in the work tree in order to be able to remove it when the tree we are resetting to does not have the path. In order to differentiate such an entry from ordinary cache entry, the cache entry added by read_index_unmerged() is marked as CE_CONFLICTED. - Update merged_entry() and deleted_entry() so that they pay attention to cache entries marked as CE_CONFLICTED. They are previously unmerged entries, and the files in the work tree that correspond to them are resetted away by oneway_merge() to the version from the tree we are resetting to. Signed-off-by: Junio C Hamano --- Documentation/git-reset.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index cf2433d52c..dc73dca736 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -122,14 +122,14 @@ entries: X U A B --soft (disallowed) --mixed X B B --hard B B B - --merge X B B + --merge B B B working index HEAD target working index HEAD ---------------------------------------------------- X U A A --soft (disallowed) --mixed X A A --hard A A A - --merge (disallowed) + --merge A A A X means any state and U means an unmerged index. -- cgit v1.2.3 From 397d596f84209d0e9d17621ce56b5432bc98d368 Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Tue, 5 Jan 2010 06:58:30 +0100 Subject: Documentation: reset: add some missing tables and while at it also explain why --merge option is disallowed in some cases. Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-reset.txt | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index dc73dca736..c137183574 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -79,6 +79,13 @@ git reset --option target to reset the HEAD to another commit (`target`) with the different reset options depending on the state of the files. +In these tables, A, B, C and D are some different states of a +file. For example, the first line of the first table means that if a +file is in state A in the working tree, in state B in the index, in +state C in HEAD and in state D in the target, then "git reset --soft +target" will put the file in state A in the working tree, in state B +in the index and in state D in HEAD. + working index HEAD target working index HEAD ---------------------------------------------------- A B C D --soft A B D @@ -107,12 +114,28 @@ reset options depending on the state of the files. --hard C C C --merge C C C -In these tables, A, B, C and D are some different states of a -file. For example, the last line of the last table means that if a -file is in state B in the working tree and the index, and in a -different state C in HEAD and in the target, then "git reset ---merge target" will put the file in state C in the working tree, -in the index and in HEAD. + working index HEAD target working index HEAD + ---------------------------------------------------- + B C C D --soft B C D + --mixed B D D + --hard D D D + --merge (disallowed) + + working index HEAD target working index HEAD + ---------------------------------------------------- + B C C C --soft B C C + --mixed B C C + --hard C C C + --merge 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 +involved in the merge does not have local change wrt the index before +it starts, and that it writes the result out to the work tree. So if +we see some difference between the index and the target and also +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. The following tables show what happens when there are unmerged entries: -- cgit v1.2.3