Code

Merge branch 'nd/maint-relative' into maint
[git.git] / Documentation / technical / api-merge.txt
1 merge API
2 =========
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.
10  * determining which trees to merge (recursive ancestor consolidation);
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;
16  * performing a three-way merge of corresponding files, taking
17    path-specific merge drivers (specified in `.gitattributes`)
18    into account.
20 Low-level (single file) merge
21 -----------------------------
23 `ll_merge`::
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.
31 The caller:
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);).
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 `>>>>>>>`.
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.
50 The `flag` parameter is a bitfield:
52  - The `LL_OPT_VIRTUAL_ANCESTOR` bit indicates whether this is an
53    internal merge to consolidate ancestors for a recursive merge.
55  - The `LL_OPT_FAVOR_MASK` 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`).
58    They can be populated by `create_ll_flag`, whose argument can be
59    `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or
60    `XDL_MERGE_FAVOR_UNION`.
62 Everything else
63 ---------------
65 Talk about <merge-recursive.h> and merge_file():
67  - merge_trees() to merge with rename detection
68  - merge_recursive() for ancestor consolidation
69  - try_merge_command() for other strategies
70  - conflict format
71  - merge options
73 (Daniel, Miklos, Stephan, JC)