merge: move doc to ll-merge.h
Move the related documentation from Documentation/technical/api-merge.txt to ll-merge.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Only the ll-merge related doc is removed from documentation/technical/api-merge.txt because this information will be redundant and it'll be hard to keep it up to date and synchronized with the documentation in ll-merge.h. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
d3d7172e4002a360b8a463363968593cfb261dbe
2 files changed
+74
-71
Documentation/technical/api-merge.txt
+2
-70
@@ -28,77 +28,9 @@ and `diff.c` for examples.
28
29
* `struct ll_merge_options`
30
31
-This describes the set of options the calling program wants to affect
32
-the operation of a low-level (single file) merge. Some options:
33
-
34
-`virtual_ancestor`::
35
- Behave as though this were part of a merge between common
36
- ancestors in a recursive merge.
37
- If a helper program is specified by the
38
- `[merge "<driver>"] recursive` configuration, it will
39
- be used (see linkgit:gitattributes[5]).
40
-
41
-`variant`::
42
- Resolve local conflicts automatically in favor
43
- of one side or the other (as in 'git merge-file'
44
- `--ours`/`--theirs`/`--union`). Can be `0`,
45
- `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or
46
- `XDL_MERGE_FAVOR_UNION`.
47
-
48
-`renormalize`::
49
- Resmudge and clean the "base", "theirs" and "ours" files
50
- before merging. Use this when the merge is likely to have
51
- overlapped with a change in smudge/clean or end-of-line
52
- normalization rules.
31
+Check ll-merge.h for details.
32
33
Low-level (single file) merge
34
-----------------------------
35
57
-`ll_merge`::
58
-
59
- Perform a three-way single-file merge in core. This is
60
- a thin wrapper around `xdl_merge` that takes the path and
61
- any merge backend specified in `.gitattributes` or
62
- `.git/info/attributes` into account. Returns 0 for a
63
- clean merge.
64
-
65
-Calling sequence:
66
-
67
-* Prepare a `struct ll_merge_options` to record options.
68
- If you have no special requests, skip this and pass `NULL`
69
- as the `opts` parameter to use the default options.
70
-
71
-* Allocate an mmbuffer_t variable for the result.
72
-
73
-* Allocate and fill variables with the file's original content
74
- and two modified versions (using `read_mmfile`, for example).
75
-
76
-* Call `ll_merge()`.
77
-
78
-* Read the merged content from `result_buf.ptr` and `result_buf.size`.
79
-
80
-* Release buffers when finished. A simple
81
- `free(ancestor.ptr); free(ours.ptr); free(theirs.ptr);
82
- free(result_buf.ptr);` will do.
83
-
84
-If the modifications do not merge cleanly, `ll_merge` will return a
85
-nonzero value and `result_buf` will generally include a description of
86
-the conflict bracketed by markers such as the traditional `<<<<<<<`
87
-and `>>>>>>>`.
88
-
89
-The `ancestor_label`, `our_label`, and `their_label` parameters are
90
-used to label the different sides of a conflict if the merge driver
91
-supports this.
92
-
93
-Everything else
94
----------------
95
-
96
-Talk about <merge-recursive.h> and merge_file():
97
-
98
- - merge_trees() to merge with rename detection
99
- - merge_recursive() for ancestor consolidation
100
- - try_merge_command() for other strategies
101
- - conflict format
102
- - merge options
103
-
104
-(Daniel, Miklos, Stephan, JC)
36
+Check ll-merge.h for details.
ll-merge.h
+72
-1
@@ -7,16 +7,87 @@
7
8
#include "xdiff/xdiff.h"
9
10
+/**
11
+ *
12
+ * Calling sequence:
13
+ * ----------------
14
+ *
15
+ * - Prepare a `struct ll_merge_options` to record options.
16
+ * If you have no special requests, skip this and pass `NULL`
17
+ * as the `opts` parameter to use the default options.
18
+ *
19
+ * - Allocate an mmbuffer_t variable for the result.
20
+ *
21
+ * - Allocate and fill variables with the file's original content
22
+ * and two modified versions (using `read_mmfile`, for example).
23
+ *
24
+ * - Call `ll_merge()`.
25
+ *
26
+ * - Read the merged content from `result_buf.ptr` and `result_buf.size`.
27
+ *
28
+ * - Release buffers when finished. A simple
29
+ * `free(ancestor.ptr); free(ours.ptr); free(theirs.ptr);
30
+ * free(result_buf.ptr);` will do.
31
+ *
32
+ * If the modifications do not merge cleanly, `ll_merge` will return a
33
+ * nonzero value and `result_buf` will generally include a description of
34
+ * the conflict bracketed by markers such as the traditional `<<<<<<<`
35
+ * and `>>>>>>>`.
36
+ *
37
+ * The `ancestor_label`, `our_label`, and `their_label` parameters are
38
+ * used to label the different sides of a conflict if the merge driver
39
+ * supports this.
40
+ */
41
+
42
+
43
struct index_state;
44
45
+/**
46
+ * This describes the set of options the calling program wants to affect
47
+ * the operation of a low-level (single file) merge.
48
+ */
49
struct ll_merge_options {
50
+
51
+ /**
52
+ * Behave as though this were part of a merge between common ancestors in
53
+ * a recursive merge (merges of binary files may need to be handled
54
+ * differently in such cases, for example). If a helper program is
55
+ * specified by the `[merge "<driver>"] recursive` configuration, it will
56
+ * be used.
57
+ */
58
unsigned virtual_ancestor : 1;
14
- unsigned variant : 2; /* favor ours, favor theirs, or union merge */
59
+
60
+ /**
61
+ * Resolve local conflicts automatically in favor of one side or the other
62
+ * (as in 'git merge-file' `--ours`/`--theirs`/`--union`). Can be `0`,
63
+ * `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`,
64
+ * or `XDL_MERGE_FAVOR_UNION`.
65
+ */
66
+ unsigned variant : 2;
67
+
68
+ /**
69
+ * Resmudge and clean the "base", "theirs" and "ours" files before merging.
70
+ * Use this when the merge is likely to have overlapped with a change in
71
+ * smudge/clean or end-of-line normalization rules.
72
+ */
73
unsigned renormalize : 1;
74
+
75
+ /**
76
+ * Increase the length of conflict markers so that nested conflicts
77
+ * can be differentiated.
78
+ */
79
unsigned extra_marker_size;
80
+
81
+ /* Extra xpparam_t flags as defined in xdiff/xdiff.h. */
82
long xdl_opts;
83
};
84
85
+/**
86
+ * Perform a three-way single-file merge in core. This is a thin wrapper
87
+ * around `xdl_merge` that takes the path and any merge backend specified in
88
+ * `.gitattributes` or `.git/info/attributes` into account.
89
+ * Returns 0 for a clean merge.
90
+ */
91
int ll_merge(mmbuffer_t *result_buf,
92
const char *path,
93
mmfile_t *ancestor, const char *ancestor_label,