@matheusbsbs / matheus-bagliano / commits / 3d89cb4f3f
Fork 0

[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