usr.bin/diff3/diff3.1

   1 .\" $OpenBSD: diff3.1,v 1.7 2007/05/31 19:20:09 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1993, 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)diff3.1     8.2 (Berkeley) 4/18/94
  31 .\" $FreeBSD$
  32 .\"
  33 .Dd May 25, 2017
  34 .Dt DIFF3 1
  35 .Os
  36 .Sh NAME
  37 .Nm diff3
  38 .Nd 3-way differential file comparison
  39 .Sh SYNOPSIS
  40 .Nm diff3
  41 .Op Fl 3aEeXx
  42 .Ar file1 file2 file3
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility compares the contents of three different versions of a file,
  47 .Ar file1 ,
  48 .Ar file2
  49 and
  50 .Ar file3 ,
  51 writing the result to the standard output.
  52 The options describe different methods of merging and
  53 purging
  54 the separate versions into a new file.
  55 .Nm
  56 is used by
  57 .Xr rcs 1
  58 to merge specific versions or create
  59 new versions.
  60 .Pp
  61 The options are as follows:
  62 .Bl -tag -width "-E, -X"
  63 .It Fl 3
  64 Produces an output script suitable for
  65 .Xr ed 1
  66 with changes
  67 specific only to
  68 .Ar file3 .
  69 .It Fl a
  70 Treat all files as ASCII.
  71 .It Fl E , X
  72 Similar to
  73 .Fl e
  74 and
  75 .Fl x ,
  76 respectively, but treat overlapping changes (i.e., changes that would
  77 be noted with ==== in the normal listing) differently.
  78 The overlapping lines from both files will be inserted by the edit script,
  79 bracketed by "<<<<<<" and ">>>>>>" lines.
  80 .It Fl e
  81 Produces output in a form suitable as an input script for the
  82 .Xr ed 1
  83 utility.
  84 The script may then be used to merge differences common between all
  85 three files and differences specific to
  86 .Ar file1
  87 and
  88 .Ar file3 .
  89 In other words, the
  90 .Fl e
  91 option ignores differences specific to
  92 .Ar file1
  93 and
  94 .Ar file2 ,
  95 and those specific to
  96 .Ar file2
  97 and
  98 .Ar file3 .
  99 It is useful for backing out changes specific to
 100 .Ar file2
 101 only.
 102 .It Fl x
 103 Produces an output script suitable for
 104 .Xr ed 1
 105 with changes
 106 specific only to all three versions.
 107 .El
 108 .Pp
 109 The
 110 .Fl E
 111 option is used by
 112 .Tn RCS
 113 .Xr merge 1
 114 to ensure that overlapping changes in the merged files are preserved
 115 and brought to someone's attention.
 116 .Pp
 117 For example, suppose lines 7-8 are changed in both
 118 .Ar file1
 119 and
 120 .Ar file2 .
 121 Applying the edit script generated by the command
 122 .Pp
 123 .Dl $ diff3 -E file1 file2 file3
 124 .Pp
 125 to
 126 .Ar file1
 127 results in the file:
 128 .Bd -literal -offset indent
 129 lines 1-6
 130 of file1
 131 <<<<<<< file1
 132 lines 7-8
 133 of file1
 134 =======
 135 lines 7-8
 136 of file3
 137 >>>>>>> file3
 138 rest of file1
 139 .Ed
 140 .Pp
 141 The default output of
 142 .Nm
 143 makes notation of the differences between all files, and those
 144 differences specific to each pair of files.
 145 The changes are described by the commands necessary for
 146 .Xr ed 1
 147 to create the desired target from the different versions.
 148 See
 149 .Xr diff 1
 150 for a description of the commands.
 151 .Bl -tag -width "====="
 152 .It Li \&====
 153 The lines beneath this notation are ranges of lines which are different
 154 between all files.
 155 .It \&==== Ns Va n
 156 The lines beneath this notation are ranges of lines which are exclusively
 157 different in file
 158 .Va n .
 159 .El
 160 .Sh SEE ALSO
 161 .Xr diff 1 ,
 162 .Xr ed 1 ,
 163 .Xr merge 1 ,
 164 .Xr rcs 1 ,
 165 .Xr sdiff 1
 166 .Sh HISTORY
 167 A
 168 .Nm
 169 command appeared in
 170 .At v7 .
 171 .Sh BUGS
 172 The
 173 .Fl e
 174 option cannot catch and change lines which have
 175 .Ql \&.
 176 as the first and only character on the line.
 177 The resulting script will fail on that line
 178 as
 179 .Ql \&.
 180 is an
 181 .Xr ed 1
 182 editing command.