diff.texi

这是一个同样来自贝尔实验室的和UNIX有着渊源的操作系统, 其简洁的设计和实现易于我们学习和理解

output line represents two differing lines, one might be incomplete
while the other is not.  In this case, the output line is complete,
but its the gutter is marked @samp{\} if the first line is incomplete,
@samp{/} if the second line is.

Side by side format is sometimes easiest to read, but it has limitations.
It generates much wider output than usual, and truncates lines that are
too long to fit.  Also, it relies on lining up output more heavily than
usual, so its output looks particularly bad if you use varying
width fonts, nonstandard tab stops, or nonprinting characters.

You can use the @code{sdiff} command to interactively merge side by side
differences.  @xref{Interactive Merging}, for more information on merging files.

@menu
* Side by Side Format::		Controlling side by side output format.
* Example Side by Side::	Sample side by side output.
@end menu

@node Side by Side Format, Example Side by Side, , Side by Side
@section Controlling Side by Side Format
@cindex side by side format

The @samp{-y} or @samp{--side-by-side} option selects side by side
format.  Because side by side output lines contain two input lines, they
are wider than usual.  They are normally 130 columns, which can fit onto
a traditional printer line.  You can set the length of output lines with
the @samp{-W @var{columns}} or @samp{--width=@var{columns}} option.  The
output line is split into two halves of equal length, separated by a
small gutter to mark differences; the right half is aligned to a tab
stop so that tabs line up.  Input lines that are too long to fit in half
of an output line are truncated for output.

The @samp{--left-column} option prints only the left column of two
common lines.  The @samp{--suppress-common-lines} option suppresses
common lines entirely.

@node Example Side by Side, , Side by Side Format, Side by Side
@subsection An Example of Side by Side Format

Here is the output of the command @samp{diff -y -W 72 lao tzu}
(@pxref{Sample diff Input}, for the complete contents of the two files).

@example
The Way that can be told of is n   <
The name that can be named is no   <
The Nameless is the origin of He        The Nameless is the origin of He
The Named is the mother of all t   |    The named is the mother of all t
                                   >
Therefore let there always be no        Therefore let there always be no
  so we may see their subtlety,           so we may see their subtlety,
And let there always be being,          And let there always be being,
  so we may see their outcome.            so we may see their outcome.
The two are the same,                   The two are the same,
But after they are produced,            But after they are produced,
  they have different names.              they have different names.
                                   >    They both may be called deep and
                                   >    Deeper and more profound,
                                   >    The door of all subtleties!
@end example

@node Scripts, If-then-else, Side by Side, Output Formats
@section Making Edit Scripts
@cindex script output formats

Several output modes produce command scripts for editing @var{from-file}
to produce @var{to-file}.

@menu
* ed Scripts::		Using @code{diff} to produce commands for @code{ed}.
* Forward ed::		Making forward @code{ed} scripts.
* RCS::			A special @code{diff} output format used by RCS.
@end menu

@node ed Scripts, Forward ed, , Scripts
@subsection @code{ed} Scripts
@cindex @code{ed} script output format

@code{diff} can produce commands that direct the @code{ed} text editor
to change the first file into the second file.  Long ago, this was the
only output mode that was suitable for editing one file into another
automatically; today, with @code{patch}, it is almost obsolete.  Use the
@samp{-e} or @samp{--ed} option to select this output format.

Like the normal format (@pxref{Normal}), this output format does not
show any context; unlike the normal format, it does not include the
information necessary to apply the diff in reverse (to produce the first
file if all you have is the second file and the diff).

If the file @file{d} contains the output of @samp{diff -e old new}, then
the command @samp{(cat d && echo w) | ed - old} edits @file{old} to make
it a copy of @file{new}.  More generally, if @file{d1}, @file{d2},
@dots{}, @file{dN} contain the outputs of @samp{diff -e old new1},
@samp{diff -e new1 new2}, @dots{}, @samp{diff -e newN-1 newN},
respectively, then the command @samp{(cat d1 d2 @dots{} dN && echo w) |
ed - old} edits @file{old} to make it a copy of @file{newN}.

@menu
* Detailed ed::		A detailed description of @code{ed} format.
* Example ed::		A sample @code{ed} script.
@end menu

@node Detailed ed, Example ed, , ed Scripts
@subsubsection Detailed Description of @code{ed} Format

The @code{ed} output format consists of one or more hunks of
differences.  The changes closest to the ends of the files come first so
that commands that change the number of lines do not affect how
@code{ed} interprets line numbers in succeeding commands.  @code{ed}
format hunks look like this:

@example
@var{change-command}
@var{to-file-line}
@var{to-file-line}@dots{}
.
@end example

Because @code{ed} uses a single period on a line to indicate the end of
input, GNU @code{diff} protects lines of changes that contain a single
period on a line by writing two periods instead, then writing a
subsequent @code{ed} command to change the two periods into one.  The
@code{ed} format cannot represent an incomplete line, so if the second
file ends in a changed incomplete line, @code{diff} reports an error and
then pretends that a newline was appended.

There are three types of change commands.  Each consists of a line
number or comma-separated range of lines in the first file and a single
character indicating the kind of change to make.  All line numbers are
the original line numbers in the file.  The types of change commands
are:

@table @samp
@item @var{l}a
Add text from the second file after line @var{l} in the first file.  For
example, @samp{8a} means to add the following lines after line 8 of file
1.

@item @var{r}c
Replace the lines in range @var{r} in the first file with the following
lines.  Like a combined add and delete, but more compact.  For example,
@samp{5,7c} means change lines 5--7 of file 1 to read as the text file
2.

@item @var{r}d
Delete the lines in range @var{r} from the first file.  For example,
@samp{5,7d} means delete lines 5--7 of file 1.
@end table

@node Example ed, , Detailed ed, ed Scripts
@subsubsection Example @code{ed} Script

Here is the output of @samp{diff -e lao tzu} (@pxref{Sample
diff Input}, for the complete contents of the two files):

@example
11a
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
.
4c
The named is the mother of all things.

.
1,2d
@end example

@node Forward ed, RCS, ed Scripts, Scripts
@subsection Forward @code{ed} Scripts
@cindex forward @code{ed} script output format

@code{diff} can produce output that is like an @code{ed} script, but
with hunks in forward (front to back) order.  The format of the commands
is also changed slightly: command characters precede the lines they
modify, spaces separate line numbers in ranges, and no attempt is made
to disambiguate hunk lines consisting of a single period.  Like
@code{ed} format, forward @code{ed} format cannot represent incomplete
lines.

Forward @code{ed} format is not very useful, because neither @code{ed}
nor @code{patch} can apply diffs in this format.  It exists mainly for
compatibility with older versions of @code{diff}.  Use the @samp{-f} or
@samp{--forward-ed} option to select it.

@node RCS, , Forward ed, Scripts
@subsection RCS Scripts
@cindex RCS script output format

The RCS output format is designed specifically for use by the Revision
Control System, which is a set of free programs used for organizing
different versions and systems of files.  Use the @samp{-n} or
@samp{--rcs} option to select this output format.  It is like the
forward @code{ed} format (@pxref{Forward ed}), but it can represent
arbitrary changes to the contents of a file because it avoids the
forward @code{ed} format's problems with lines consisting of a single
period and with incomplete lines.  Instead of ending text sections with
a line consisting of a single period, each command specifies the number
of lines it affects; a combination of the @samp{a} and @samp{d}
commands are used instead of @samp{c}.  Also, if the second file ends
in a changed incomplete line, then the output also ends in an
incomplete line.

Here is the output of @samp{diff -n lao tzu} (@pxref{Sample
diff Input}, for the complete contents of the two files):

@example
d1 2
d4 1
a4 2
The named is the mother of all things.

a11 3
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
@end example

@node If-then-else, , Scripts, Output Formats
@section Merging Files with If-then-else
@cindex merged output format
@cindex if-then-else output format
@cindex C if-then-else output format
@cindex @code{ifdef} output format

You can use @code{diff} to merge two files of C source code.  The output
of @code{diff} in this format contains all the lines of both files.
Lines common to both files are output just once; the differing parts are
separated by the C preprocessor directives @code{#ifdef @var{name}} or
@code{#ifndef @var{name}}, @code{#else}, and @code{#endif}.  When
compiling the output, you select which version to use by either defining
or leaving undefined the macro @var{name}.

To merge two files, use @code{diff} with the @samp{-D @var{name}} or
@samp{--ifdef=@var{name}} option.  The argument @var{name} is the C
preprocessor identifier to use in the @code{#ifdef} and @code{#ifndef}
directives.

For example, if you change an instance of @code{wait (&s)} to
@code{waitpid (-1, &s, 0)} and then merge the old and new files with
the @samp{--ifdef=HAVE_WAITPID} option, then the affected part of your code
might look like this:

@example
    do @{
#ifndef HAVE_WAITPID
        if ((w = wait (&s)) < 0  &&  errno != EINTR)
#else /* HAVE_WAITPID */
        if ((w = waitpid (-1, &s, 0)) < 0  &&  errno != EINTR)
#endif /* HAVE_WAITPID */
            return w;
    @} while (w != child);
@end example

You can specify formats for languages other than C by using line group
formats and line formats, as described in the next sections.

@menu
* Line Group Formats::		Formats for general if-then-else line groups.
* Line Formats::		Formats for each line in a line group.
* Detailed If-then-else::	A detailed description of if-then-else format.
* Example If-then-else::	Sample if-then-else format output.
@end menu

@node Line Group Formats, Line Formats, , If-then-else
@subsection Line Group Formats
@cindex line group formats
@cindex formats for if-then-else line groups

Line group formats let you specify formats suitable for many
applications that allow if-then-else input, including programming
languages and text formatting languages.  A line group format specifies
the output format for a contiguous group of similar lines.

For example, the following command compares the TeX files @file{old}
and @file{new}, and outputs a merged file in which old regions are
surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new
regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines.

@example
diff \
   --old-group-format='\begin@{em@}
%<\end@{em@}
' \
   --new-group-format='\begin@{bf@}
%>\end@{bf@}
' \
   old new
@end example

The following command is equivalent to the above example, but it is a
little more verbose, because it spells out the default line group formats.

@example
diff \
   --old-group-format='\begin@{em@}
%<\end@{em@}
' \
   --new-group-format='\begin@{bf@}
%>\end@{bf@}
' \
   --unchanged-group-format='%=' \
   --changed-group-format='\begin@{em@}
%<\end@{em@}
\begin@{bf@}
%>\end@{bf@}
' \
   old new
@end example

Here is a more advanced example, which outputs a diff listing with
headers containing line numbers in a ``plain English'' style.

@example
diff \
   --unchanged-group-format='' \
   --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
%<' \
   --new-group-format='-------- %dN line%(N=1?:s) added after %de:
%>' \
   --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
%<-------- to:
%>' \
   old new
@end example

To specify a line group format, use @code{diff} with one of the options
listed below.  You can specify up to four line group formats, one for
each kind of line group.  You should quote @var{format}, because it
typically contains shell metacharacters.

@table @samp
@item --old-group-format=@var{format}
These line groups are hunks containing only lines from the first file.