treewide: correct several "up-to-date" to "up to date"
[git/git.git] / Documentation / technical / trivial-merge.txt
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 Entries marked '+' have stat information. Spaces marked '*' don't
14 affect the result.
15
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
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
35 and not up to date.
36
37 Entries marked '+' have stat information. Spaces marked '*' don't
38 affect the result.
39
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
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
68 up to date.
69
70 *empty* means that the tree must not have a directory-file conflict
71 with the entry.
72
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.
76
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
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
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.