source: trunk/essentials/sys-apps/diffutils/doc/diff.texi@ 3506

\input texinfo @c -*-texinfo-*-
@comment $Id$
@comment %**start of header
@setfilename diff.info
@include version.texi
@settitle Comparing and Merging Files
@syncodeindex vr cp
@setchapternewpage odd
@comment %**end of header
@copying
This manual is for GNU Diffutils
(version @value{VERSION}, @value{UPDATED}),
and documents the @sc{gnu} @command{diff}, @command{diff3},
@command{sdiff}, and @command{cmp} commands for showing the
differences between files and the @sc{gnu} @command{patch} command for
using their output to update files.

Copyright @copyright{} 1992, 1993, 1994, 1998, 2001, 2002 Free
Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying

@c Debian install-info (up through at least version 1.9.20) uses only the
@c first dircategory.  Put this one first, as it is more useful in practice.
@dircategory Individual utilities
@direntry
* cmp: (diff)Invoking cmp.                      Compare 2 files byte by byte.
* diff: (diff)Invoking diff.                    Compare 2 files line by line.
* diff3: (diff)Invoking diff3.                  Compare 3 files line by line.
* patch: (diff)Invoking patch.                  Apply a patch to a file.
* sdiff: (diff)Invoking sdiff.                  Merge 2 files side-by-side.
@end direntry

@dircategory GNU packages
@direntry
* Diff: (diff).                 Comparing and merging files.
@end direntry

@titlepage
@title Comparing and Merging Files
@subtitle for Diffutils @value{VERSION} and @code{patch} 2.5.4
@subtitle @value{UPDATED}
@author David MacKenzie, Paul Eggert, and Richard Stallman
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@shortcontents
@contents

@ifnottex
@node Top
@top Comparing and Merging Files

@insertcopying
@end ifnottex

@menu
* Overview::              Preliminary information.
* Comparison::            What file comparison means.

* Output Formats::        Formats for two-way difference reports.
* Incomplete Lines::      Lines that lack trailing newlines.
* Comparing Directories:: Comparing files and directories.
* Adjusting Output::      Making @command{diff} output prettier.
* diff Performance::      Making @command{diff} smarter or faster.

* Comparing Three Files:: Formats for three-way difference reports.
* diff3 Merging::         Merging from a common ancestor.

* Interactive Merging::   Interactive merging with @command{sdiff}.

* Merging with patch::    Using @command{patch} to change old files into new ones.
* Making Patches::        Tips for making and using patch distributions.

* Invoking cmp::          Compare two files byte by byte.
* Invoking diff::         Compare two files line by line.
* Invoking diff3::        Compare three files line by line.
* Invoking patch::        Apply a diff file to an original.
* Invoking sdiff::        Side-by-side merge of file differences.

* Standards conformance:: Conformance to the @sc{posix} standard.
* Projects::              If you've found a bug or other shortcoming.

* Copying This Manual::   How to make copies of this manual.
* Index::                 Index.
@end menu

@node Overview
@unnumbered Overview
@cindex overview of @command{diff} and @command{patch}

Computer users often find occasion to ask how two files differ.  Perhaps
one file is a newer version of the other file.  Or maybe the two files
started out as identical copies but were changed by different people.

You can use the @command{diff} command to show differences between two
files, or each corresponding file in two directories.  @command{diff}
outputs differences between files line by line in any of several
formats, selectable by command line options.  This set of differences is
often called a @dfn{diff} or @dfn{patch}.  For files that are identical,
@command{diff} normally produces no output; for binary (non-text) files,
@command{diff} normally reports only that they are different.

You can use the @command{cmp} command to show the byte and line numbers
where two files differ.  @command{cmp} can also show all the bytes
that differ between the two files, side by side.  A way to compare
two files character by character is the Emacs command @kbd{M-x
compare-windows}.  @xref{Other Window, , Other Window, emacs, The @sc{gnu}
Emacs Manual}, for more information on that command.

You can use the @command{diff3} command to show differences among three
files.  When two people have made independent changes to a common
original, @command{diff3} can report the differences between the original
and the two changed versions, and can produce a merged file that
contains both persons' changes together with warnings about conflicts.

You can use the @command{sdiff} command to merge two files interactively.

You can use the set of differences produced by @command{diff} to distribute
updates to text files (such as program source code) to other people.
This method is especially useful when the differences are small compared
to the complete files.  Given @command{diff} output, you can use the
@command{patch} program to update, or @dfn{patch}, a copy of the file.  If you
think of @command{diff} as subtracting one file from another to produce
their difference, you can think of @command{patch} as adding the difference
to one file to reproduce the other.

This manual first concentrates on making diffs, and later shows how to
use diffs to update files.

@sc{gnu} @command{diff} was written by Paul Eggert, Mike Haertel,
David Hayes, Richard Stallman, and Len Tower.  Wayne Davison designed and
implemented the unified output format.  The basic algorithm is described
in ``An O(ND) Difference Algorithm and its Variations'', Eugene W. Myers,
@cite{Algorithmica} Vol.@: 1 No.@: 2, 1986, pp.@: 251--266; and in ``A File
Comparison Program'', Webb Miller and Eugene W. Myers,
@cite{Software---Practice and Experience} Vol.@: 15 No.@: 11, 1985,
pp.@: 1025--1040.
@c From: "Gene Myers" <[email protected]>
@c They are about the same basic algorithm; the Algorithmica
@c paper gives a rigorous treatment and the sub-algorithm for
@c delivering scripts and should be the primary reference, but
@c both should be mentioned.
The algorithm was independently discovered as described in
``Algorithms for Approximate String Matching'',
E. Ukkonen, @cite{Information and Control} Vol.@: 64, 1985, pp.@: 100--118.
@c From: "Gene Myers" <[email protected]>
@c Date: Wed, 29 Sep 1993 08:27:55 MST
@c Ukkonen should be given credit for also discovering the algorithm used
@c in GNU diff.

@sc{gnu} @command{diff3} was written by Randy Smith.  @sc{gnu}
@command{sdiff} was written by Thomas Lord.  @sc{gnu} @command{cmp}
was written by Torbjorn Granlund and David MacKenzie.

@command{patch} was written mainly by Larry Wall and Paul Eggert;
several @sc{gnu} enhancements were contributed by Wayne Davison and
David MacKenzie.  Parts of this manual are adapted from a manual page
written by Larry Wall, with his permission.

@node Comparison
@chapter What Comparison Means
@cindex introduction

There are several ways to think about the differences between two files.
One way to think of the differences is as a series of lines that were
deleted from, inserted in, or changed in one file to produce the other
file.  @command{diff} compares two files line by line, finds groups of
lines that differ, and reports each group of differing lines.  It can
report the differing lines in several formats, which have different
purposes.

@sc{gnu} @command{diff} can show whether files are different without detailing
the differences.  It also provides ways to suppress certain kinds of
differences that are not important to you.  Most commonly, such
differences are changes in the amount of white space between words or
lines.  @command{diff} also provides ways to suppress differences in
alphabetic case or in lines that match a regular expression that you
provide.  These options can accumulate; for example, you can ignore
changes in both white space and alphabetic case.

Another way to think of the differences between two files is as a
sequence of pairs of bytes that can be either identical or
different.  @command{cmp} reports the differences between two files
byte by byte, instead of line by line.  As a result, it is often
more useful than @command{diff} for comparing binary files.  For text
files, @command{cmp} is useful mainly when you want to know only whether
two files are identical, or whether one file is a prefix of the other.

To illustrate the effect that considering changes byte by byte
can have compared with considering them line by line, think of what
happens if a single newline character is added to the beginning of a
file.  If that file is then compared with an otherwise identical file
that lacks the newline at the beginning, @command{diff} will report that a
blank line has been added to the file, while @command{cmp} will report that
almost every byte of the two files differs.

@command{diff3} normally compares three input files line by line, finds
groups of lines that differ, and reports each group of differing lines.
Its output is designed to make it easy to inspect two different sets of
changes to the same file.

@menu
* Hunks::             Groups of differing lines.
* White Space::       Suppressing differences in white space.
* Blank Lines::       Suppressing differences in blank lines.
* Case Folding::      Suppressing differences in alphabetic case.
* Specified Folding:: Suppressing differences that match regular expressions.
* Brief::             Summarizing which files are different.
* Binary::            Comparing binary files or forcing text comparisons.
@end menu

@node Hunks
@section Hunks
@cindex hunks

When comparing two files, @command{diff} finds sequences of lines common to
both files, interspersed with groups of differing lines called
@dfn{hunks}.  Comparing two identical files yields one sequence of
common lines and no hunks, because no lines differ.  Comparing two
entirely different files yields no common lines and one large hunk that
contains all lines of both files.  In general, there are many ways to
match up lines between two given files.  @command{diff} tries to minimize
the total hunk size by finding large sequences of common lines
interspersed with small hunks of differing lines.

For example, suppose the file @file{F} contains the three lines
@samp{a}, @samp{b}, @samp{c}, and the file @file{G} contains the same
three lines in reverse order @samp{c}, @samp{b}, @samp{a}.  If
@command{diff} finds the line @samp{c} as common, then the command
@samp{diff F G} produces this output:

@example
1,2d0
< a
< b
3a2,3
> b
> a
@end example

@noindent
But if @command{diff} notices the common line @samp{b} instead, it produces
this output:

@example
1c1
< a
---
> c
3c3
< c
---
> a
@end example

@noindent
It is also possible to find @samp{a} as the common line.  @command{diff}
does not always find an optimal matching between the files; it takes
shortcuts to run faster.  But its output is usually close to the
shortest possible.  You can adjust this tradeoff with the
@option{--minimal} option (@pxref{diff Performance}).

@node White Space
@section Suppressing Differences in Blank and Tab Spacing
@cindex blank and tab difference suppression
@cindex tab and blank difference suppression

The @option{-E} and @option{--ignore-tab-expansion} options ignore the
distinction between tabs and spaces on input.  A tab is considered to be
equivalent to the number of spaces to the next tab stop.  @command{diff}
assumes that tab stops are set every 8 print columns.

The @option{-b} and @option{--ignore-space-change} options are stronger.
They ignore white space at line end, and consider all other sequences of
one or more white space characters to be equivalent.  With these
options, @command{diff} considers the following two lines to be equivalent,
where @samp{$} denotes the line end:

@example
Here lyeth  muche rychnesse  in lytell space.   -- John Heywood$
Here lyeth muche rychnesse in lytell space. -- John Heywood   $
@end example

The @option{-w} and @option{--ignore-all-space} options are stronger still.
They ignore difference even if one line has white space where
the other line has none.  @dfn{White space} characters include
tab, newline, vertical tab, form feed, carriage return, and space;
some locales may define additional characters to be white space.
With these options, @command{diff} considers the
following two lines to be equivalent, where @samp{$} denotes the line
end and @samp{^M} denotes a carriage return:

@example
Here lyeth  muche  rychnesse in lytell space.--  John Heywood$
  He relyeth much erychnes  seinly tells pace.  --John Heywood   ^M$
@end example

@node Blank Lines
@section Suppressing Differences in Blank Lines
@cindex blank line difference suppression

The @option{-B} and @option{--ignore-blank-lines} options ignore insertions
or deletions of blank lines.  These options affect only lines
that are completely empty; they do not affect lines that look empty but
contain space or tab characters.  With these options, for example, a
file containing
@example
1.  A point is that which has no part.

2.  A line is breadthless length.
-- Euclid, The Elements, I
@end example
@noindent
is considered identical to a file containing
@example
1.  A point is that which has no part.
2.  A line is breadthless length.


-- Euclid, The Elements, I
@end example

@node Case Folding
@section Suppressing Case Differences
@cindex case difference suppression

@sc{gnu} @command{diff} can treat lower case letters as equivalent to their
upper case counterparts, so that, for example, it considers @samp{Funky
Stuff}, @samp{funky STUFF}, and @samp{fUNKy stuFf} to all be the same.
To request this, use the @option{-i} or @option{--ignore-case} option.

@node Specified Folding
@section Suppressing Lines Matching a Regular Expression
@cindex regular expression suppression

To ignore insertions and deletions of lines that match a
@command{grep}-style regular expression, use the @option{-I
@var{regexp}} or @option{--ignore-matching-lines=@var{regexp}} option.
You should escape
regular expressions that contain shell metacharacters to prevent the
shell from expanding them.  For example, @samp{diff -I '^[[:digit:]]'} ignores
all changes to lines beginning with a digit.

However, @option{-I} only ignores the insertion or deletion of lines that
contain the regular expression if every changed line in the hunk---every
insertion and every deletion---matches the regular expression.  In other
words, for each nonignorable change, @command{diff} prints the complete set
of changes in its vicinity, including the ignorable ones.

You can specify more than one regular expression for lines to ignore by
using more than one @option{-I} option.  @command{diff} tries to match each
line against each regular expression.

@node Brief
@section Summarizing Which Files Differ
@cindex summarizing which files differ
@cindex brief difference reports

When you only want to find out whether files are different, and you
don't care what the differences are, you can use the summary output
format.  In this format, instead of showing the differences between the
files, @command{diff} simply reports whether files differ.  The @option{-q}
and @option{--brief} options select this output format.

This format is especially useful when comparing the contents of two
directories.  It is also much faster than doing the normal line by line
comparisons, because @command{diff} can stop analyzing the files as soon as
it knows that there are any differences.

You can also get a brief indication of whether two files differ by using
@command{cmp}.  For files that are identical, @command{cmp} produces no
output.  When the files differ, by default, @command{cmp} outputs the byte
and line number where the first difference occurs.  You can use
the @option{-s} option to suppress that information, so that @command{cmp}
produces no output and reports whether the files differ using only its
exit status (@pxref{Invoking cmp}).

@c Fix this.
Unlike @command{diff}, @command{cmp} cannot compare directories; it can only
compare two files.

@node Binary
@section Binary Files and Forcing Text Comparisons
@cindex binary file diff
@cindex text versus binary diff

If @command{diff} thinks that either of the two files it is comparing is
binary (a non-text file), it normally treats that pair of files much as
if the summary output format had been selected (@pxref{Brief}), and
reports only that the binary files are different.  This is because line
by line comparisons are usually not meaningful for binary files.

@command{diff} determines whether a file is text or binary by checking the
first few bytes in the file; the exact number of bytes is system
dependent, but it is typically several thousand.  If every byte in
that part of the file is non-null, @command{diff} considers the file to be
text; otherwise it considers the file to be binary.

Sometimes you might want to force @command{diff} to consider files to be
text.  For example, you might be comparing text files that contain
null characters; @command{diff} would erroneously decide that those are
non-text files.  Or you might be comparing documents that are in a
format used by a word processing system that uses null characters to
indicate special formatting.  You can force @command{diff} to consider all
files to be text files, and compare them line by line, by using the
@option{-a} or @option{--text} option.  If the files you compare using this
option do not in fact contain text, they will probably contain few
newline characters, and the @command{diff} output will consist of hunks
showing differences between long lines of whatever characters the files
contain.

You can also force @command{diff} to consider all files to be binary files,
and report only whether they differ (but not how).  Use the
@option{-q} or @option{--brief} option for this.

Differing binary files are considered to cause trouble because the
resulting @command{diff} output does not capture all the differences.
This trouble causes @command{diff} to exit with status 2.  However,
this trouble cannot occur with the @option{--a} or @option{--text}
option, or with the @option{-q} or @option{--brief} option, as these
options both cause @command{diff} to treat binary files like text
files.

In operating systems that distinguish between text and binary files,
@command{diff} normally reads and writes all data as text.  Use the
@option{--binary} option to force @command{diff} to read and write binary
data instead.  This option has no effect on a @sc{posix}-compliant system
like @sc{gnu} or traditional Unix.  However, many personal computer
operating systems represent the end of a line with a carriage return
followed by a newline.  On such systems, @command{diff} normally ignores
these carriage returns on input and generates them at the end of each
output line, but with the @option{--binary} option @command{diff} treats
each carriage return as just another input character, and does not
generate a carriage return at the end of each output line.  This can be
useful when dealing with non-text files that are meant to be
interchanged with @sc{posix}-compliant systems.

The @option{--strip-trailing-cr} causes @command{diff} to treat input
lines that end in carriage return followed by newline as if they end
in plain newline.  This can be useful when comparing text that is
imperfectly imported from many personal computer operating systems.
This option affects how lines are read, which in turn affects how they
are compared and output.

If you want to compare two files byte by byte, you can use the
@command{cmp} program with the @option{-l} option to show the values
of each differing byte in the two files.  With @sc{gnu} @command{cmp},
you can also use the @option{-b} option to show the @sc{ascii}
representation of those bytes.  @xref{Invoking cmp}, for more
information.

If @command{diff3} thinks that any of the files it is comparing is binary
(a non-text file), it normally reports an error, because such
comparisons are usually not useful.  @command{diff3} uses the same test as
@command{diff} to decide whether a file is binary.  As with @command{diff}, if
the input files contain a few non-text bytes but otherwise are like
text files, you can force @command{diff3} to consider all files to be text
files and compare them line by line by using the @option{-a} or
@option{--text} options.

@node Output Formats
@chapter @command{diff} Output Formats
@cindex output formats
@cindex format of @command{diff} output

@command{diff} has several mutually exclusive options for output format.
The following sections describe each format, illustrating how
@command{diff} reports the differences between two sample input files.

@menu
* Sample diff Input:: Sample @command{diff} input files for examples.
* Normal::            Showing differences without surrounding text.
* Context::           Showing differences with the surrounding text.
* Side by Side::      Showing differences in two columns.
* Scripts::           Generating scripts for other programs.
* If-then-else::      Merging files with if-then-else.
@end menu

@node Sample diff Input
@section Two Sample Input Files
@cindex @command{diff} sample input
@cindex sample input for @command{diff}

Here are two sample files that we will use in numerous examples to
illustrate the output of @command{diff} and how various options can change
it.

This is the file @file{lao}:

@example
The Way that can be told of is not the eternal Way;
The name that can be named is not the eternal name.
The Nameless is the origin of Heaven and Earth;
The Named is the mother of all things.
Therefore let there always be non-being,
  so we may see their subtlety,
And let there always be being,
  so we may see their outcome.
The two are the same,
But after they are produced,
  they have different names.
@end example

This is the file @file{tzu}:

@example
The Nameless is the origin of Heaven and Earth;
The named is the mother of all things.

Therefore let there always be non-being,
  so we may see their subtlety,
And let there always be being,
  so we may see their outcome.
The two are the same,
But after they are produced,
  they have different names.
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
@end example

In this example, the first hunk contains just the first two lines of
@file{lao}, the second hunk contains the fourth line of @file{lao}
opposing the second and third lines of @file{tzu}, and the last hunk
contains just the last three lines of @file{tzu}.

@node Normal
@section Showing Differences Without Context
@cindex normal output format
@cindex @samp{<} output format

The ``normal'' @command{diff} output format shows each hunk of differences
without any surrounding context.  Sometimes such output is the clearest
way to see how lines have changed, without the clutter of nearby
unchanged lines (although you can get similar results with the context
or unified formats by using 0 lines of context).  However, this format
is no longer widely used for sending out patches; for that purpose, the
context format (@pxref{Context Format}) and the unified format
(@pxref{Unified Format}) are superior.  Normal format is the default for
compatibility with older versions of @command{diff} and the @sc{posix}
standard.  Use the @option{--normal} option to select this output
format explicitly.

@menu
* Detailed Normal:: A detailed description of normal output format.
* Example Normal::  Sample output in the normal format.
@end menu

@node Detailed Normal
@subsection Detailed Description of Normal Format

The normal output format consists of one or more hunks of differences;
each hunk shows one area where the files differ.  Normal format hunks
look like this:

@example
@var{change-command}
< @var{from-file-line}
< @var{from-file-line}@dots{}
---
> @var{to-file-line}
> @var{to-file-line}@dots{}
@end example

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

@table @samp
@item @var{l}a@var{r}
Add the lines in range @var{r} of the second file after line @var{l} of
the first file.  For example, @samp{8a12,15} means append lines 12--15
of file 2 after line 8 of file 1; or, if changing file 2 into file 1,
delete lines 12--15 of file 2.

@item @var{f}c@var{t}
Replace the lines in range @var{f} of the first file with lines in range
@var{t} of the second file.  This is like a combined add and delete, but
more compact.  For example, @samp{5,7c8,10} means change lines 5--7 of
file 1 to read as lines 8--10 of file 2; or, if changing file 2 into
file 1, change lines 8--10 of file 2 to read as lines 5--7 of file 1.

@item @var{r}d@var{l}
Delete the lines in range @var{r} from the first file; line @var{l} is where
they would have appeared in the second file had they not been deleted.
For example, @samp{5,7d3} means delete lines 5--7 of file 1; or, if
changing file 2 into file 1, append lines 5--7 of file 1 after line 3 of
file 2.
@end table

@node Example Normal
@subsection An Example of Normal Format

Here is the output of the command @samp{diff lao tzu}
(@pxref{Sample diff Input}, for the complete contents of the two files).
Notice that it shows only the lines that are different between the two
files.

@example
1,2d0
< The Way that can be told of is not the eternal Way;
< The name that can be named is not the eternal name.
4c2,3
< The Named is the mother of all things.
---
> The named is the mother of all things.
> 
11a11,13
> They both may be called deep and profound.
> Deeper and more profound,
> The door of all subtleties!
@end example

@node Context
@section Showing Differences in Their Context
@cindex context output format
@cindex @samp{!} output format

Usually, when you are looking at the differences between files, you will
also want to see the parts of the files near the lines that differ, to
help you understand exactly what has changed.  These nearby parts of the
files are called the @dfn{context}.

@sc{gnu} @command{diff} provides two output formats that show context
around the differing lines: @dfn{context format} and @dfn{unified
format}.  It can optionally show in which function or section of the
file the differing lines are found.

If you are distributing new versions of files to other people in the
form of @command{diff} output, you should use one of the output formats
that show context so that they can apply the diffs even if they have
made small changes of their own to the files.  @command{patch} can apply
the diffs in this case by searching in the files for the lines of
context around the differing lines; if those lines are actually a few
lines away from where the diff says they are, @command{patch} can adjust
the line numbers accordingly and still apply the diff correctly.
@xref{Imperfect}, for more information on using @command{patch} to apply
imperfect diffs.

@menu
* Context Format::  An output format that shows surrounding lines.
* Unified Format::  A more compact output format that shows context.
* Sections::        Showing which sections of the files differences are in.
* Alternate Names:: Showing alternate file names in context headers.
@end menu

@node Context Format
@subsection Context Format

The context output format shows several lines of context around the
lines that differ.  It is the standard format for distributing updates
to source code.

To select this output format, use the @option{-C @var{lines}},
@option{--context@r{[}=@var{lines}@r{]}}, or @option{-c} option.  The
argument @var{lines} that some of these options take is the number of
lines of context to show.  If you do not specify @var{lines}, it
defaults to three.  For proper operation, @command{patch} typically needs
at least two lines of context.

@menu
* Detailed Context:: A detailed description of the context output format.
* Example Context::  Sample output in context format.
* Less Context::     Another sample with less context.
@end menu

@node Detailed Context
@subsubsection Detailed Description of Context Format

The context output format starts with a two-line header, which looks
like this:

@example
*** @var{from-file} @var{from-file-modification-time}
--- @var{to-file} @var{to-file-modification time}
@end example

@noindent
@vindex LC_TIME
@cindex time stamp format, context diffs
The time stamp normally looks like @samp{2002-02-21 23:30:39.942229878
-0800} to indicate the date, time with fractional seconds, and time
zone in @uref{ftp://ftp.isi.edu/in-notes/rfc2822.txt, Internet RFC
2822 format}.  However, a traditional time stamp like @samp{Thu Feb 21
23:30:39 2002} is used if the @env{LC_TIME} locale category is either
@samp{C} or @samp{POSIX}.

You can change the header's content with the
@option{--label=@var{label}} option; see @ref{Alternate Names}.

Next come one or more hunks of differences; each hunk shows one area
where the files differ.  Context format hunks look like this:

@example
***************
*** @var{from-file-line-range} ****
  @var{from-file-line}
  @var{from-file-line}@dots{}
--- @var{to-file-line-range} ----
  @var{to-file-line}
  @var{to-file-line}@dots{}
@end example

The lines of context around the lines that differ start with two space
characters.  The lines that differ between the two files start with one
of the following indicator characters, followed by a space character:

@table @samp
@item !
A line that is part of a group of one or more lines that changed between
the two files.  There is a corresponding group of lines marked with
@samp{!} in the part of this hunk for the other file.

@item +
An ``inserted'' line in the second file that corresponds to nothing in
the first file.

@item -
A ``deleted'' line in the first file that corresponds to nothing in the
second file.
@end table

If all of the changes in a hunk are insertions, the lines of
@var{from-file} are omitted.  If all of the changes are deletions, the
lines of @var{to-file} are omitted.

@node Example Context
@subsubsection An Example of Context Format

Here is the output of @samp{diff -c lao tzu} (@pxref{Sample diff Input},
for the complete contents of the two files).  Notice that up to three
lines that are not different are shown around each line that is
different; they are the context lines.  Also notice that the first two
hunks have run together, because their contents overlap.

@example
*** lao 2002-02-21 23:30:39.942229878 -0800
--- tzu 2002-02-21 23:30:50.442260588 -0800
***************
*** 1,7 ****
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
  The Nameless is the origin of Heaven and Earth;
! The Named is the mother of all things.
  Therefore let there always be non-being,
    so we may see their subtlety,
  And let there always be being,
--- 1,6 ----
  The Nameless is the origin of Heaven and Earth;
! The named is the mother of all things.
! 
  Therefore let there always be non-being,
    so we may see their subtlety,
  And let there always be being,
***************
*** 9,11 ****
--- 8,13 ----
  The two are the same,
  But after they are produced,
    they have different names.
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
@end example

@node Less Context
@subsubsection An Example of Context Format with Less Context

Here is the output of @samp{diff -C 1 lao tzu} (@pxref{Sample diff
Input}, for the complete contents of the two files).  Notice that at
most one context line is reported here.

@example
*** lao 2002-02-21 23:30:39.942229878 -0800
--- tzu 2002-02-21 23:30:50.442260588 -0800
***************
*** 1,5 ****
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
  The Nameless is the origin of Heaven and Earth;
! The Named is the mother of all things.
  Therefore let there always be non-being,
--- 1,4 ----
  The Nameless is the origin of Heaven and Earth;
! The named is the mother of all things.
! 
  Therefore let there always be non-being,
***************
*** 11 ****
--- 10,13 ----
    they have different names.
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
@end example

@node Unified Format
@subsection Unified Format
@cindex unified output format
@cindex @samp{+-} output format

The unified output format is a variation on the context format that is
more compact because it omits redundant context lines.  To select this
output format, use the @option{-U @var{lines}},
@option{--unified@r{[}=@var{lines}@r{]}}, or @option{-u}
option.  The argument @var{lines} is the number of lines of context to
show.  When it is not given, it defaults to three.

At present, only @sc{gnu} @command{diff} can produce this format and
only @sc{gnu} @command{patch} can automatically apply diffs in this
format.  For proper operation, @command{patch} typically needs at
least three lines of context.

@menu
* Detailed Unified:: A detailed description of unified format.
* Example Unified::  Sample output in unified format.
@end menu

@node Detailed Unified
@subsubsection Detailed Description of Unified Format

The unified output format starts with a two-line header, which looks
like this:

@example
--- @var{from-file} @var{from-file-modification-time}
+++ @var{to-file} @var{to-file-modification-time}
@end example

@noindent
@cindex time stamp format, unified diffs
The time stamp looks like @samp{2002-02-21 23:30:39.942229878 -0800}
to indicate the date, time with fractional seconds, and time zone.

You can change the header's content with the
@option{--label=@var{label}} option; see @xref{Alternate Names}.

Next come one or more hunks of differences; each hunk shows one area
where the files differ.  Unified format hunks look like this:

@example
@@@@ @var{from-file-range} @var{to-file-range} @@@@
 @var{line-from-either-file}
 @var{line-from-either-file}@dots{}
@end example

The lines common to both files begin with a space character.  The lines
that actually differ between the two files have one of the following
indicator characters in the left print column:

@table @samp
@item +
A line was added here to the first file.

@item -
A line was removed here from the first file.
@end table

@node Example Unified
@subsubsection An Example of Unified Format

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

@example
--- lao 2002-02-21 23:30:39.942229878 -0800
+++ tzu 2002-02-21 23:30:50.442260588 -0800
@@@@ -1,7 +1,6 @@@@
-The Way that can be told of is not the eternal Way;
-The name that can be named is not the eternal name.
 The Nameless is the origin of Heaven and Earth;
-The Named is the mother of all things.
+The named is the mother of all things.
+
 Therefore let there always be non-being,
   so we may see their subtlety,
 And let there always be being,
@@@@ -9,3 +8,6 @@@@
 The two are the same,
 But after they are produced,
   they have different names.
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
@end example

@node Sections
@subsection Showing Which Sections Differences Are in
@cindex headings
@cindex section headings

Sometimes you might want to know which part of the files each change
falls in.  If the files are source code, this could mean which function
was changed.  If the files are documents, it could mean which chapter or
appendix was changed.  @sc{gnu} @command{diff} can show this by displaying the
nearest section heading line that precedes the differing lines.  Which
lines are ``section headings'' is determined by a regular expression.

@menu
* Specified Headings::  Showing headings that match regular expressions.
* C Function Headings:: Showing headings of C functions.
@end menu

@node Specified Headings
@subsubsection Showing Lines That Match Regular Expressions
@cindex specified headings
@cindex regular expression matching headings

To show in which sections differences occur for files that are not
source code for C or similar languages, use the @option{-F @var{regexp}}
or @option{--show-function-line=@var{regexp}} option.  @command{diff}
considers lines that match the @command{grep}-style regular expression
@var{regexp} to be the beginning
of a section of the file.  Here are suggested regular expressions for
some common languages:

@c Please add to this list, e.g. Fortran, Pascal, Perl, Python.
@table @samp
@item ^[[:alpha:]$_]
C, C++, Prolog
@item ^(
Lisp
@item ^@@node
Texinfo
@end table

This option does not automatically select an output format; in order to
use it, you must select the context format (@pxref{Context Format}) or
unified format (@pxref{Unified Format}).  In other output formats it
has no effect.

The @option{-F} and @option{--show-function-line} options find the nearest
unchanged line that precedes each hunk of differences and matches the
given regular expression.  Then they add that line to the end of the
line of asterisks in the context format, or to the @samp{@@@@} line in
unified format.  If no matching line exists, they leave the output for
that hunk unchanged.  If that line is more than 40 characters long, they
output only the first 40 characters.  You can specify more than one
regular expression for such lines; @command{diff} tries to match each line
against each regular expression, starting with the last one given.  This
means that you can use @option{-p} and @option{-F} together, if you wish.

@node C Function Headings
@subsubsection Showing C Function Headings
@cindex C function headings
@cindex function headings, C

To show in which functions differences occur for C and similar
languages, you can use the @option{-p} or @option{--show-c-function} option.
This option automatically defaults to the context output format
(@pxref{Context Format}), with the default number of lines of context.
You can override that number with @option{-C @var{lines}} elsewhere in the
command line.  You can override both the format and the number with
@option{-U @var{lines}} elsewhere in the command line.

The @option{-p} and @option{--show-c-function} options are equivalent to
@option{-F '^[[:alpha:]$_]'} if the unified format is specified, otherwise
@option{-c -F '^[[:alpha:]$_]'} (@pxref{Specified Headings}).  @sc{gnu}
@command{diff} provides them for the sake of convenience.

@node Alternate Names
@subsection Showing Alternate File Names
@cindex alternate file names
@cindex file name alternates

If you are comparing two files that have meaningless or uninformative
names, you might want @command{diff} to show alternate names in the header
of the context and unified output formats.  To do this, use the
@option{--label=@var{label}} option.  The first time
you give this option, its argument replaces the name and date of the
first file in the header; the second time, its argument replaces the
name and date of the second file.  If you give this option more than
twice, @command{diff} reports an error.  The @option{--label} option does not
affect the file names in the @command{pr} header when the @option{-l} or
@option{--paginate} option is used (@pxref{Pagination}).

Here are the first two lines of the output from @samp{diff -C 2
--label=original --label=modified lao tzu}:

@example
*** original
--- modified
@end example

@node Side by Side
@section Showing Differences Side by Side
@cindex side by side
@cindex two-column output
@cindex columnar output

@command{diff} can produce a side by side difference listing of two files.
The files are listed in two columns with a gutter between them.  The
gutter contains one of the following markers:

@table @asis
@item white space
The corresponding lines are in common.  That is, either the lines are
identical, or the difference is ignored because of one of the
@option{--ignore} options (@pxref{White Space}).

@item @samp{|}
The corresponding lines differ, and they are either both complete
or both incomplete.

@item @samp{<}
The files differ and only the first file contains the line.

@item @samp{>}
The files differ and only the second file contains the line.

@item @samp{(}
Only the first file contains the line, but the difference is ignored.

@item @samp{)}
Only the second file contains the line, but the difference is ignored.

@item @samp{\}
The corresponding lines differ, and only the first line is incomplete.

@item @samp{/}
The corresponding lines differ, and only the second line is incomplete.
@end table

Normally, an output line is incomplete if and only if the lines that it
contains are incomplete; @xref{Incomplete Lines}.  However, when an
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 @command{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
@subsection Controlling Side by Side Format
@cindex side by side format

The @option{-y} or @option{--side-by-side} option selects side by side
format.  Because side by side output lines contain two input lines, the
output is wider than usual: normally 130 print columns, which can fit
onto a traditional printer line.  You can set the width of the output
with the @option{-W @var{columns}} or @option{--width=@var{columns}}
option.  The output is split into two halves of equal width, 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 @option{--left-column} option prints only the left column of two
common lines.  The @option{--suppress-common-lines} option suppresses
common lines entirely.

@node Example 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
@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 @command{diff} to produce commands for @command{ed}.
* Forward ed:: Making forward @command{ed} scripts.
* RCS::        A special @command{diff} output format used by @sc{rcs}.
@end menu

@node ed Scripts
@subsection @command{ed} Scripts
@cindex @command{ed} script output format

@command{diff} can produce commands that direct the @command{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 @command{patch}, it is almost obsolete.  Use the
@option{-e} or @option{--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 @command{ed} format.
* Example ed::  A sample @command{ed} script.
@end menu

@node Detailed ed
@subsubsection Detailed Description of @command{ed} Format

The @command{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
@command{ed} interprets line numbers in succeeding commands.  @command{ed}
format hunks look like this:

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

Because @command{ed} uses a single period on a line to indicate the end of
input, @sc{gnu} @command{diff} protects lines of changes that contain a single
period on a line by writing two periods instead, then writing a
subsequent @command{ed} command to change the two periods into one.  The
@command{ed} format cannot represent an incomplete line, so if the second
file ends in a changed incomplete line, @command{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