Documentation/technical: document ll_merge
Cc: Junio C Hamano <gitster@pobox.com> Cc: Avery Pennarun <apenwarr@gmail.com> Cc: Bert Wesarg <bert.wesarg@googlemail.com> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
Aug 5, 2010 at 06:16 UTC
24d113ec11d9948cedee4ba4687d0775e36b65f9
1 file changed
+70
Documentation/technical/api-merge.txt
new
+70
@@ -0,0 +1,70 @@
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)