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 June 23, 2022
  34 .Dt DIFF3 1
  35 .Os
  36 .Sh NAME
  37 .Nm diff3
  38 .Nd 3-way differential file comparison
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl 3AaEeimTXx
  42 .Op Fl Fl diff-program Ar program
  43 .Op Fl Fl strip-trailing-cr
  44 .Op Fl L | Fl Fl label Ar label1
  45 .Op Fl L | Fl Fl label Ar label2
  46 .Op Fl L | Fl Fl label Ar label3
  47 .Ar file1 file2 file3
  48 .Nm
  49 .Op Fl Fl help
  50 .Op Fl Fl version
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 utility compares the contents of three different versions of a file,
  55 .Ar file1 ,
  56 .Ar file2
  57 and
  58 .Ar file3 ,
  59 writing the result to the standard output.
  60 The options describe different methods of merging and
  61 purging
  62 the separate versions into a new file.
  63 .Nm
  64 is used by
  65 .Xr rcs 1
  66 to merge specific versions or create
  67 new versions.
  68 .Pp
  69 The options are as follows:
  70 .Bl -tag -width "-E, -X"
  71 .It Fl 3 , Fl Fl easy-only
  72 Produces an output script suitable for
  73 .Xr ed 1
  74 with changes
  75 specific only to
  76 .Ar file3 .
  77 .It Fl A Fl Fl show-all
  78 Output all changes, bracketing conflicts.
  79 .It Fl a , Fl Fl text
  80 Treat all files as ASCII.
  81 .It Fl E , Fl Fl show-overlap
  82 .It Fl X
  83 Similar to
  84 .Fl e
  85 and
  86 .Fl x ,
  87 respectively, but treat overlapping changes (i.e., changes that would
  88 be noted with ==== in the normal listing) differently.
  89 The overlapping lines from both files will be inserted by the edit script,
  90 bracketed by "<<<<<<" and ">>>>>>" lines.
  91 .It Fl e , Fl Fl ed
  92 Produces output in a form suitable as an input script for the
  93 .Xr ed 1
  94 utility.
  95 The script may then be used to merge differences common between all
  96 three files and differences specific to
  97 .Ar file1
  98 and
  99 .Ar file3 .
 100 In other words, the
 101 .Fl e
 102 option ignores differences specific to
 103 .Ar file1
 104 and
 105 .Ar file2 ,
 106 and those specific to
 107 .Ar file2
 108 and
 109 .Ar file3 .
 110 It is useful for backing out changes specific to
 111 .Ar file2
 112 only.
 113 .It Fl Fl help
 114 Prints usage information and exits.
 115 .It Fl i
 116 Appends 'w' and 'q'
 117 .Xr ed 1
 118 commands.
 119 .It Fl L , Fl Fl label
 120 Defines labels to print instead of file names
 121 .Ar file1 ,
 122 .Ar file2
 123 and
 124 .Ar file3 .
 125 .It Fl m, Fl Fl merge
 126 Merge output instead of generating ed script.
 127 .It Fl T, Fl Fl initial-tab
 128 In the normal listing,
 129 use a tab instead of two spaces
 130 at the beginning of each line.
 131 In modes that produce an
 132 .Xr ed 1
 133 script, this option changes nothing.
 134 .It Fl x, Fl Fl overlap-only
 135 Produces an output script suitable for
 136 .Xr ed 1
 137 with changes
 138 specific only to all three versions.
 139 .It Fl Fl diff-program Ar program
 140 Use
 141 .Ar program
 142 instead of the default
 143 .Xr diff 1
 144 to compare files.
 145 .It Fl Fl strip-trailing-cr
 146 Strip trailing carriage return on input files.
 147 .It Fl Fl version
 148 Prints version information and exits.
 149 .El
 150 .Pp
 151 The
 152 .Fl E
 153 option is used by
 154 .Tn RCS
 155 .Xr merge 1
 156 to ensure that overlapping changes in the merged files are preserved
 157 and brought to someone's attention.
 158 .Pp
 159 For example, suppose lines 7-8 are changed in both
 160 .Ar file1
 161 and
 162 .Ar file2 .
 163 Applying the edit script generated by the command
 164 .Pp
 165 .Dl $ diff3 -E file1 file2 file3
 166 .Pp
 167 to
 168 .Ar file1
 169 results in the file:
 170 .Bd -literal -offset indent
 171 lines 1-6
 172 of file1
 173 <<<<<<< file1
 174 lines 7-8
 175 of file1
 176 =======
 177 lines 7-8
 178 of file3
 179 >>>>>>> file3
 180 rest of file1
 181 .Ed
 182 .Pp
 183 The default output of
 184 .Nm
 185 makes notation of the differences between all files, and those
 186 differences specific to each pair of files.
 187 The changes are described by the commands necessary for
 188 .Xr ed 1
 189 to create the desired target from the different versions.
 190 See
 191 .Xr diff 1
 192 for a description of the commands.
 193 .Bl -tag -width "====="
 194 .It Li \&====
 195 The lines beneath this notation are ranges of lines which are different
 196 between all files.
 197 .It \&==== Ns Va n
 198 The lines beneath this notation are ranges of lines which are exclusively
 199 different in file
 200 .Va n .
 201 .El
 202 .Sh SEE ALSO
 203 .Xr diff 1 ,
 204 .Xr ed 1 ,
 205 .Xr merge 1 ,
 206 .Xr rcs 1 ,
 207 .Xr sdiff 1
 208 .Sh HISTORY
 209 A
 210 .Nm
 211 command appeared in
 212 .At v7 .
 213 .Sh BUGS
 214 The
 215 .Fl e
 216 option cannot catch and change lines which have
 217 .Ql \&.
 218 as the first and only character on the line.
 219 The resulting script will fail on that line
 220 as
 221 .Ql \&.
 222 is an
 223 .Xr ed 1
 224 editing command.