Annotation of src/usr.bin/diff3/diff3.1, Revision 1.6
1.6 ! jmc 1: .\" $OpenBSD: diff3.1,v 1.5 2005/12/27 12:48:56 jmc Exp $
1.1 millert 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: .\"
32: .Dd April 18, 1994
33: .Dt DIFF3 1
34: .Os
35: .Sh NAME
36: .Nm diff3
37: .Nd 3-way differential file comparison
38: .Sh SYNOPSIS
39: .Nm diff3
1.6 ! jmc 40: .Op Fl 3aEeXx
1.1 millert 41: .Ar file1 file2 file3
42: .Sh DESCRIPTION
43: The
44: .Nm
45: utility compares the contents of three different versions of a file,
46: .Ar file1 ,
47: .Ar file2
48: and
49: .Ar file3 ,
50: writing the result to the standard output.
51: The options describe different methods of merging and
52: purging
53: the separate versions into a new file.
54: .Nm
55: is used by
1.3 jmc 56: .Xr rcs 1
1.1 millert 57: to merge specific versions or create
58: new versions.
59: .Pp
60: The options are as follows:
61: .Bl -tag -width "-E, -X"
1.6 ! jmc 62: .It Fl 3
! 63: Produces an output script suitable for
! 64: .Xr ed 1
! 65: with changes
! 66: specific only to
! 67: .Ar file3 .
1.1 millert 68: .It Fl a
69: Treat all files as ASCII.
1.6 ! jmc 70: .It Fl E , X
! 71: Similar to
! 72: .Fl e
! 73: and
! 74: .Fl x ,
! 75: respectively, but treat overlapping changes (i.e., changes that would
! 76: be noted with ==== in the normal listing) differently.
! 77: The overlapping lines from both files will be inserted by the edit script,
! 78: bracketed by "<<<<<<" and ">>>>>>" lines.
1.1 millert 79: .It Fl e
80: Produces output in a form suitable as an input script for the
81: .Xr ed 1
82: utility.
83: The script may then be used to merge differences common between all
84: three files and differences specific to
85: .Ar file1
86: and
87: .Ar file3 .
88: In other words, the
89: .Fl e
90: option ignores differences specific to
91: .Ar file1
92: and
93: .Ar file2 ,
94: and those specific to
95: .Ar file2
96: and
97: .Ar file3 .
98: It is useful for backing out changes specific to
99: .Ar file2
100: only.
101: .It Fl x
102: Produces an output script suitable for
103: .Xr ed 1
104: with changes
105: specific only to all three versions.
106: .El
107: .Pp
108: The
109: .Fl E
110: option is used by
111: .Tn RCS
1.3 jmc 112: .Xr merge 1
1.1 millert 113: to ensure that overlapping changes in the merged files are preserved
114: and brought to someone's attention.
115: .Pp
116: For example, suppose lines 7-8 are changed in both
117: .Ar file1
118: and
119: .Ar file2 .
120: Applying the edit script generated by the command
121: .Pp
1.4 jaredy 122: .Dl $ diff3 -E file1 file2 file3
1.1 millert 123: .Pp
124: to
125: .Ar file1
126: results in the file:
1.3 jmc 127: .Bd -literal -offset indent
1.1 millert 128: lines 1-6
129: of file1
130: <<<<<<< file1
131: lines 7-8
132: of file1
133: =======
134: lines 7-8
135: of file3
136: >>>>>>> file3
137: rest of file1
138: .Ed
139: .Pp
140: The default output of
141: .Nm
142: makes notation of the differences between all files, and those
143: differences specific to each pair of files.
144: The changes are described by the commands necessary for
1.2 deraadt 145: .Xr ed 1
1.1 millert 146: to create the desired target from the different versions.
147: See
148: .Xr diff 1
149: for a description of the commands.
150: .Bl -tag -width "====="
151: .It Li \&====
152: The lines beneath this notation are ranges of lines which are different
153: between all files.
154: .It \&==== Ns Va n
155: The lines beneath this notation are ranges of lines which are exclusively
156: different in file
157: .Va n .
158: .El
159: .Sh ENVIRONMENT
160: .Bl -tag -width TMPDIR
161: .It Ev TMPDIR
162: If the environment variable
163: .Ev TMPDIR
164: exists,
165: .Nm
166: will use the directory specified by
167: .Ev TMPDIR
168: as the temporary directory.
169: .El
170: .Sh FILES
171: .Bl -tag -width /usr/libexec/diff3prog -compact
172: .It Pa /tmp/d3a.XXXXXXXXXX
173: temporary file
174: .It Pa /tmp/d3b.XXXXXXXXXX
175: temporary file
1.4 jaredy 176: .It Pa /usr/libexec/diff3prog
1.1 millert 177: the actual executable
178: .El
179: .Sh SEE ALSO
180: .Xr diff 1 ,
181: .Xr ed 1 ,
1.3 jmc 182: .Xr merge 1 ,
1.5 jmc 183: .Xr rcs 1 ,
184: .Xr sdiff 1
1.3 jmc 185: .Sh HISTORY
186: A
187: .Nm
188: command appeared in
189: .At v7 .
1.1 millert 190: .Sh BUGS
191: The
192: .Fl e
193: option cannot catch and change lines which have
194: .Ql \&.
195: as the first and only character on the line.
196: The resulting script will fail on that line
197: as
198: .Ql \&.
199: is an
200: .Xr ed 1
201: editing command.