/usr/share/doc/diffutils-doc/diff3-Merging.html is in diffutils-doc 1:3.5-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for GNU Diffutils
(version 3.5, 4 August 2016),
and documents the GNU diff, diff3,
sdiff, and cmp commands for showing the
differences between files and the GNU patch command for
using their output to update files.
Copyright (C) 1992-1994, 1998, 2001-2002, 2004, 2006, 2009-2016 Free
Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled
"GNU Free Documentation License." -->
<!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Comparing and Merging Files: diff3 Merging</title>
<meta name="description" content="Comparing and Merging Files: diff3 Merging">
<meta name="keywords" content="Comparing and Merging Files: diff3 Merging">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index.html#Index" rel="index" title="Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="Interactive-Merging.html#Interactive-Merging" rel="next" title="Interactive Merging">
<link href="Comparing-Three-Files.html#diff3-Hunks" rel="prev" title="diff3 Hunks">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="diff3-Merging"></a>
<div class="header">
<p>
Next: <a href="Interactive-Merging.html#Interactive-Merging" accesskey="n" rel="next">Interactive Merging</a>, Previous: <a href="Comparing-Three-Files.html#Comparing-Three-Files" accesskey="p" rel="prev">Comparing Three Files</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Merging-From-a-Common-Ancestor"></a>
<h2 class="chapter">8 Merging From a Common Ancestor</h2>
<a name="index-merging-from-a-common-ancestor"></a>
<p>When two people have made changes to copies of the same file,
<code>diff3</code> can produce a merged output that contains both sets of
changes together with warnings about conflicts.
</p>
<p>One might imagine programs with names like <code>diff4</code> and <code>diff5</code>
to compare more than three files simultaneously, but in practice the
need rarely arises. You can use <code>diff3</code> to merge three or more
sets of changes to a file by merging two change sets at a time.
</p>
<p><code>diff3</code> can incorporate changes from two modified versions into a
common preceding version. This lets you merge the sets of changes
represented by the two newer files. Specify the common ancestor version
as the second argument and the two newer versions as the first and third
arguments, like this:
</p>
<div class="example">
<pre class="example">diff3 <var>mine</var> <var>older</var> <var>yours</var>
</pre></div>
<p>You can remember the order of the arguments by noting that they are in
alphabetical order.
</p>
<a name="index-conflict"></a>
<a name="index-overlap"></a>
<p>You can think of this as subtracting <var>older</var> from <var>yours</var> and
adding the result to <var>mine</var>, or as merging into <var>mine</var> the
changes that would turn <var>older</var> into <var>yours</var>. This merging is
well-defined as long as <var>mine</var> and <var>older</var> match in the
neighborhood of each such change. This fails to be true when all three
input files differ or when only <var>older</var> differs; we call this
a <em>conflict</em>. When all three input files differ, we call the
conflict an <em>overlap</em>.
</p>
<p><code>diff3</code> gives you several ways to handle overlaps and conflicts.
You can omit overlaps or conflicts, or select only overlaps,
or mark conflicts with special ‘<samp><<<<<<<</samp>’ and ‘<samp>>>>>>>></samp>’ lines.
</p>
<p><code>diff3</code> can output the merge results as an <code>ed</code> script that
that can be applied to the first file to yield the merged output.
However, it is usually better to have <code>diff3</code> generate the merged
output directly; this bypasses some problems with <code>ed</code>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Which-Changes" accesskey="1">Which Changes</a>:</td><td> </td><td align="left" valign="top">Selecting changes to incorporate.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Marking-Conflicts" accesskey="2">Marking Conflicts</a>:</td><td> </td><td align="left" valign="top">Marking conflicts.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Bypassing-ed" accesskey="3">Bypassing ed</a>:</td><td> </td><td align="left" valign="top">Generating merged output directly.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Merging-Incomplete-Lines" accesskey="4">Merging Incomplete Lines</a>:</td><td> </td><td align="left" valign="top">How <code>diff3</code> merges incomplete lines.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Saving-the-Changed-File" accesskey="5">Saving the Changed File</a>:</td><td> </td><td align="left" valign="top">Emulating System V behavior.
</td></tr>
</table>
<hr>
<a name="Which-Changes"></a>
<div class="header">
<p>
Next: <a href="#Marking-Conflicts" accesskey="n" rel="next">Marking Conflicts</a>, Up: <a href="#diff3-Merging" accesskey="u" rel="up">diff3 Merging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Selecting-Which-Changes-to-Incorporate"></a>
<h3 class="section">8.1 Selecting Which Changes to Incorporate</h3>
<a name="index-overlapping-change_002c-selection-of"></a>
<a name="index-unmerged-change"></a>
<p>You can select all unmerged changes from <var>older</var> to <var>yours</var> for merging
into <var>mine</var> with the <samp>--ed</samp> (<samp>-e</samp>) option. You can
select only the nonoverlapping unmerged changes with
<samp>--easy-only</samp> (<samp>-3</samp>),
and you can select only the overlapping changes with
<samp>--overlap-only</samp> (<samp>-x</samp>).
</p>
<p>The <samp>-e</samp>, <samp>-3</samp> and <samp>-x</samp> options select only
<em>unmerged changes</em>, i.e. changes where <var>mine</var> and <var>yours</var>
differ; they ignore changes from <var>older</var> to <var>yours</var> where
<var>mine</var> and <var>yours</var> are identical, because they assume that such
changes have already been merged. If this assumption is not a safe
one, you can use the <samp>--show-all</samp> (<samp>-A</samp>) option
(see <a href="#Marking-Conflicts">Marking Conflicts</a>).
</p>
<p>Here is the output of the command <code>diff3</code> with each of these three
options (see <a href="Comparing-Three-Files.html#Sample-diff3-Input">Sample diff3 Input</a>, for the complete contents of the files).
Notice that <samp>-e</samp> outputs the union of the disjoint sets of changes
output by <samp>-3</samp> and <samp>-x</samp>.
</p>
<p>Output of ‘<samp>diff3 -e lao tzu tao</samp>’:
</p><div class="example">
<pre class="example">11a
-- The Way of Lao-Tzu, tr. Wing-tsit Chan
.
8c
so we may see their result.
.
</pre></div>
<p>Output of ‘<samp>diff3 -3 lao tzu tao</samp>’:
</p><div class="example">
<pre class="example">8c
so we may see their result.
.
</pre></div>
<p>Output of ‘<samp>diff3 -x lao tzu tao</samp>’:
</p><div class="example">
<pre class="example">11a
-- The Way of Lao-Tzu, tr. Wing-tsit Chan
.
</pre></div>
<hr>
<a name="Marking-Conflicts"></a>
<div class="header">
<p>
Next: <a href="#Bypassing-ed" accesskey="n" rel="next">Bypassing ed</a>, Previous: <a href="#Which-Changes" accesskey="p" rel="prev">Which Changes</a>, Up: <a href="#diff3-Merging" accesskey="u" rel="up">diff3 Merging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Marking-Conflicts-1"></a>
<h3 class="section">8.2 Marking Conflicts</h3>
<a name="index-conflict-marking"></a>
<a name="index-_003c_003c_003c_003c_003c_003c_003c-for-marking-conflicts"></a>
<p><code>diff3</code> can mark conflicts in the merged output by
bracketing them with special marker lines. A conflict
that comes from two files <var>A</var> and <var>B</var> is marked as follows:
</p>
<div class="example">
<pre class="example"><<<<<<< <var>A</var>
<span class="roman">lines from <var>A</var></span>
=======
<span class="roman">lines from <var>B</var></span>
>>>>>>> <var>B</var>
</pre></div>
<p>A conflict that comes from three files <var>A</var>, <var>B</var> and <var>C</var> is
marked as follows:
</p>
<div class="example">
<pre class="example"><<<<<<< <var>A</var>
<span class="roman">lines from <var>A</var></span>
||||||| <var>B</var>
<span class="roman">lines from <var>B</var></span>
=======
<span class="roman">lines from <var>C</var></span>
>>>>>>> <var>C</var>
</pre></div>
<p>The <samp>--show-all</samp> (<samp>-A</samp>) option acts like the <samp>-e</samp>
option, except that it brackets conflicts, and it outputs all changes
from <var>older</var> to <var>yours</var>, not just the unmerged changes. Thus,
given the sample input files (see <a href="Comparing-Three-Files.html#Sample-diff3-Input">Sample diff3 Input</a>), ‘<samp>diff3
-A lao tzu tao</samp>’ puts brackets around the conflict where only <samp>tzu</samp>
differs:
</p>
<div class="example">
<pre class="example"><<<<<<< tzu
=======
The Way that can be told of is not the eternal Way;
The name that can be named is not the eternal name.
>>>>>>> tao
</pre></div>
<p>And it outputs the three-way conflict as follows:
</p>
<div class="example">
<pre class="example"><<<<<<< lao
||||||| tzu
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
=======
-- The Way of Lao-Tzu, tr. Wing-tsit Chan
>>>>>>> tao
</pre></div>
<p>The <samp>--show-overlap</samp> (<samp>-E</samp>) option outputs less information
than the <samp>--show-all</samp> (<samp>-A</samp>) option, because it outputs only
unmerged changes, and it never outputs the contents of the second
file. Thus the <samp>-E</samp> option acts like the <samp>-e</samp> option,
except that it brackets the first and third files from three-way
overlapping changes. Similarly, <samp>-X</samp> acts like <samp>-x</samp>, except
it brackets all its (necessarily overlapping) changes. For example,
for the three-way overlapping change above, the <samp>-E</samp> and <samp>-X</samp>
options output the following:
</p>
<div class="example">
<pre class="example"><<<<<<< lao
=======
-- The Way of Lao-Tzu, tr. Wing-tsit Chan
>>>>>>> tao
</pre></div>
<p>If you are comparing files that have meaningless or uninformative names,
you can use the <samp>--label=<var>label</var></samp>
option to show alternate names in the ‘<samp><<<<<<<</samp>’, ‘<samp>|||||||</samp>’
and ‘<samp>>>>>>>></samp>’ brackets. This option can be given up to three
times, once for each input file. Thus ‘<samp>diff3 -A --label X
--label Y --label Z A
B C</samp>’ acts like ‘<samp>diff3 -A A B C</samp>’, except that the output looks like
it came from files named ‘<samp>X</samp>’, ‘<samp>Y</samp>’ and ‘<samp>Z</samp>’ rather than
from files named ‘<samp>A</samp>’, ‘<samp>B</samp>’ and ‘<samp>C</samp>’.
</p>
<hr>
<a name="Bypassing-ed"></a>
<div class="header">
<p>
Next: <a href="#Merging-Incomplete-Lines" accesskey="n" rel="next">Merging Incomplete Lines</a>, Previous: <a href="#Marking-Conflicts" accesskey="p" rel="prev">Marking Conflicts</a>, Up: <a href="#diff3-Merging" accesskey="u" rel="up">diff3 Merging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Generating-the-Merged-Output-Directly"></a>
<h3 class="section">8.3 Generating the Merged Output Directly</h3>
<a name="index-merged-diff3-format"></a>
<p>With the <samp>--merge</samp> (<samp>-m</samp>) option, <code>diff3</code> outputs the
merged file directly. This is more efficient than using <code>ed</code> to
generate it, and works even with non-text files that <code>ed</code> would
reject. If you specify <samp>-m</samp> without an <code>ed</code> script option,
<samp>-A</samp> is assumed.
</p>
<p>For example, the command ‘<samp>diff3 -m lao tzu tao</samp>’
(see <a href="Comparing-Three-Files.html#Sample-diff3-Input">Sample diff3 Input</a> for a copy of the input files) would output
the following:
</p>
<div class="example">
<pre class="example"><<<<<<< tzu
=======
The Way that can be told of is not the eternal Way;
The name that can be named is not the eternal name.
>>>>>>> tao
The Nameless is the origin of Heaven and Earth;
The Named is the mother of all things.
Therefore let there always be non-being,
so we may see their subtlety,
And let there always be being,
so we may see their result.
The two are the same,
But after they are produced,
they have different names.
<<<<<<< lao
||||||| tzu
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
=======
-- The Way of Lao-Tzu, tr. Wing-tsit Chan
>>>>>>> tao
</pre></div>
<hr>
<a name="Merging-Incomplete-Lines"></a>
<div class="header">
<p>
Next: <a href="#Saving-the-Changed-File" accesskey="n" rel="next">Saving the Changed File</a>, Previous: <a href="#Bypassing-ed" accesskey="p" rel="prev">Bypassing ed</a>, Up: <a href="#diff3-Merging" accesskey="u" rel="up">diff3 Merging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="How-diff3-Merges-Incomplete-Lines"></a>
<h3 class="section">8.4 How <code>diff3</code> Merges Incomplete Lines</h3>
<a name="index-incomplete-line-merging"></a>
<p>With <samp>-m</samp>, incomplete lines (see <a href="Incomplete-Lines.html#Incomplete-Lines">Incomplete Lines</a>) are simply
copied to the output as they are found; if the merged output ends in an
conflict and one of the input files ends in an incomplete
line, succeeding ‘<samp>|||||||</samp>’, ‘<samp>=======</samp>’ or ‘<samp>>>>>>>></samp>’
brackets appear somewhere other than the start of a line because
they are appended to the incomplete line.
</p>
<p>Without <samp>-m</samp>, if an <code>ed</code> script option is specified and an
incomplete line is found, <code>diff3</code> generates a warning and acts as
if a newline had been present.
</p>
<hr>
<a name="Saving-the-Changed-File"></a>
<div class="header">
<p>
Previous: <a href="#Merging-Incomplete-Lines" accesskey="p" rel="prev">Merging Incomplete Lines</a>, Up: <a href="#diff3-Merging" accesskey="u" rel="up">diff3 Merging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Saving-the-Changed-File-1"></a>
<h3 class="section">8.5 Saving the Changed File</h3>
<a name="index-System-V-diff3-compatibility"></a>
<p>Traditional Unix <code>diff3</code> generates an <code>ed</code> script without the
trailing ‘<samp>w</samp>’ and ‘<samp>q</samp>’ commands that save the changes.
System V <code>diff3</code> generates these extra commands. <acronym>GNU</acronym>
<code>diff3</code> normally behaves like traditional Unix
<code>diff3</code>, but with the <samp>-i</samp> option it behaves like
System V <code>diff3</code> and appends the ‘<samp>w</samp>’ and ‘<samp>q</samp>’
commands.
</p>
<p>The <samp>-i</samp> option requires one of the <code>ed</code> script options
<samp>-AeExX3</samp>, and is incompatible with the merged output option
<samp>-m</samp>.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="#Merging-Incomplete-Lines" accesskey="p" rel="prev">Merging Incomplete Lines</a>, Up: <a href="#diff3-Merging" accesskey="u" rel="up">diff3 Merging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|