BSD 4_4 release

[unix-history] / usr / src / usr.bin / diff / diff3 / diff3.1

diff --git a/usr/src/usr.bin/diff/diff3/diff3.1 b/usr/src/usr.bin/diff/diff3/diff3.1
index 8fe83db..890fdd3 100644 (file)
--- a/usr/src/usr.bin/diff/diff3/diff3.1
+++ b/usr/src/usr.bin/diff/diff3/diff3.1
@@ -1,98 +1,172 @@
-.\"    @(#)diff3.1     5.1 (Berkeley) %G%
+.\" Copyright (c) 1990, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.TH DIFF3 1  "18 January 1983"
-.AT 3
-.SH NAME
-diff3 \- 3-way differential file comparison
-.SH SYNOPSIS
-.B diff3
-[
-.B \-ex3
-]
-file1 file2 file3
-.SH DESCRIPTION
-.I Diff3
-compares three versions of a file,
-and publishes disagreeing ranges of text
-flagged with these codes:
-.TP 16
-====
-all three files differ
-.TP 16
-====1
-.IR file1 " is different"
-.TP 16
-====2
-.IR file2 " is different"
-.TP 16
-====3
-.IR file3 " is different"
-.PP
-The type of change suffered in converting a given range
-of a given file to some other is
-indicated in one of these ways:
-.TP 16
-.IB f " : " n1 " a"
-Text is to be appended after line number
-.I n1
-in file
-.I f,
-where
-.I f
-= 1, 2, or 3.
-.TP 16
-.IB f " : " n1 " , " n2 " c"
-Text is to be
-changed in the range line
-.I n1
-to line
-.IR n2 .
-If 
-.I n1
-=
-.I n2,
-the range may be abbreviated to
-.IR n1 .
-.PP
-The original contents of the range follows immediately
-after a
-.B c
-indication.
-When the contents of two
-files are identical, the contents of the lower-numbered
-file is suppressed.
-.PP
-Under the
-.B \-e
-option,
-.I diff3
-publishes a script for the editor
-.I ed
-that will incorporate into
-.I file1
-all changes between
-.I file2
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)diff3.1    8.1 (Berkeley) 6/6/93
+.\"
+.Dd June 6, 1993
+.Dt DIFF3 1
+.Os BSD 4.3R
+.Sh NAME
+.Nm diff3
+.Nd 3-way differential file comparison
+.Sh SYNOPSIS
+.Nm diff3
+.Op Fl exEX3
+.Ar file1 file2 file3
+.Sh DESCRIPTION
+The
+.Nm diff3
+utility compares the contents of three different versions of a file,
+.Ar file1 ,
+.Ar file2
+and
+.Ar file3 ,
+writing the result to the standard output.
+The options describe different methods of merging and
+purging
+the separate versions into a new file.
+.Nm Diff3
+is used by
+.Xr RCS 1
+to merge specific versions or create
+new versions.
+.Pp
+Options are:
+.Bl -tag -width "--E, --X"
+.It Fl e
+Produces output in a form suitable as an input script for the
+.Xr ed 1
+utility.  The script may then be used to merge differences common
+between all three files and differences specific to file1 and file3.
+In other words, the
+.Fl e
+option ignores differences specific to file1 and file2, and those
+specific to file2 and file3.  It is useful for backing out changes
+specific to file2 only.
+.It Fl x
+Produces an output script suitable for
+.Xr ed 1
+with changes
+specific only to all three versions.
+.It Fl 3
+Produces an output script suitable for
+.Xr ed 1
+with changes
+specific only to file3.
+.It Fl E , X
+Similar to
+.Fl e

 and
 and

-.I file3,
-.IR i.e .
-the changes that normally would be flagged ==== and ====3.
-Option
-.B \-x
-(\fB\-3\fR)
-produces a script to incorporate
-only changes flagged ==== (====3).
-The following command will apply the resulting script to
-`file1'.
-.PP
-.ti 16n
-(cat script; echo \'1,$p\') \(bv ed \- file1
-.SH FILES
-/tmp/d3?????
-.br
-/usr/lib/diff3
-.SH "SEE ALSO"
-diff(1)
-.SH BUGS
-Text lines that consist of a single `.' will
-defeat
-.B \-e.
+.Fl x  ,
+respectively, but treat overlapping changes (i.e., changes that would
+be noted with ==== in the normal listing) differently.  The overlapping
+lines from both files will be inserted by the edit script, bracketed
+by "<<<<<<" and ">>>>>>" lines.
+.El
+.Pp
+The
+.Fl E
+option is used by
+.Tn RCS
+.Xr merge  1
+to insure that overlapping changes in the merged files are preserved
+and brought to someone's attention.
+.Pp
+For example, suppose lines 7-8 are changed in both file1 and file2.
+Applying the edit script generated by the command
+.Pp
+.Dl diff3 -E file1 file2 file3
+.Pp
+to file1 results in the file:
+.Pp
+.Bd -literal -offset indent -compact
+lines 1-6
+of file1
+<<<<<<< file1
+lines 7-8
+of file1
+=======
+lines 7-8
+of file3
+>>>>>>> file3
+rest of file1
+.Ed
+.Pp
+The default output of
+.Nm diff3
+makes notation of the differences between all files, and those differences
+specific to each pair of files. The
+changes are described by
+the commands neccessary for
+.Xr ed 1 
+to create the desired target from the different versions.
+See
+.Xr diff 1
+for a description of the commands.
+.Bl -tag -width "====="
+.It Li \&====
+The lines beneath this notation are ranges of lines which are different
+between all files.
+.It \&==== Ns Va n
+The lines beneath this notation are ranges of lines which are exclusively
+different in file
+.Va n .
+.El
+.Sh FILES
+.Bl -tag -width /usr/bin/diff3 -compact
+.It Pa /tmp/d3?????
+temporary files.
+.It Pa /usr/bin/diff3
+the executable.
+.El
+.Sh SEE ALSO
+.Xr diff 1
+.Xr ed 1
+.Xr rcs 1
+.Sh BUGS
+The
+.Fl e
+option
+cannot catch and change
+lines which have
+.Ql \&.
+as the first and only character on the line.
+The resulting script will fail on that line
+as
+.Ql \&.
+is an
+.Xr ed 1
+editing command.
+.Sh HISTORY
+A
+.Nm
+command appeared in
+.At v7 .