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    index   tree    result
  14    -----------------------
  15    *       (empty) (empty)
  16    (empty) tree    tree
  17    index+  tree    tree
  18    index+  index   index+
  19
  20 Two-way merge
  21 -------------
  22
  23
  24
  25 Three-way merge
  26 ---------------
  27
  28 It is permitted for the index to lack an entry; this does not prevent
  29 any case from applying.
  30
  31 If the index exists, it is an error for it not to match either the
  32 head or (if the merge is trivial) the result.
  33
  34 If multiple cases apply, the one used is listed first.
  35
  36 A result of "no merge" means that index is left in stage 0, ancest in
  37 stage 1, head in stage 2, and remote in stage 3 (if any of these are
  38 empty, no entry is left for that stage). Otherwise, the given entry is
  39 left in stage 0, and there are no other entries.
  40
  41 A result of "no merge" is an error if the index is not empty and not
  42 up-to-date.
  43
  44 *empty* means that the tree must not have a directory-file conflict
  45  with the entry.
  46
  47 For multiple ancestors or remotes, a '+' means that this case applies
  48 even if only one ancestor or remote fits; normally, all of the
  49 ancestors or remotes must be the same.
  50
  51 case  ancest    head    remote    result
  52 ----------------------------------------
  53 1     (empty)+  (empty) (empty)   (empty)
  54 2ALT  (empty)+  *empty* remote    remote
  55 2ALT  (empty)+  *empty* remote    remote
  56 2     (empty)^  (empty) remote    no merge
  57 3ALT  (empty)+  head    *empty*   head
  58 3     (empty)^  head    (empty)   no merge
  59 4     (empty)^  head    remote    no merge
  60 5ALT  *         head    head      head
  61 6     ancest^   (empty) (empty)   no merge
  62 8ALT  ancest    (empty) ancest    (empty)
  63 7     ancest+   (empty) remote    no merge
  64 9     ancest+   head    (empty)   no merge
  65 10ALT ancest    ancest  (empty)   (empty)
  66 11    ancest+   head    remote    no merge
  67 16    anc1/anc2 anc1    anc2      no merge
  68 13    ancest+   head    ancest    head
  69 14    ancest+   ancest  remote    remote
  70 14ALT ancest+   ancest  remote    remote
  71
  72 Only #2ALT and #3ALT use *empty*, because these are the only cases
  73 where there can be conflicts that didn't exist before. Note that we
  74 allow directory-file conflicts between things in different stages
  75 after the trivial merge.
  76
  77 A possible alternative for #6 is (empty), which would make it like
  78 #1. This is not used, due to the likelihood that it arises due to
  79 moving the file to multiple different locations or moving and deleting
  80 it in different branches.
  81
  82 Case #1 is included for completeness, and also in case we decide to
  83 put on '+' markings; any path that is never mentioned at all isn't
  84 handled.
  85
  86 Note that #16 is when both #13 and #14 apply; in this case, we refuse
  87 the trivial merge, because we can't tell from this data which is
  88 right. This is a case of a reverted patch (in some direction, maybe
  89 multiple times), and the right answer depends on looking at crossings
  90 of history or common ancestors of the ancestors.
  91
  92 The status as of Sep 5 is that multiple remotes are not supported