[PATCH] Finish documenting trivial merge rules

Fix missing symbol explanations, a few incorrect cases, and add
two-way merge rules.

Signed-off-by: Daniel Barkalow <barkalow@iabervon.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>

diff --git a/Documentation/technical/trivial-merge.txt b/Documentation/technical/trivial-merge.txt
index b3a9915..24c8410 100644 (file)
--- a/Documentation/technical/trivial-merge.txt
+++ b/Documentation/technical/trivial-merge.txt
@@ -10,6 +10,9 @@ This replaces the index with a different tree, keeping the stat info
 for entries that don't change, and allowing -u to make the minimum
 required changes to the working tree to have it match.
 
+Entries marked '+' have stat information. Spaces marked '*' don't
+affect the result.
+
    index   tree    result
    -----------------------
    *       (empty) (empty)
@@ -20,7 +23,30 @@ required changes to the working tree to have it match.
 Two-way merge
 -------------
 
+It is permitted for the index to lack an entry; this does not prevent
+any case from applying.
+
+If the index exists, it is an error for it not to match either the old
+or the result.
+
+If multiple cases apply, the one used is listed first.
+
+A result which changes the index is an error if the index is not empty
+and not up-to-date.
+
+Entries marked '+' have stat information. Spaces marked '*' don't
+affect the result.
 
+ case  index   old     new     result
+ -------------------------------------
+ 0/2   (empty) *       (empty) (empty)
+ 1/3   (empty) *       new     new
+ 4/5   index+  (empty) (empty) index+
+ 6/7   index+  (empty) index   index+
+ 10    index+  index   (empty) (empty)
+ 14/15 index+  old     old     index+
+ 18/19 index+  old     index   index+
+ 20    index+  index   new     new
 
 Three-way merge
 ---------------
@@ -44,30 +70,28 @@ up-to-date.
 *empty* means that the tree must not have a directory-file conflict
  with the entry.
 
-For multiple ancestors or remotes, a '+' means that this case applies
-even if only one ancestor or remote fits; normally, all of the
-ancestors or remotes must be the same.
+For multiple ancestors, a '+' means that this case applies even if
+only one ancestor or remote fits; a '^' means all of the ancestors
+must be the same.
 
 case  ancest    head    remote    result
 ----------------------------------------
 1     (empty)+  (empty) (empty)   (empty)
 2ALT  (empty)+  *empty* remote    remote
-2ALT  (empty)+  *empty* remote    remote
 2     (empty)^  (empty) remote    no merge
 3ALT  (empty)+  head    *empty*   head
 3     (empty)^  head    (empty)   no merge
 4     (empty)^  head    remote    no merge
 5ALT  *         head    head      head
-6     ancest^   (empty) (empty)   no merge
-8ALT  ancest    (empty) ancest    (empty)
+6     ancest+   (empty) (empty)   no merge
+8     ancest^   (empty) ancest    no merge
 7     ancest+   (empty) remote    no merge
+10    ancest^   ancest  (empty)   no merge
 9     ancest+   head    (empty)   no merge
-10ALT ancest    ancest  (empty)   (empty)
-11    ancest+   head    remote    no merge
 16    anc1/anc2 anc1    anc2      no merge
 13    ancest+   head    ancest    head
 14    ancest+   ancest  remote    remote
-14ALT ancest+   ancest  remote    remote
+11    ancest+   head    remote    no merge
 
 Only #2ALT and #3ALT use *empty*, because these are the only cases
 where there can be conflicts that didn't exist before. Note that we
@@ -89,4 +113,9 @@ right. This is a case of a reverted patch (in some direction, maybe
 multiple times), and the right answer depends on looking at crossings
 of history or common ancestors of the ancestors.
 
-The status as of Sep 5 is that multiple remotes are not supported
\ No newline at end of file
+Note that, between #6, #7, #9, and #11, all cases not otherwise
+covered are handled in this table.
+
+For #8 and #10, there is alternative behavior, not currently
+implemented, where the result is (empty). As currently implemented,
+the automatic merge will generally give this effect.