Documentation / technical / trivial-merge.txton commit Merge branch 'jc/maint-split-diff-metainfo' (bdf6442)
   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
  77case  ancest    head    remote    result
  78----------------------------------------
  791     (empty)+  (empty) (empty)   (empty)
  802ALT  (empty)+  *empty* remote    remote
  812     (empty)^  (empty) remote    no merge
  823ALT  (empty)+  head    *empty*   head
  833     (empty)^  head    (empty)   no merge
  844     (empty)^  head    remote    no merge
  855ALT  *         head    head      head
  866     ancest+   (empty) (empty)   no merge
  878     ancest^   (empty) ancest    no merge
  887     ancest+   (empty) remote    no merge
  8910    ancest^   ancest  (empty)   no merge
  909     ancest+   head    (empty)   no merge
  9116    anc1/anc2 anc1    anc2      no merge
  9213    ancest+   head    ancest    head
  9314    ancest+   ancest  remote    remote
  9411    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.