When two people have made changes to copies of the same file,
diff3 can produce a merged output that contains both sets of
changes together with warnings about conflicts.
One might imagine programs with names like diff4 and diff5
to compare more than three files simultaneously, but in practice the
need rarely arises. You can use diff3 to merge three or more
sets of changes to a file by merging two change sets at a time.
diff3 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:
diff3 mine older yours
You can remember the order of the arguments by noting that they are in alphabetical order.
You can think of this as subtracting older from yours and adding the result to mine, or as merging into mine the changes that would turn older into yours. This merging is well-defined as long as mine and older match in the neighborhood of each such change. This fails to be true when all three input files differ or when only older differs; we call this a conflict. When all three input files differ, we call the conflict an overlap.
diff3 gives you several ways to handle overlaps and conflicts.
You can omit overlaps or conflicts, or select only overlaps,
or mark conflicts with special `<<<<<<<' and `>>>>>>>' lines.
diff3 can output the merge results as an ed script that
that can be applied to the first file to yield the merged output.
However, it is usually better to have diff3 generate the merged
output directly; this bypasses some problems with ed.
diff3 merges incomplete lines.
You can select all unmerged changes from older to yours for merging into mine with the `-e' or `--ed' option. You can select only the nonoverlapping unmerged changes with `-3' or `--easy-only', and you can select only the overlapping changes with `-x' or `--overlap-only'.
The `-e', `-3' and `-x' options select only unmerged changes, i.e. changes where mine and yours differ; they ignore changes from older to yours where mine and yours are identical, because they assume that such changes have already been merged. If this assumption is not a safe one, you can use the `-A' or `--show-all' option (see section Marking Conflicts).
Here is the output of the command diff3 with each of these three
options (see section A Third Sample Input File, for the complete contents of the files).
Notice that `-e' outputs the union of the disjoint sets of changes
output by `-3' and `-x'.
Output of `diff3 -e lao tzu tao':
11a -- The Way of Lao-Tzu, tr. Wing-tsit Chan . 8c so we may see their result. .
Output of `diff3 -3 lao tzu tao':
8c so we may see their result. .
Output of `diff3 -x lao tzu tao':
11a -- The Way of Lao-Tzu, tr. Wing-tsit Chan .
diff3 can mark conflicts in the merged output by
bracketing them with special marker lines. A conflict
that comes from two files A and B is marked as follows:
<<<<<<< A lines from A ======= lines from B >>>>>>> B
A conflict that comes from three files A, B and C is marked as follows:
<<<<<<< A lines from A ||||||| B lines from B ======= lines from C >>>>>>> C
The `-A' or `--show-all' option acts like the `-e' option, except that it brackets conflicts, and it outputs all changes from older to yours, not just the unmerged changes. Thus, given the sample input files (see section A Third Sample Input File), `diff3 -A lao tzu tao' puts brackets around the conflict where only `tzu' differs:
<<<<<<< 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
And it outputs the three-way conflict as follows:
<<<<<<< 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
The `-E' or `--show-overlap' option outputs less information than the `-A' or `--show-all' option, because it outputs only unmerged changes, and it never outputs the contents of the second file. Thus the `-E' option acts like the `-e' option, except that it brackets the first and third files from three-way overlapping changes. Similarly, `-X' acts like `-x', except it brackets all its (necessarily overlapping) changes. For example, for the three-way overlapping change above, the `-E' and `-X' options output the following:
<<<<<<< lao ======= -- The Way of Lao-Tzu, tr. Wing-tsit Chan >>>>>>> tao
If you are comparing files that have meaningless or uninformative names, you can use the `-L label' or `--label=label' option to show alternate names in the `<<<<<<<', `|||||||' and `>>>>>>>' brackets. This option can be given up to three times, once for each input file. Thus `diff3 -A -L X -L Y -L Z A B C' acts like `diff3 -A A B C', except that the output looks like it came from files named `X', `Y' and `Z' rather than from files named `A', `B' and `C'.
With the `-m' or `--merge' option, diff3 outputs the
merged file directly. This is more efficient than using ed to
generate it, and works even with non-text files that ed would
reject. If you specify `-m' without an ed script option,
`-A' (`--show-all') is assumed.
For example, the command `diff3 -m lao tzu tao' (see section A Third Sample Input File for a copy of the input files) would output the following:
<<<<<<< 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
diff3 Merges Incomplete LinesWith `-m', incomplete lines (see section Incomplete Lines) 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 `|||||||', `=======' or `>>>>>>>' brackets appear somewhere other than the start of a line because they are appended to the incomplete line.
Without `-m', if an ed script option is specified and an
incomplete line is found, diff3 generates a warning and acts as
if a newline had been present.
Traditional Unix diff3 generates an ed script without the
trailing `w' and and `q' commands that save the changes.
System V diff3 generates these extra commands. GNU diff3
normally behaves like traditional Unix diff3, but with the
`-i' option it behaves like System V diff3 and appends the
`w' and `q' commands.
The `-i' option requires one of the ed script options
`-AeExX3', and is incompatible with the merged output option
`-m'.