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 <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Christian Couder committed
Jan 5, 2010 at 06:58 UTC
397d596f84209d0e9d17621ce56b5432bc98d368
1 file changed
+29
-6
Documentation/git-reset.txt
+29
-6
@@ -79,6 +79,13 @@ git reset --option target
79
to reset the HEAD to another commit (`target`) with the different
80
reset options depending on the state of the files.
81
82
+In these tables, A, B, C and D are some different states of a
83
+file. For example, the first line of the first table means that if a
84
+file is in state A in the working tree, in state B in the index, in
85
+state C in HEAD and in state D in the target, then "git reset --soft
86
+target" will put the file in state A in the working tree, in state B
87
+in the index and in state D in HEAD.
88
+
89
working index HEAD target working index HEAD
90
----------------------------------------------------
91
A B C D --soft A B D
@@ -107,12 +114,28 @@ reset options depending on the state of the files.
114
--hard C C C
115
--merge C C C
116
110
-In these tables, A, B, C and D are some different states of a
111
-file. For example, the last line of the last table means that if a
112
-file is in state B in the working tree and the index, and in a
113
-different state C in HEAD and in the target, then "git reset
114
---merge target" will put the file in state C in the working tree,
115
-in the index and in HEAD.
117
+ working index HEAD target working index HEAD
118
+ ----------------------------------------------------
119
+ B C C D --soft B C D
120
+ --mixed B D D
121
+ --hard D D D
122
+ --merge (disallowed)
123
+
124
+ working index HEAD target working index HEAD
125
+ ----------------------------------------------------
126
+ B C C C --soft B C C
127
+ --mixed B C C
128
+ --hard C C C
129
+ --merge B C C
130
+
131
+"reset --merge" is meant to be used when resetting out of a conflicted
132
+merge. Any mergy operation guarantees that the work tree file that is
133
+involved in the merge does not have local change wrt the index before
134
+it starts, and that it writes the result out to the work tree. So if
135
+we see some difference between the index and the target and also
136
+between the index and the work tree, then it means that we are not
137
+resetting out from a state that a mergy operation left after failing
138
+with a conflict. That is why we disallow --merge option in this case.
139
140
The following tables show what happens when there are unmerged
141
entries: