/ uis / git / x / uis / git / git.git / blame
| Commit | Line | Data |
|---|---|---|
| 24d113ec JN |
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) |