[PATCH] Document the trivial merge rules for 3(+more ancestors)-way merges.
Signed-off-by: Daniel Barkalow Signed-off-by: Junio C Hamano <junkio@cox.net>
Daniel Barkalow committed
Sep 5, 2005 at 02:05 UTC
3d89cb4f3f5333d5eb5899352566ad071dbd0d0c
1 file changed
+92
Documentation/technical/trivial-merge.txt
new
+92
@@ -0,0 +1,92 @@
1
+Trivial merge rules
2
+===================
3
+
4
+This document describes the outcomes of the trivial merge logic in read-tree.
5
+
6
+One-way merge
7
+-------------
8
+
9
+This replaces the index with a different tree, keeping the stat info
10
+for entries that don't change, and allowing -u to make the minimum
11
+required changes to the working tree to have it match.
12
+
13
+ index tree result
14
+ -----------------------
15
+ * (empty) (empty)
16
+ (empty) tree tree
17
+ index+ tree tree
18
+ index+ index index+
19
+
20
+Two-way merge
21
+-------------
22
+
23
+
24
+
25
+Three-way merge
26
+---------------
27
+
28
+It is permitted for the index to lack an entry; this does not prevent
29
+any case from applying.
30
+
31
+If the index exists, it is an error for it not to match either the
32
+head or (if the merge is trivial) the result.
33
+
34
+If multiple cases apply, the one used is listed first.
35
+
36
+A result of "no merge" means that index is left in stage 0, ancest in
37
+stage 1, head in stage 2, and remote in stage 3 (if any of these are
38
+empty, no entry is left for that stage). Otherwise, the given entry is
39
+left in stage 0, and there are no other entries.
40
+
41
+A result of "no merge" is an error if the index is not empty and not
42
+up-to-date.
43
+
44
+*empty* means that the tree must not have a directory-file conflict
45
+ with the entry.
46
+
47
+For multiple ancestors or remotes, a '+' means that this case applies
48
+even if only one ancestor or remote fits; normally, all of the
49
+ancestors or remotes must be the same.
50
+
51
+case ancest head remote result
52
+----------------------------------------
53
+1 (empty)+ (empty) (empty) (empty)
54
+2ALT (empty)+ *empty* remote remote
55
+2ALT (empty)+ *empty* remote remote
56
+2 (empty)^ (empty) remote no merge
57
+3ALT (empty)+ head *empty* head
58
+3 (empty)^ head (empty) no merge
59
+4 (empty)^ head remote no merge
60
+5ALT * head head head
61
+6 ancest^ (empty) (empty) no merge
62
+8ALT ancest (empty) ancest (empty)
63
+7 ancest+ (empty) remote no merge
64
+9 ancest+ head (empty) no merge
65
+10ALT ancest ancest (empty) (empty)
66
+11 ancest+ head remote no merge
67
+16 anc1/anc2 anc1 anc2 no merge
68
+13 ancest+ head ancest head
69
+14 ancest+ ancest remote remote
70
+14ALT ancest+ ancest remote remote
71
+
72
+Only #2ALT and #3ALT use *empty*, because these are the only cases
73
+where there can be conflicts that didn't exist before. Note that we
74
+allow directory-file conflicts between things in different stages
75
+after the trivial merge.
76
+
77
+A possible alternative for #6 is (empty), which would make it like
78
+#1. This is not used, due to the likelihood that it arises due to
79
+moving the file to multiple different locations or moving and deleting
80
+it in different branches.
81
+
82
+Case #1 is included for completeness, and also in case we decide to
83
+put on '+' markings; any path that is never mentioned at all isn't
84
+handled.
85
+
86
+Note that #16 is when both #13 and #14 apply; in this case, we refuse
87
+the trivial merge, because we can't tell from this data which is
88
+right. This is a case of a reverted patch (in some direction, maybe
89
+multiple times), and the right answer depends on looking at crossings
90
+of history or common ancestors of the ancestors.
91
+
92
+The status as of Sep 5 is that multiple remotes are not supported
\ No newline at end of file