Comparing and Merging Files with GNU diff and patch Notes

When comparing two files, diff finds sequences of lines common to both files, interspersed with groups of differing lines called hunks.

The ‘-E’ and ‘–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. diff assumes that tab stops are set every 8 print columns.

The ‘-b’ and ‘–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.

diff considers the following two lines to be equivalent, where ‘$’ denotes the line end:

Here lyeth muche rychnesse in lytell space. – John Heywood$
Here lyeth muche rychnesse in lytell space. – John Heywood $

The ‘-w’ and ‘–ignore-all-space’ options are stronger still. They ignore difference even if one line has white space where the other line has none.

diff considers the following two lines to be equivalent, where ‘$’ denotes the line end and ‘^M’ denotes a carriage return:

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

The ‘-B’ and ‘–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.

To request this, use the ‘-i’ or ‘–ignore-case’ option.

To ignore insertions and deletions of lines that match a grep-style regular expression, use the ‘-I regexp’ or ‘–ignore-matching-lines=regexp’ option. For example, ‘diff -I ’^[[:digit:]]’’ ignores all changes to lines beginning with a digit.

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

diff simply reports whether files differ. The ‘-q’ and ‘–brief’ options select this output format.

Unlike diff, cmp cannot compare directories; it can only compare two files.

You can force diff to consider all files to be text files, and compare them line by line, by using the ‘-a’ or ‘–text’ option.

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

Use the ‘–binary’ option to force diff to read and write binary data instead.

The ‘–strip-trailing-cr’ causes diff to treat input lines that end in carriage return followed by newline as if they end in plain newline

All line numbers are the original line numbers in each file. The types of change commands are:

• ‘lar’: Add the lines in range r of the second file after line l of the first file. For example, ‘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.
• ‘fct’: Replace the lines in range f of the first file with lines in range t of the second file. This is like a combined add and delete, but more compact. For example, ‘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.
• ‘rdl’ Delete the lines in range r from the first file; line l is where they would have appeared in the second file had they not been deleted. For example, ‘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.

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 context.

gnu diff provides two output formats that show context around the differing lines: context format and unified format.

To select this output format, use the ‘-C lines’, ‘–context[=lines]’, or ‘-c’ option. The argument lines that some of these options take is the number of lines of context to show.

To select this output format, use the ‘-U lines’, ‘–unified[=lines]’, or ‘-u’ option. The argument lines is the number of lines of context to show.

use the ‘-F regexp’ or ‘–show-function-line=regexp’ option.

Here are suggested regular expressions for some common languages:

‘^[[:alpha:]$_]’
   C, C++, Prolog
‘^(’   Lisp
‘^@node’    Texinfo

The ‘-F’ and ‘–show-function-line’ options find the nearest unchanged line that precedes each hunk of differences and matches the given regular expression.

To show in which functions differences occur for C and similar languages, you can use the ‘-p’ or ‘–show-c-function’ option.

Here are the first two lines of the output from ‘diff -C 2 –label=original –label=modified lao tzu’:

*** original
--- modified

The gutter contains one of the following markers:

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 ‘–ignore’ options (see Section 1.2 [White Space],
page 6).

‘|’ The corresponding lines differ, and they are either both complete
or both incomplete.

‘<’ The files differ and only the first file contains the line.
‘>’ The files differ and only the second file contains the line.
‘(’ Only the first file contains the line, but the difference is
ignored.
‘)’ Only the second file contains the line, but the difference is
ignored.
‘\’ The corresponding lines differ, and only the first line is incomplete.
‘/’ The corresponding lines differ, and only the second line is
incomplete.

To merge two files, use diff with the ‘-D name’ or ‘–ifdef=name’ option. The argument name is the C preprocessor identifier to use in the #ifdef and #ifndef directives.

The first way is to have diff convert all tabs into the correct number of spaces before outputting them; select this method with the ‘-t’ or ‘–expand-tabs’ option.

The ‘-l’ and ‘–paginate’ options do this by sending the diff output through the pr program.

The output formats listed here are the only ones that patch can understand. ‘-c’‘–context’ context diff.

‘-e’‘–ed’ ed script.

‘-n’‘–normal’ normal diff.

‘-u’‘–unified’ unified diff.

Sometimes people run diff with the new file first instead of second. This creates a diff that is “reversed”. To apply such patches, give patch the ‘-R’ or ‘–reverse’ option.

The ‘-d directory’ or ‘–directory=directory’ option to patch makes directory directory the current directory for interpreting both file names in the patch file, and file names given as arguments to other options

Sometimes the file names given in a patch contain leading directories, but you keep your files in a directory different from the one given in the patch. In those cases, you can use the ‘-pnumber’ or ‘--strip=number’ option to set the file name strip count to number. The strip count tells patch how many slashes, along with the directory names between them, to strip from the front of file names. A sequence of one or more adjacent slashes is counted as a single slash. By default, patch strips off all leading directories, leaving just the base file names.

For example, suppose the file name in the patch file is ‘/gnu/src/emacs/etc/NEWS’. Using ‘-p0’ gives the entire file name unmodified, ‘-p1’ gives ‘gnu/src/emacs/etc/NEWS’ (no leading slash), ‘-p4’ gives ‘etc/NEWS’, and not specifying ‘-p’ at all gives ‘NEWS’.

To generate the patch, use the command ‘diff -Naur old new’ where old and new identify the old and new directories. The names old and new should not contain any slashes. The ‘-N’ option lets the patch create and remove files; ‘-a’ lets the patch update non-text files; ‘-u’ generates useful time stamps and enough context; and ‘-r’ lets the patch update subdirectories. Here is an example command, using Bourne shell syntax:

diff -Naur gcc-3.0.3 gcc-3.0.4

Brackets ([ and ]) indicate that an option takes an optional argument.

‘-a’
‘–text’ Treat all files as text and compare them line-by-line, even
if they do not seem to be text. See Section 1.7 [Binary],
page 8.

‘-b’
‘–ignore-space-change’
Ignore changes in amount of white space. See Section 1.2
[White Space], page 6.

‘-B’
‘–ignore-blank-lines’
Ignore changes that just insert or delete blank lines. See
Section 1.3 [Blank Lines], page 7.
‘–binary’ Read and write data in binary mode. See Section
1.7[Binary],page 8.

‘-c’ Use the context output format, showing three lines of context.
See Section 2.3.1 [Context Format], page 14.

‘-C lines’
‘–context[=lines]’
Use the context output format, showing lines (an integer)
lines of context, or three if lines is not given. See Section
2.3.1 [Context Format], page 14. For proper operation,
patch typically needs at least two lines of context.
On older systems, diff supports an obsolete option ‘-lines’
that has effect when combined with ‘-c’ or ‘-p’. posix
1003.1-2001 (see Chapter 17 [Standards conformance],
page 97) does not allow this; use ‘-C lines’ instead.

‘–changed-group-format=format’
Use format to output a line group containing differing lines
from both files in if-then-else format. See Section 2.6.1 [Line
Group Formats], page 24.

‘-d’
‘–minimal’
Change the algorithm perhaps find a smaller set of changes.
This makes diff slower (sometimes much slower). See Chapter
6 [diff Performance], page 39.

‘-D name’
‘–ifdef=name’
Make merged ‘#ifdef’ format output, conditional on the
preprocessor macro name. See Section 2.6 [If-then-else],
page 24.

‘-e’
‘–ed’ Make output that is a valid ed script. See Section 2.5.1 [ed
Scripts], page 21.

‘-E’
‘–ignore-tab-expansion’
Ignore changes due to tab expansion. See Section 1.2 [White
Space], page 6.

‘-f’
‘–forward-ed’
Make output that looks vaguely like an ed script but has
changes in the order they appear in the file. See Section 2.5.2
[Forward ed], page 23.

‘-F regexp’
‘–show-function-line=regexp’
In context and unified format, for each hunk of differences,
show some of the last preceding line that matches regexp.
See Section 2.3.3.1 [Specified Headings], page 18.

‘–from-file=file’
Compare file to each operand; file may be a directory.

‘–help’ Output a summary of usage and then exit.

‘–horizon-lines=lines’
Do not discard the last lines lines of the common prefix and
the first lines lines of the common suffix. See Chapter 6 [diff
Performance], page 39.

‘-i’
‘–ignore-case’
Ignore changes in case; consider upper- and lower-case letters
equivalent. See Section 1.4 [Case Folding], page 7.

‘-I regexp’
‘–ignore-matching-lines=regexp’
Ignore changes that just insert or delete lines that match
regexp. See Section 1.5 [Specified Folding], page 7.

‘–ignore-file-name-case’
Ignore case when comparing file names during recursive comparison.
See Chapter 4 [Comparing Directories], page 35.

‘-l’
‘–paginate’
Pass the output through pr to paginate it. See Section 5.2
[Pagination], page 37.

‘–label=label’
Use label instead of the file name in the context format (see
Section 2.3.1 [Context Format], page 14) and unified format(see Section 2.3.2 [Unified Format], page 16) headers. See
Section 2.5.3 [RCS], page 23.

‘–left-column’
Print only the left column of two common lines in side by
side format. See Section 2.4.1 [Side by Side Format], page 20.

‘–line-format=format’
Use format to output all input lines in if-then-else format.
See Section 2.6.2 [Line Formats], page 27.

‘-n’
‘–rcs’ Output rcs-format diffs; like ‘-f’ except that each command
specifies the number of lines affected. See Section 2.5.3
[RCS], page 23.

‘-N’
‘–new-file’
In directory comparison, if a file is found in only one directory,
treat it as present but empty in the other directory.
See Chapter 4 [Comparing Directories], page 35.

‘–new-group-format=format’
Use format to output a group of lines taken from just the
second file in if-then-else format. See Section 2.6.1 [Line
Group Formats], page 24.

‘–new-line-format=format’
Use format to output a line taken from just the second
file in if-then-else format. See Section 2.6.2 [Line Formats],
page 27.

‘–old-group-format=format’
Use format to output a group of lines taken from just the
first file in if-then-else format. See Section 2.6.1 [Line Group
Formats], page 24.

‘–old-line-format=format’
Use format to output a line taken from just the first file in ifthen-
else format. See Section 2.6.2 [Line Formats], page 27

‘-p’
‘–show-c-function’
Show which C function each change is in. See Section 2.3.3.2
[C Function Headings], page 19.

‘-q’
‘–brief’ Report only whether the files differ, not the details of the
differences. See Section 1.6 [Brief], page 8.

‘-r’
‘–recursive’
When comparing directories, recursively compare any subdirectories
found. See Chapter 4 [Comparing Directories],
page 35.

‘-s’
‘–report-identical-files’
Report when two files are the same. See Chapter 4 [Comparing
Directories], page 35.

‘-S file’
‘–starting-file=file’
When comparing directories, start with the file file. This is
used for resuming an aborted comparison. See Chapter 4
[Comparing Directories], page 35.

‘–speed-large-files’
Use heuristics to speed handling of large files that have numerous
scattered small changes. See Chapter 6 [diff Performance],
page 39.

‘–strip-trailing-cr’
Strip any trailing carriage return at the end of an input line.
See Section 1.7 [Binary], page 8.

‘–suppress-common-lines’
Do not print common lines in side by side format. See Section
2.4.1 [Side by Side Format], page 20.

‘-t’
‘–expand-tabs’
Expand tabs to spaces in the output, to preserve the alignment
of tabs in the input files. See Section 5.1 [Tabs],
page 37.

‘-T’
‘–initial-tab’
Output a tab rather than a space before the text of a line in
normal or context format. This causes the alignment of tabs
in the line to look normal. See Section 5.1 [Tabs], page 37.

‘–to-file=file’
Compare each operand to file; file may be a directory.
‘-u’ Use the unified output format, showing three lines of context.
See Section 2.3.2 [Unified Format], page 16.

‘–unchanged-group-format=format’
Use format to output a group of common lines taken from
both files in if-then-else format. See Section 2.6.1 [Line
Group Formats], page 24.

‘–unchanged-line-format=format’
Use format to output a line common to both files in if-thenelse
format. See Section 2.6.2 [Line Formats], page 27.

‘–unidirectional-new-file’
When comparing directories, if a file appears only in the
second directory of the two, treat it as present but empty in
the other. See Chapter 4 [Comparing Directories], page 35.

‘-U lines’
‘–unified[=lines]’
Use the unified output format, showing lines (an integer)
lines of context, or three if lines is not given. See Section
2.3.2 [Unified Format], page 16. For proper operation,
patch typically needs at least two lines of context.
On older systems, diff supports an obsolete option ‘-lines’
that has effect when combined with ‘-u’. posix 1003.1-2001
(see Chapter 17 [Standards conformance], page 97) does not
allow this; use ‘-U lines’ instead.

‘-v’
‘–version’
Output version information and then exit.

‘-w’
‘–ignore-all-space’
Ignore white space when comparing lines. See Section 1.2
[White Space], page 6.

‘-W columns’
‘–width=columns’
Output at most columns (default 130) print columns per
line in side by side format. See Section 2.4.1 [Side by Side
Format], page 20.

‘-x pattern’
‘–exclude=pattern’
When comparing directories, ignore files and subdirectories
whose basenames match pattern. See Chapter 4 [Comparing
Directories], page 35.

‘-X file’
‘–exclude-from=file’
When comparing directories, ignore files and subdirectories
whose basenames match any pattern contained in file. See
Chapter 4 [Comparing Directories], page 35.

‘-y’
‘–side-by-side’
Use the side by side output format. See Section 2.4.1 [Side
by Side Format], page 20.

Multiple single-letter options that do not take an argument can be combined into a single command line argument with only one dash.

‘-b’
‘–backup’ Back up the original contents of each file, even if backups
would normally not be made. See Section 10.8 [Backups],
page 60.

‘-B prefix’
‘–prefix=prefix’
Prepend prefix to backup file names. See Section 10.9
[Backup Names], page 60.

‘–backup-if-mismatch’
Back up the original contents of each file if the patch does not
exactly match the file. This is the default behavior when not
conforming to posix. See Section 10.8 [Backups], page 60.

‘–binary’ Read and write all files in binary mode, except for standard
output and ‘/dev/tty’. This option has no effect on posixconforming
systems like gnu/Linux. On systems where this
option makes a difference, the patch should be generated by
‘diff -a –binary’. See Section 1.7 [Binary], page 8.

‘-c’
‘–context’
Interpret the patch file as a context diff. See Section 10.1
[patch Input], page 53.

‘-d directory’
‘–directory=directory’
Make directory directory the current directory for interpreting
both file names in the patch file, and file names given as
arguments to other options. See Section 10.7 [patch Directories],
page 59.

‘-D name’
‘–ifdef=name’
Make merged if-then-else output using name. See Section 2.6
[If-then-else], page 24.

‘–dry-run’
Print the results of applying the patches without actually
changing any files. See Section 10.3.4 [Dry Runs], page 56.

‘-e’
‘–ed’ Interpret the patch file as an ed script. See Section 10.1
[patch Input], page 53.

‘-E’
‘–remove-empty-files’
Remove output files that are empty after the patches have
been applied. See Section 10.4 [Creating and Removing],
page 57.

‘-f’
‘–force’ Assume that the user knows exactly what he or she is doing,
and do not ask any questions. See Section 10.11 [patch
Messages], page 61.

‘-F lines’
‘–fuzz=lines’
Set the maximum fuzz factor to lines. See Section 10.3.3
[Inexact], page 55.

‘-g num’
‘–get=num’
If num is positive, get input files from a revision control system
as necessary; if zero, do not get the files; if negative, ask
the user whether to get the files. See Section 10.2 [Revision
Control], page 54.

‘–help’ Output a summary of usage and then exit.

‘-i patchfile’
‘–input=patchfile’
Read the patch from patchfile rather than from standard
input. See Section 15.1 [patch Options], page 87.

‘-l’
‘–ignore-white-space’
Let any sequence of blanks (spaces or tabs) in the patch file
match any sequence of blanks in the input file. See Section
10.3.1 [Changed White Space], page 54.

‘-n’
‘–normal’ Interpret the patch file as a normal diff. See Section 10.1
[patch Input], page 53.

‘-N’
‘–forward’
Ignore patches that patch thinks are reversed or already
applied. See also ‘-R’. See Section 10.3.2 [Reversed Patches],
page 55.

‘–no-backup-if-mismatch’
Do not back up the original contents of files. This is the
default behavior when conforming to posix. See Section 10.8
[Backups], page 60.

‘-o file’
‘–output=file’
Use file as the output file name. See Section 15.1 [patch
Options], page 87.

‘-pnumber’
‘–strip=number’
Set the file name strip count to number. See Section 10.7
[patch Directories], page 59.

‘–posix’ Conform to posix, as if the POSIXLY_CORRECT environment
variable had been set. See Section 10.12 [patch and POSIX],
page 63.

‘–quoting-style=word’
Use style word to quote names in diagnostics, as if the
QUOTING_STYLE environment variable had been set to word.
See Section 10.11.3 [patch Quoting Style], page 62.

‘-r reject-file’
‘–reject-file=reject-file’
Use reject-file as the reject file name. See Section 10.10
[Reject Names], page 61.

‘-R’
‘–reverse’
Assume that this patch was created with the old and
new files swapped. See Section 10.3.2 [Reversed Patches],
page 55.

‘-s’
‘–quiet’
‘–silent’ Work silently unless an error occurs. See Section 10.11 [patch
Messages], page 61.

‘-t’
‘–batch’ Do not ask any questions. See Section 10.11 [patch
Messages], page 61.

‘-T’
‘–set-time’
Set the modification and access times of patched files from
time stamps given in context diff headers, assuming that
the context diff headers use local time. See Section 10.5
[Patching Time Stamps], page 57.

‘-u’
‘–unified’
Interpret the patch file as a unified diff. See Section 10.1
[patch Input], page 53.

‘-v’
‘–version’
Output version information and then exit.

‘-V backup-style’
‘–version=control=backup-style’
Select the naming convention for backup file names. See
Section 10.9 [Backup Names], page 60.

‘–verbose’
Print more diagnostics than usual. See Section 10.11 [patch
Messages], page 61.

‘-x number’
‘–debug=number’
Set internal debugging flags. Of interest only to patch patchers.

‘-Y prefix’
‘–basename-prefix=prefix’
Prepend prefix to base names of backup files. See Section
10.9 [Backup Names], page 60.

‘-z suffix’
‘–suffix=suffix’
Use suffix as the backup extension instead of ‘.orig’ or ‘~’.
See Section 10.9 [Backup Names], page 60.

‘-Z’
‘–set-utc’
Set the modification and access times of patched files from
time stamps given in context diff headers, assuming that the
context diff headers use utc. See Section 10.5 [Patching
Time Stamps], page 57.

You should quote format, because it typically contains shell metacharacters. ‘–old-group-format=format’ These line groups are hunks containing only lines from the first file. The default old group format is the same as the changed group format if it is specified; otherwise it is a format that outputs the line group as-is.

‘–new-group-format=format’ These line groups are hunks containing only lines from the second file. The default new group format is same as the changed group format if it is specified; otherwise it is a format that outputs the line group as-is.

‘–changed-group-format=format’ These line groups are hunks containing lines from both files. The default changed group format is the concatenation of the old and new group formats.

‘–unchanged-group-format=format’ These line groups contain lines common to both files. The default unchanged group format is a format that outputs the line group as-is.

In a line group format, ordinary characters represent themselves; conversion specifications start with ‘%’ and have one of the following forms. ‘%<’ stands for the lines from the first file, including the trailing newline. Each line is formatted according to the old line format (see Section 2.6.2 [Line Formats], page 27). ‘%>’ stands for the lines from the second file, including the trailing newline. Each line is formatted according to the new line format. ‘%=’ stands for the lines common to both files, including the trailing newline. Each line is formatted according to the unchanged line format. ‘%%’ stands for ‘%’. ‘%c’C’’ where C is a single character, stands for C. C may not be a backslash or an apostrophe. For example, ‘%c’:’’ stands for a colon, even inside the then-part of an if-then-else format, which a colon would normally terminate. ‘%c’\O’’ where O is a string of 1, 2, or 3 octal digits, stands for the character with octal code O. For example, ‘%c’\0’’ stands for a null character.

‘Fn’ where F is a printf conversion specification and n is one of the following letters, stands for n’s value formatted with F. ‘e’ The line number of the line just before the group in the old file. ‘f’ The line number of the first line in the group in the old file; equals e + 1.

‘l’ The line number of the last line in the group in the old file. ‘m’ The line number of the line just after the group in the old file; equals l + 1. ‘n’ The number of lines in the group in the old file; equals l - f + 1. ‘E,F,L,M,N ’ Likewise, for lines in the new file.