]>
Commit | Line | Data |
---|---|---|
3d89cb4f DB |
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 | ||
7061f5c2 DB |
13 | Entries marked '+' have stat information. Spaces marked '*' don't |
14 | affect the result. | |
15 | ||
3d89cb4f DB |
16 | index tree result |
17 | ----------------------- | |
18 | * (empty) (empty) | |
19 | (empty) tree tree | |
20 | index+ tree tree | |
21 | index+ index index+ | |
22 | ||
23 | Two-way merge | |
24 | ------------- | |
25 | ||
7061f5c2 DB |
26 | It is permitted for the index to lack an entry; this does not prevent |
27 | any case from applying. | |
28 | ||
29 | If the index exists, it is an error for it not to match either the old | |
30 | or the result. | |
31 | ||
32 | If multiple cases apply, the one used is listed first. | |
33 | ||
34 | A result which changes the index is an error if the index is not empty | |
7560f547 | 35 | and not up to date. |
7061f5c2 DB |
36 | |
37 | Entries marked '+' have stat information. Spaces marked '*' don't | |
38 | affect the result. | |
3d89cb4f | 39 | |
7061f5c2 DB |
40 | case index old new result |
41 | ------------------------------------- | |
42 | 0/2 (empty) * (empty) (empty) | |
43 | 1/3 (empty) * new new | |
44 | 4/5 index+ (empty) (empty) index+ | |
45 | 6/7 index+ (empty) index index+ | |
46 | 10 index+ index (empty) (empty) | |
47 | 14/15 index+ old old index+ | |
48 | 18/19 index+ old index index+ | |
49 | 20 index+ index new new | |
3d89cb4f DB |
50 | |
51 | Three-way merge | |
52 | --------------- | |
53 | ||
54 | It is permitted for the index to lack an entry; this does not prevent | |
55 | any case from applying. | |
56 | ||
57 | If the index exists, it is an error for it not to match either the | |
58 | head or (if the merge is trivial) the result. | |
59 | ||
60 | If multiple cases apply, the one used is listed first. | |
61 | ||
62 | A result of "no merge" means that index is left in stage 0, ancest in | |
63 | stage 1, head in stage 2, and remote in stage 3 (if any of these are | |
64 | empty, no entry is left for that stage). Otherwise, the given entry is | |
65 | left in stage 0, and there are no other entries. | |
66 | ||
67 | A result of "no merge" is an error if the index is not empty and not | |
7560f547 | 68 | up to date. |
3d89cb4f DB |
69 | |
70 | *empty* means that the tree must not have a directory-file conflict | |
71 | with the entry. | |
72 | ||
7061f5c2 DB |
73 | For multiple ancestors, a '+' means that this case applies even if |
74 | only one ancestor or remote fits; a '^' means all of the ancestors | |
75 | must be the same. | |
3d89cb4f | 76 | |
5316c8e9 TA |
77 | case ancest head remote result |
78 | ---------------------------------------- | |
79 | 1 (empty)+ (empty) (empty) (empty) | |
80 | 2ALT (empty)+ *empty* remote remote | |
81 | 2 (empty)^ (empty) remote no merge | |
82 | 3ALT (empty)+ head *empty* head | |
83 | 3 (empty)^ head (empty) no merge | |
84 | 4 (empty)^ head remote no merge | |
85 | 5ALT * head head head | |
86 | 6 ancest+ (empty) (empty) no merge | |
87 | 8 ancest^ (empty) ancest no merge | |
88 | 7 ancest+ (empty) remote no merge | |
89 | 10 ancest^ ancest (empty) no merge | |
90 | 9 ancest+ head (empty) no merge | |
91 | 16 anc1/anc2 anc1 anc2 no merge | |
92 | 13 ancest+ head ancest head | |
93 | 14 ancest+ ancest remote remote | |
94 | 11 ancest+ head remote no merge | |
3d89cb4f DB |
95 | |
96 | Only #2ALT and #3ALT use *empty*, because these are the only cases | |
97 | where there can be conflicts that didn't exist before. Note that we | |
98 | allow directory-file conflicts between things in different stages | |
99 | after the trivial merge. | |
100 | ||
101 | A possible alternative for #6 is (empty), which would make it like | |
102 | #1. This is not used, due to the likelihood that it arises due to | |
103 | moving the file to multiple different locations or moving and deleting | |
104 | it in different branches. | |
105 | ||
106 | Case #1 is included for completeness, and also in case we decide to | |
107 | put on '+' markings; any path that is never mentioned at all isn't | |
108 | handled. | |
109 | ||
110 | Note that #16 is when both #13 and #14 apply; in this case, we refuse | |
111 | the trivial merge, because we can't tell from this data which is | |
112 | right. This is a case of a reverted patch (in some direction, maybe | |
113 | multiple times), and the right answer depends on looking at crossings | |
114 | of history or common ancestors of the ancestors. | |
115 | ||
7061f5c2 DB |
116 | Note that, between #6, #7, #9, and #11, all cases not otherwise |
117 | covered are handled in this table. | |
118 | ||
119 | For #8 and #10, there is alternative behavior, not currently | |
120 | implemented, where the result is (empty). As currently implemented, | |
121 | the automatic merge will generally give this effect. |