Documentation/technical/api-merge.txt

   1 merge API
   2 =========
   3
   4 The merge API helps a program to reconcile two competing sets of
   5 improvements to some files (e.g., unregistered changes from the work
   6 tree versus changes involved in switching to a new branch), reporting
   7 conflicts if found.  The library called through this API is
   8 responsible for a few things.
   9
  10  * determining which trees to merge (recursive ancestor consolidation);
  11
  12  * lining up corresponding files in the trees to be merged (rename
  13    detection, subtree shifting), reporting edge cases like add/add
  14    and rename/rename conflicts to the user;
  15
  16  * performing a three-way merge of corresponding files, taking
  17    path-specific merge drivers (specified in `.gitattributes`)
  18    into account.
  19
  20 Low-level (single file) merge
  21 -----------------------------
  22
  23 `ll_merge`::
  24
  25         Perform a three-way single-file merge in core.  This is
  26         a thin wrapper around `xdl_merge` that takes the path and
  27         any merge backend specified in `.gitattributes` or
  28         `.git/info/attributes` into account.  Returns 0 for a
  29         clean merge.
  30
  31 The caller:
  32
  33 1. allocates an mmbuffer_t variable for the result;
  34 2. allocates and fills variables with the file's original content
  35    and two modified versions (using `read_mmfile`, for example);
  36 3. calls ll_merge();
  37 4. reads the output from result_buf.ptr and result_buf.size;
  38 5. releases buffers when finished (free(ancestor.ptr); free(ours.ptr);
  39    free(theirs.ptr); free(result_buf.ptr);).
  40
  41 If the modifications do not merge cleanly, `ll_merge` will return a
  42 nonzero value and `result_buf` will generally include a description of
  43 the conflict bracketed by markers such as the traditional `<<<<<<<`
  44 and `>>>>>>>`.
  45
  46 The `ancestor_label`, `our_label`, and `their_label` parameters are
  47 used to label the different sides of a conflict if the merge driver
  48 supports this.
  49
  50 The `flag` parameter is a bitfield:
  51
  52  - The least significant bit indicates whether this is an internal
  53    merge to consolidate ancestors for a recursive merge.
  54
  55  - The next two bits allow local conflicts to be automatically
  56    resolved in favor of one side or the other (as in 'git merge-file'
  57    `--ours`/`--theirs`/`--union` for 01, 10, and 11, respectively).
  58
  59 Everything else
  60 ---------------
  61
  62 Talk about <merge-recursive.h> and merge_file():
  63
  64  - merge_trees() to merge with rename detection
  65  - merge_recursive() for ancestor consolidation
  66  - try_merge_command() for other strategies
  67  - conflict format
  68  - merge options
  69
  70 (Daniel, Miklos, Stephan, JC)