Google Git
Sign in
chromium / external / gitster / git-htmldocs / a74e4c319c25bbf547ffb840f4e84d8e709291c5 / . / technical / api-merge.html
blob: 4c3ec10cb1833cea0a1bf525000b5937dc4ac98a [file] [log] [blame]
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]6<meta name="generator" content="AsciiDoc 8.4.5" />
7<title>merge API</title>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]8<style type="text/css">
9/* Debug borders */
10p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11/*
12 border: 1px solid red;
13*/
14}
15
16body {
17 margin: 1em 5% 1em 5%;
18}
19
20a {
21 color: blue;
22 text-decoration: underline;
23}
24a:visited {
25 color: fuchsia;
26}
27
28em {
29 font-style: italic;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]30 color: navy;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]31}
32
33strong {
34 font-weight: bold;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]35 color: #083194;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]36}
37
38tt {
39 color: navy;
40}
41
42h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
48}
49
50h1, h2, h3 {
51 border-bottom: 2px solid silver;
52}
53h2 {
54 padding-top: 0.5em;
55}
56h3 {
57 float: left;
58}
59h3 + * {
60 clear: left;
61}
62
63div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
66}
67
68hr {
69 border: 1px solid silver;
70}
71
72p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
75}
76
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]77ul, ol, li > p {
78 margin-top: 0;
79}
80
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]81pre {
82 padding: 0;
83 margin: 0;
84}
85
86span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
90 font-size: 1.1em;
91}
92span#email {
93}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]94span#revnumber, span#revdate, span#revremark {
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]95 font-family: sans-serif;
96}
97
98div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
104}
105div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
108}
109div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
112}
113
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]114div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
117}
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]118div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120div.admonitionblock {
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
123}
124div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
127}
128
129div.content { /* Block element content. */
130 padding: 0;
131}
132
133/* Block element titles. */
134div.title, caption.title {
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]135 color: #527bbd;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
141}
142div.title + * {
143 margin-top: 0;
144}
145
146td div.title:first-child {
147 margin-top: 0.0em;
148}
149div.content div.title:first-child {
150 margin-top: 0.0em;
151}
152div.content + div.title {
153 margin-top: 0.0em;
154}
155
156div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
160}
161
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]162div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
166}
167
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]168div.quoteblock {
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]169 padding-left: 2.0em;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]170 margin-right: 10%;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]171}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]172div.quoteblock > div.attribution {
173 padding-top: 0.5em;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]174 text-align: right;
175}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]176
177div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
180}
181div.verseblock > div.content {
182 white-space: pre;
183}
184div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
187}
188/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]189div.verseblock + div.attribution {
190 text-align: left;
191}
192
193div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
200}
201div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
204}
205
206div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
209}
210
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]211div.imageblock div.content { padding-left: 0; }
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]212span.image img { border-style: none; }
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]213a.image:visited { color: white; }
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]214
215dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
218}
219dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]222 font-style: normal;
223 color: navy;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]224}
225dd > *:first-child {
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]226 margin-top: 0.1em;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]227}
228
229ul, ol {
230 list-style-position: outside;
231}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]232ol.arabic {
233 list-style-type: decimal;
234}
235ol.loweralpha {
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]236 list-style-type: lower-alpha;
237}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]238ol.upperalpha {
239 list-style-type: upper-alpha;
240}
241ol.lowerroman {
242 list-style-type: lower-roman;
243}
244ol.upperroman {
245 list-style-type: upper-roman;
246}
247
248div.compact ul, div.compact ol,
249div.compact p, div.compact p,
250div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
253}
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]254
255div.tableblock > table {
256 border: 3px solid #527bbd;
257}
258thead {
259 font-family: sans-serif;
260 font-weight: bold;
261}
262tfoot {
263 font-weight: bold;
264}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]265td > div.verse {
266 white-space: pre;
267}
268p.table {
269 margin-top: 0;
270}
271/* Because the table frame attribute is overriden by CSS in most browsers. */
272div.tableblock > table[frame="void"] {
273 border-style: none;
274}
275div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
278}
279div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
282}
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]283
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]284
285div.hdlist {
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
288}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]289div.hdlist tr {
290 padding-bottom: 15px;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]291}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]292dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
294}
295td.hdlist1 {
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]296 vertical-align: top;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]297 font-style: normal;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]298 padding-right: 0.8em;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]299 color: navy;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]300}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]301td.hdlist2 {
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]302 vertical-align: top;
303}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]304div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
307}
308
309.comment {
310 background: yellow;
311}
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]312
313@media print {
314 div#footer-badges { display: none; }
315}
316
317div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
324}
325
326div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
329}
330div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
333}
334div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
337}
338div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
341}
342/* Workarounds for IE6's broken and incomplete CSS2. */
343
344div.sidebar-content {
345 background: #ffffee;
346 border: 1px solid silver;
347 padding: 0.5em;
348}
349div.sidebar-title, div.image-title {
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]350 color: #527bbd;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]351 font-family: sans-serif;
352 font-weight: bold;
353 margin-top: 0.0em;
354 margin-bottom: 0.5em;
355}
356
357div.listingblock div.content {
358 border: 1px solid silver;
359 background: #f4f4f4;
360 padding: 0.5em;
361}
362
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]363div.quoteblock-attribution {
364 padding-top: 0.5em;
365 text-align: right;
366}
367
368div.verseblock-content {
369 white-space: pre;
370}
371div.verseblock-attribution {
372 padding-top: 0.75em;
373 text-align: left;
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]374}
375
376div.exampleblock-content {
377 border-left: 2px solid silver;
378 padding-left: 0.5em;
379}
380
381/* IE6 sets dynamically generated links as visited. */
382div#toc a:visited { color: blue; }
383</style>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]384</head>
385<body>
386<div id="header">
387<h1>merge API</h1>
388</div>
389<div id="preamble">
390<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]391<div class="paragraph"><p>The merge API helps a program to reconcile two competing sets of
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]392improvements to some files (e.g., unregistered changes from the work
393tree versus changes involved in switching to a new branch), reporting
394conflicts if found. The library called through this API is
395responsible for a few things.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]396<div class="ulist"><ul>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]397<li>
398<p>
399determining which trees to merge (recursive ancestor consolidation);
400</p>
401</li>
402<li>
403<p>
404lining up corresponding files in the trees to be merged (rename
405 detection, subtree shifting), reporting edge cases like add/add
406 and rename/rename conflicts to the user;
407</p>
408</li>
409<li>
410<p>
411performing a three-way merge of corresponding files, taking
412 path-specific merge drivers (specified in <tt>.gitattributes</tt>)
413 into account.
414</p>
415</li>
416</ul></div>
417</div>
418</div>
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]419<h2 id="_data_structures">Data structures</h2>
420<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]421<div class="ulist"><ul>
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]422<li>
423<p>
424<tt>mmbuffer_t</tt>, <tt>mmfile_t</tt>
425</p>
426</li>
427</ul></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]428<div class="paragraph"><p>These store data usable for use by the xdiff backend, for writing and
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]429for reading, respectively. See <tt>xdiff/xdiff.h</tt> for the definitions
430and <tt>diff.c</tt> for examples.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]431<div class="ulist"><ul>
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]432<li>
433<p>
434<tt>struct ll_merge_options</tt>
435</p>
436</li>
437</ul></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]438<div class="paragraph"><p>This describes the set of options the calling program wants to affect
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]439the operation of a low-level (single file) merge. Some options:</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]440<div class="dlist"><dl>
441<dt class="hdlist1">
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]442<tt>virtual_ancestor</tt>
443</dt>
444<dd>
445<p>
446 Behave as though this were part of a merge between common
447 ancestors in a recursive merge.
448 If a helper program is specified by the
449 <tt>[merge "&lt;driver&gt;"] recursive</tt> configuration, it will
450 be used (see <a href="gitattributes.html">gitattributes(5)</a>).
451</p>
452</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]453<dt class="hdlist1">
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]454<tt>variant</tt>
455</dt>
456<dd>
457<p>
458 Resolve local conflicts automatically in favor
459 of one side or the other (as in <em>git merge-file</em>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]460 <tt>--ours</tt>/<tt>--theirs</tt>/<tt>--union</tt>). Can be <tt>0</tt>,
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]461 <tt>XDL_MERGE_FAVOR_OURS</tt>, <tt>XDL_MERGE_FAVOR_THEIRS</tt>, or
462 <tt>XDL_MERGE_FAVOR_UNION</tt>.
463</p>
464</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]465<dt class="hdlist1">
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]466<tt>renormalize</tt>
467</dt>
468<dd>
469<p>
470 Resmudge and clean the "base", "theirs" and "ours" files
471 before merging. Use this when the merge is likely to have
472 overlapped with a change in smudge/clean or end-of-line
473 normalization rules.
474</p>
475</dd>
476</dl></div>
477</div>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]478<h2 id="_low_level_single_file_merge">Low-level (single file) merge</h2>
479<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]480<div class="dlist"><dl>
481<dt class="hdlist1">
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]482<tt>ll_merge</tt>
483</dt>
484<dd>
485<p>
486 Perform a three-way single-file merge in core. This is
487 a thin wrapper around <tt>xdl_merge</tt> that takes the path and
488 any merge backend specified in <tt>.gitattributes</tt> or
489 <tt>.git/info/attributes</tt> into account. Returns 0 for a
490 clean merge.
491</p>
492</dd>
493</dl></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]494<div class="paragraph"><p>Calling sequence:</p></div>
495<div class="ulist"><ul>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]496<li>
497<p>
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]498Prepare a <tt>struct ll_merge_options</tt> to record options.
499 If you have no special requests, skip this and pass <tt>NULL</tt>
500 as the <tt>opts</tt> parameter to use the default options.
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]501</p>
502</li>
503<li>
504<p>
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]505Allocate an mmbuffer_t variable for the result.
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]506</p>
507</li>
508<li>
509<p>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]510Allocate and fill variables with the file&#8217;s original content
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]511 and two modified versions (using <tt>read_mmfile</tt>, for example).
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]512</p>
513</li>
514<li>
515<p>
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]516Call <tt>ll_merge()</tt>.
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]517</p>
518</li>
519<li>
520<p>
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]521Read the merged content from <tt>result_buf.ptr</tt> and <tt>result_buf.size</tt>.
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]522</p>
523</li>
Junio C Hamano39c7a692010-10-27 06:08:54[diff] [blame]524<li>
525<p>
526Release buffers when finished. A simple
527 <tt>free(ancestor.ptr); free(ours.ptr); free(theirs.ptr);
528 free(result_buf.ptr);</tt> will do.
529</p>
530</li>
531</ul></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]532<div class="paragraph"><p>If the modifications do not merge cleanly, <tt>ll_merge</tt> will return a
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]533nonzero value and <tt>result_buf</tt> will generally include a description of
534the conflict bracketed by markers such as the traditional <tt>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</tt>
535and <tt>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</tt>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]536<div class="paragraph"><p>The <tt>ancestor_label</tt>, <tt>our_label</tt>, and <tt>their_label</tt> parameters are
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]537used to label the different sides of a conflict if the merge driver
538supports this.</p></div>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]539</div>
540<h2 id="_everything_else">Everything else</h2>
541<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]542<div class="paragraph"><p>Talk about &lt;merge-recursive.h&gt; and merge_file():</p></div>
543<div class="ulist"><ul>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]544<li>
545<p>
546merge_trees() to merge with rename detection
547</p>
548</li>
549<li>
550<p>
551merge_recursive() for ancestor consolidation
552</p>
553</li>
554<li>
555<p>
556try_merge_command() for other strategies
557</p>
558</li>
559<li>
560<p>
561conflict format
562</p>
563</li>
564<li>
565<p>
566merge options
567</p>
568</li>
569</ul></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]570<div class="paragraph"><p>(Daniel, Miklos, Stephan, JC)</p></div>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]571</div>
572<div id="footer">
573<div id="footer-text">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]574Last updated 2010-11-06 00:41:57 UTC
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]575</div>
576</div>
577</body>
578</html>