ll-merge: make flag easier to populate
[git/git.git] / Documentation / technical / api-merge.txt
CommitLineData
24d113ec
JN
1merge API
2=========
3
4The merge API helps a program to reconcile two competing sets of
5improvements to some files (e.g., unregistered changes from the work
6tree versus changes involved in switching to a new branch), reporting
7conflicts if found. The library called through this API is
8responsible 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
20Low-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
31The caller:
32
331. allocates an mmbuffer_t variable for the result;
342. allocates and fills variables with the file's original content
35 and two modified versions (using `read_mmfile`, for example);
363. calls ll_merge();
374. reads the output from result_buf.ptr and result_buf.size;
385. releases buffers when finished (free(ancestor.ptr); free(ours.ptr);
39 free(theirs.ptr); free(result_buf.ptr);).
40
41If the modifications do not merge cleanly, `ll_merge` will return a
42nonzero value and `result_buf` will generally include a description of
43the conflict bracketed by markers such as the traditional `<<<<<<<`
44and `>>>>>>>`.
45
46The `ancestor_label`, `our_label`, and `their_label` parameters are
47used to label the different sides of a conflict if the merge driver
48supports this.
49
50The `flag` parameter is a bitfield:
51
73cf7f71
JN
52 - The `LL_OPT_VIRTUAL_ANCESTOR` bit indicates whether this is an
53 internal merge to consolidate ancestors for a recursive merge.
24d113ec 54
73cf7f71 55 - The `LL_OPT_FAVOR_MASK` bits allow local conflicts to be automatically
24d113ec 56 resolved in favor of one side or the other (as in 'git merge-file'
73cf7f71
JN
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`.
24d113ec
JN
61
62Everything else
63---------------
64
65Talk about <merge-recursive.h> and merge_file():
66
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
72
73(Daniel, Miklos, Stephan, JC)