1Trivial merge rules 2=================== 3 4This document describes the outcomes of the trivial merge logic in read-tree. 5 6One-way merge 7------------- 8 9This replaces the index with a different tree, keeping the stat info 10for entries that don't change, and allowing -u to make the minimum 11required changes to the working tree to have it match. 12 13Entries marked '+' have stat information. Spaces marked '*' don't 14affect the result. 15 16 index tree result 17 ----------------------- 18 * (empty) (empty) 19 (empty) tree tree 20 index+ tree tree 21 index+ index index+ 22 23Two-way merge 24------------- 25 26It is permitted for the index to lack an entry; this does not prevent 27any case from applying. 28 29If the index exists, it is an error for it not to match either the old 30or the result. 31 32If multiple cases apply, the one used is listed first. 33 34A result which changes the index is an error if the index is not empty 35and not up-to-date. 36 37Entries marked '+' have stat information. Spaces marked '*' don't 38affect 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 51Three-way merge 52--------------- 53 54It is permitted for the index to lack an entry; this does not prevent 55any case from applying. 56 57If the index exists, it is an error for it not to match either the 58head or (if the merge is trivial) the result. 59 60If multiple cases apply, the one used is listed first. 61 62A result of "no merge" means that index is left in stage 0, ancest in 63stage 1, head in stage 2, and remote in stage 3 (if any of these are 64empty, no entry is left for that stage). Otherwise, the given entry is 65left in stage 0, and there are no other entries. 66 67A result of "no merge" is an error if the index is not empty and not 68up-to-date. 69 70*empty* means that the tree must not have a directory-file conflict 71 with the entry. 72 73For multiple ancestors, a '+' means that this case applies even if 74only one ancestor or remote fits; a '^' means all of the ancestors 75must 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 96Only #2ALT and #3ALT use *empty*, because these are the only cases 97where there can be conflicts that didn't exist before. Note that we 98allow directory-file conflicts between things in different stages 99after the trivial merge. 100 101A 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 103moving the file to multiple different locations or moving and deleting 104it in different branches. 105 106Case #1 is included for completeness, and also in case we decide to 107put on '+' markings; any path that is never mentioned at all isn't 108handled. 109 110Note that #16 is when both #13 and #14 apply; in this case, we refuse 111the trivial merge, because we can't tell from this data which is 112right. This is a case of a reverted patch (in some direction, maybe 113multiple times), and the right answer depends on looking at crossings 114of history or common ancestors of the ancestors. 115 116Note that, between #6, #7, #9, and #11, all cases not otherwise 117covered are handled in this table. 118 119For #8 and #10, there is alternative behavior, not currently 120implemented, where the result is (empty). As currently implemented, 121the automatic merge will generally give this effect.