[PATCH] Documentation: reset: add some missing tables

From

Christian Couder <chriscool@tuxfamily.org>

Date

Jan 5, 2010, 05:58 UTC

Message-ID

<20100105055831.3539.26382.chriscool@tuxfamily.org>

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/git-reset.txt |   35 +++++++++++++++++++++++++++++------
 1 files changed, 29 insertions(+), 6 deletions(-)

      working index HEAD target         working index HEAD
      ----------------------------------------------------
       B       C     C    C     --merge   B       C     C

while in the other cases, when it is allowed, --merge is like --hard.

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index dc73dca..1f35278 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:

-- 
1.6.6.rc2.5.g49666