Annotation of src/usr.bin/diff3/diff3.1, Revision 1.2
1.2 ! deraadt 1: .\" $OpenBSD: diff3.1,v 1.1 2003/07/10 16:06:07 millert 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
40: .Op Fl aexEX3
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
56: .Xr RCS 1
57: to merge specific versions or create
58: new versions.
59: .Pp
60: The options are as follows:
61: .Bl -tag -width "-E, -X"
62: .It Fl a
63: Treat all files as ASCII.
64: .It Fl e
65: Produces output in a form suitable as an input script for the
66: .Xr ed 1
67: utility.
68: The script may then be used to merge differences common between all
69: three files and differences specific to
70: .Ar file1
71: and
72: .Ar file3 .
73: In other words, the
74: .Fl e
75: option ignores differences specific to
76: .Ar file1
77: and
78: .Ar file2 ,
79: and those specific to
80: .Ar file2
81: and
82: .Ar file3 .
83: It is useful for backing out changes specific to
84: .Ar file2
85: only.
86: .It Fl x
87: Produces an output script suitable for
88: .Xr ed 1
89: with changes
90: specific only to all three versions.
91: .It Fl 3
92: Produces an output script suitable for
93: .Xr ed 1
94: with changes
95: specific only to
96: .Ar file3 .
97: .It Fl E , X
98: Similar to
99: .Fl e
100: and
101: .Fl x ,
102: respectively, but treat overlapping changes (i.e., changes that would
103: be noted with ==== in the normal listing) differently.
104: The overlapping lines from both files will be inserted by the edit script,
105: bracketed by "<<<<<<" and ">>>>>>" lines.
106: .El
107: .Pp
108: The
109: .Fl E
110: option is used by
111: .Tn RCS
112: .Xr merge 1
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
122: .Dl diff3 -E file1 file2 file3
123: .Pp
124: to
125: .Ar file1
126: results in the file:
127: .Pp
128: .Bd -literal -offset indent -compact
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
1.2 ! deraadt 146: .Xr ed 1
1.1 millert 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 ENVIRONMENT
161: .Bl -tag -width TMPDIR
162: .It Ev TMPDIR
163: If the environment variable
164: .Ev TMPDIR
165: exists,
166: .Nm
167: will use the directory specified by
168: .Ev TMPDIR
169: as the temporary directory.
170: .El
171: .Sh FILES
172: .Bl -tag -width /usr/libexec/diff3prog -compact
173: .It Pa /tmp/d3a.XXXXXXXXXX
174: temporary file
175: .It Pa /tmp/d3b.XXXXXXXXXX
176: temporary file
177: .It Pa /usr/libexec/diff3
178: the actual executable
179: .El
180: .Sh SEE ALSO
181: .Xr diff 1 ,
182: .Xr ed 1 ,
183: .Xr merge 1
184: .Xr rcs 1
185: .Sh BUGS
186: The
187: .Fl e
188: option cannot catch and change lines which have
189: .Ql \&.
190: as the first and only character on the line.
191: The resulting script will fail on that line
192: as
193: .Ql \&.
194: is an
195: .Xr ed 1
196: editing command.
197: .Sh HISTORY
198: A
199: .Nm
200: command appeared in
201: .At v7 .