[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 b3a9915845171d1b1afb7d1aa95cfc8d5e18dfe7..24c84100b0790be22330464e01ea876e5d30fc9a 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.
 
 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)
    index   tree    result
    -----------------------
    *       (empty) (empty)


@@ -20,7 +23,30 @@ required changes to the working tree to have it match.
 Two-way merge
 -------------
 
 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
 ---------------
 
 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.
 
 *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
 
 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
 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
 7     ancest+   (empty) remote    no merge

+10    ancest^   ancest  (empty)   no merge

 9     ancest+   head    (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
 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
 
 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.
 
 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.