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.