From 24d113ec11d9948cedee4ba4687d0775e36b65f9 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 5 Aug 2010 06:16:51 -0500 Subject: Documentation/technical: document ll_merge Cc: Junio C Hamano Cc: Avery Pennarun Cc: Bert Wesarg Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/technical/api-merge.txt | 70 +++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 Documentation/technical/api-merge.txt (limited to 'Documentation/technical') diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt new file mode 100644 index 000000000..01a89d6d0 --- /dev/null +++ b/Documentation/technical/api-merge.txt @@ -0,0 +1,70 @@ +merge API +========= + +The merge API helps a program to reconcile two competing sets of +improvements to some files (e.g., unregistered changes from the work +tree versus changes involved in switching to a new branch), reporting +conflicts if found. The library called through this API is +responsible for a few things. + + * determining which trees to merge (recursive ancestor consolidation); + + * lining up corresponding files in the trees to be merged (rename + detection, subtree shifting), reporting edge cases like add/add + and rename/rename conflicts to the user; + + * performing a three-way merge of corresponding files, taking + path-specific merge drivers (specified in `.gitattributes`) + into account. + +Low-level (single file) merge +----------------------------- + +`ll_merge`:: + + Perform a three-way single-file merge in core. This is + a thin wrapper around `xdl_merge` that takes the path and + any merge backend specified in `.gitattributes` or + `.git/info/attributes` into account. Returns 0 for a + clean merge. + +The caller: + +1. allocates an mmbuffer_t variable for the result; +2. allocates and fills variables with the file's original content + and two modified versions (using `read_mmfile`, for example); +3. calls ll_merge(); +4. reads the output from result_buf.ptr and result_buf.size; +5. releases buffers when finished (free(ancestor.ptr); free(ours.ptr); + free(theirs.ptr); free(result_buf.ptr);). + +If the modifications do not merge cleanly, `ll_merge` will return a +nonzero value and `result_buf` will generally include a description of +the conflict bracketed by markers such as the traditional `<<<<<<<` +and `>>>>>>>`. + +The `ancestor_label`, `our_label`, and `their_label` parameters are +used to label the different sides of a conflict if the merge driver +supports this. + +The `flag` parameter is a bitfield: + + - The least significant bit indicates whether this is an internal + merge to consolidate ancestors for a recursive merge. + + - The next two bits allow local conflicts to be automatically + resolved in favor of one side or the other (as in 'git merge-file' + `--ours`/`--theirs`/`--union` for 01, 10, and 11, respectively). + +Everything else +--------------- + +Talk about and merge_file(): + + - merge_trees() to merge with rename detection + - merge_recursive() for ancestor consolidation + - try_merge_command() for other strategies + - conflict format + - merge options + +(Daniel, Miklos, Stephan, JC) -- cgit v1.2.1 From 73cf7f713da4fc797e2393a9e490ad4ec9466c53 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 5 Aug 2010 06:17:38 -0500 Subject: ll-merge: make flag easier to populate ll_merge() takes its options in a flag word, which has a few advantages: - options flags can be cheaply passed around in registers, while an option struct passed by pointer cannot; - callers can easily pass 0 without trouble for no options, while an option struct passed by value would not allow that. The downside is that code to populate and access the flag word can be somewhat opaque. Mitigate that with a few macros. Cc: Avery Pennarun Cc: Bert Wesarg Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/technical/api-merge.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'Documentation/technical') diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index 01a89d6d0..a7e050bb7 100644 --- a/Documentation/technical/api-merge.txt +++ b/Documentation/technical/api-merge.txt @@ -49,12 +49,15 @@ supports this. The `flag` parameter is a bitfield: - - The least significant bit indicates whether this is an internal - merge to consolidate ancestors for a recursive merge. + - The `LL_OPT_VIRTUAL_ANCESTOR` bit indicates whether this is an + internal merge to consolidate ancestors for a recursive merge. - - The next two bits allow local conflicts to be automatically + - The `LL_OPT_FAVOR_MASK` bits allow local conflicts to be automatically resolved in favor of one side or the other (as in 'git merge-file' - `--ours`/`--theirs`/`--union` for 01, 10, and 11, respectively). + `--ours`/`--theirs`/`--union`). + They can be populated by `create_ll_flag`, whose argument can be + `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or + `XDL_MERGE_FAVOR_UNION`. Everything else --------------- -- cgit v1.2.1