From: Jonathan Nieder <jrnieder@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: Eyvind Bernhardsen <eyvind.bernhardsen@gmail.com>,
Jakub Narebski <jnareb@gmail.com>,
Finn Arne Gangstad <finnag@pvv.org>,
"git@vger.kernel.org List" <git@vger.kernel.org>,
Avery Pennarun <apenwarr@gmail.com>,
Bert Wesarg <bert.wesarg@googlemail.com>
Subject: [PATCH 06/12] Documentation/technical: document ll_merge
Date: Thu, 5 Aug 2010 06:16:51 -0500 [thread overview]
Message-ID: <20100805111651.GH13779@burratino> (raw)
In-Reply-To: <20100805110822.GB13779@burratino>
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>
---
Sane?
Documentation/technical/api-merge.txt | 70 +++++++++++++++++++++++++++++++++
1 files changed, 70 insertions(+), 0 deletions(-)
create mode 100644 Documentation/technical/api-merge.txt
diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt
new file mode 100644
index 0000000..01a89d6
--- /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 <merge-recursive.h> 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)
--
1.7.2.1.544.ga752d.dirty
next prev parent reply other threads:[~2010-08-05 11:18 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-07-02 19:20 [PATCH v6 0/3] Merge renormalization, config renamed Eyvind Bernhardsen
2010-07-02 19:20 ` [PATCH v6 1/3] Avoid conflicts when merging branches with mixed normalization Eyvind Bernhardsen
2010-07-02 19:20 ` [PATCH v6 2/3] Try normalizing files to avoid delete/modify conflicts when merging Eyvind Bernhardsen
2010-07-02 19:20 ` [PATCH v6 3/3] Don't expand CRLFs when normalizing text during merge Eyvind Bernhardsen
2010-07-02 22:46 ` [PATCH v6 0/3] Merge renormalization, config renamed Junio C Hamano
2010-08-04 3:19 ` [PATCH/RFC eb/double-convert-before-merge 0/6] merge -Xrenormalize Jonathan Nieder
2010-08-04 3:20 ` [PATCH 1/6] merge-trees: push choice to renormalize away from low level Jonathan Nieder
2010-08-04 3:21 ` [PATCH 2/6] merge-trees: let caller decide whether to renormalize Jonathan Nieder
2010-08-04 3:21 ` [PATCH 3/6] ll-merge: " Jonathan Nieder
2010-08-04 18:12 ` Junio C Hamano
2010-08-04 3:22 ` [PATCH 4/6] rerere: migrate to parse-options API Jonathan Nieder
2010-08-04 3:23 ` [PATCH 5/6] rerere: let caller decide whether to renormalize Jonathan Nieder
2010-08-04 18:12 ` Junio C Hamano
2010-08-05 11:08 ` [PATCH/RFC v2 0/12] " Jonathan Nieder
2010-08-05 11:09 ` [PATCH 01/12] t6038 (merge.renormalize): style nitpicks Jonathan Nieder
2010-08-05 11:41 ` Ævar Arnfjörð Bjarmason
2010-08-05 11:54 ` Jonathan Nieder
2010-08-05 11:11 ` [PATCH 02/12] t6038 (merge.renormalize): try checkout -m and cherry-pick Jonathan Nieder
2010-08-05 11:13 ` [PATCH 03/12] t6038 (merge.renormalize): check that it can be turned off Jonathan Nieder
2010-08-05 11:13 ` [PATCH 04/12] merge-trees: push choice to renormalize away from low level Jonathan Nieder
2010-08-05 11:15 ` [PATCH 05/12] merge-trees: let caller decide whether to renormalize Jonathan Nieder
2010-08-05 11:16 ` Jonathan Nieder [this message]
2010-08-05 11:17 ` [PATCH 07/12] ll-merge: make flag easier to populate Jonathan Nieder
2010-08-05 12:12 ` Bert Wesarg
2010-08-05 12:16 ` Jonathan Nieder
2010-08-05 13:05 ` Bert Wesarg
2010-08-05 13:11 ` Jonathan Nieder
2010-08-05 11:24 ` [PATCH 08/12] ll-merge: let caller decide whether to renormalize Jonathan Nieder
2010-08-05 11:25 ` [PATCH 09/12] t4200 (rerere): modernize style Jonathan Nieder
2010-08-05 11:28 ` [PATCH 10/12] rerere: migrate to parse-options API Jonathan Nieder
2010-08-05 11:30 ` [PATCH 11/12] rerere: never renormalize Jonathan Nieder
2010-08-05 11:32 ` [PATCH 12/12] merge-recursive --renormalize Jonathan Nieder
2010-08-05 19:02 ` [PATCH/RFC v2 0/12] Re: rerere: let caller decide whether to renormalize Eyvind Bernhardsen
2010-08-04 3:29 ` [PATCH 6/6] merge-recursive: add -Xrenormalize option Jonathan Nieder
2010-08-04 18:10 ` [PATCH/RFC eb/double-convert-before-merge 0/6] merge -Xrenormalize Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20100805111651.GH13779@burratino \
--to=jrnieder@gmail.com \
--cc=apenwarr@gmail.com \
--cc=bert.wesarg@googlemail.com \
--cc=eyvind.bernhardsen@gmail.com \
--cc=finnag@pvv.org \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jnareb@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).