The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

 NAME

diff - compare two files

 SYNOPSIS



diff [-c| -e| -f| -C n][-br] file1 file2

 DESCRIPTION

The diff utility will compare the contents of file1 and file2 and write to standard output a list of changes necessary to convert file1 into file2. This list should be minimal. No output will be produced if the files are identical.

 OPTIONS

The diff utility supports the XBD specification, Utility Syntax Guidelines  .

The following options are supported:

-b
Cause any amount of white space at the end of a line to be treated as a single newline character (that is, the white-space characters preceding the newline character are ignored) and other strings of white-space characters, not including newline characters, to compare equal.
-c
Produce output in a form that provides three lines of context.
-C n
Produce output in a form that provides n lines of context (where n will be interpreted as a positive decimal integer).
-e
Produce output in a form suitable as input for the ed utility, which can then be used to convert file1 into file2.
-f
Produce output in an alternative form, similar in format to -e, but unsuitable as input for the ed utility, and in the opposite order.
-r
Apply diff recursively to files and directories of the same name when file1 and file2 are both directories.

 OPERANDS

The following operands are supported:
file1
file2
A pathname of a file be compared. If either the file1 or file2 operand is "-", the standard input will be used in its place.

If both file1 and file2 are directories, diff will not compare block special files, character special files or FIFO special files to any files and will not compare regular files to directories. The system documentation will specify the behaviour of diff on implementation-dependent file types not specified by the XSH specification when found in directories. Further details are as specified in Diff Directory Comparison Format .

If only one of file1 and file2 is a directory, diff will be applied to the non-directory file and the file contained in the directory file with a filename that is the same as the last component of the non-directory file.

 STDIN

The standard input will be used only if one of the file1 or file2 operands references standard input. See the INPUT FILES section.

 INPUT FILES

The input files must be text files.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of diff:
LANG
Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.
LC_ALL
If set to a non-empty string value, override the values of all the other internationalisation variables.
LC_CTYPE
Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files).
LC_MESSAGES
Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output.
LC_TIME
Determine the locale for affecting the format of file timestamps written with the -C and -c options.
NLSPATH
Determine the location of message catalogues for the processing of LC_MESSAGES .
TZ
Determine the locale for affecting the timezone used for calculating file timestamps written with the -C and -c options.

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

 Diff Directory Comparison Format
If both file1 and file2 are directories, the following output formats will be used.

In the POSIX locale, each file that is present in only one directory will be reported using the following format:

"Only in %s: %s\n", <directory pathname>, <filename>

In the POSIX locale, subdirectories that are common to the two directories may be reported with the following format:

"Common subdirectories: %s and %s\n", <directory1 pathname>,
<directory2 pathname>

For each file common to the two directories if the two files are not to be compared, the following format shall be used in the POSIX locale:

"File %s is a %s while file %s is a %s\n", <directory1 pathname>,
<file type of directory1 pathname>,
<directory2 pathname>,
<file type of directory2 pathname>

For each file common to the two directories, if the files are to be compared and are identical, no output shall be written. If the two files differ, the following format shall be written:

"diff %s %s %s\n", <diff_options>, <filename1>, <filename2>

where <diff_options> are the options as specified on the command line. Depending on these options, one of the following output formats will be used to write the differences.

All directory pathnames listed in this section will be relative to the original command line arguments. All other names of files listed in this section will be filenames (pathname components).

 Diff Default Output Format
The default (without -e, -f, -c or -C options) diff utility output contains lines of these forms:

"%da%d\n", <num1>, <num2>

"%da%d,%d\n", <num1>, <num2>, <num3>

"%dd%d\n", <num1>, <num2>

"%d,%dd%d\n", <num1>, <num2>, <num3>

"%dc%d\n", <num1>, <num2>

"%d,%dc%d\n", <num1>, <num2>, <num3>

"%dc%d,%d\n", <num1>, <num2>, <num3>

"%d,%dc%d,%d\n", <num1>, <num2>, <num3>, <num4>

These lines resemble ed subcommands to convert file1 into file2. The line numbers before the action letters pertain to file1; those after pertain to file2. Thus, by exchanging a for d and reading the line in reverse order, one can also determine how to convert file2 into file1. As in ed, identical pairs (where num1 = num2) are abbreviated as a single number.

Following each of these lines, diff will write to standard output all lines affected in the first file using the format:

"<%s", <line>

and all lines affected in the second file using the format:

">%s", <line>

If there are lines affected in both file1 and file2 (as with the c subcommand), the changes are separated with a line consisting of three hyphens:


"---\n"

 Diff -e Output Format
With the -e option, a script will be produced that will, when provided as input to ed, along with an appended w (write) command, convert file1 into file2. Only the a (append), c (change), d (delete), i (insert), and s (substitute) commands of ed will be used in this script. Text lines, except those consisting of the single character period (.), will be output as they appear in the file.
 Diff -f Output Format
With the -f option, an alternative format of script will be produced. It will be similar to that produced by -e, with the following differences:

  1. It will be expressed in reverse sequence; the output of -e will order changes from the end of the file to the beginning; the -f from beginning to end.

  2. The command form <lines> <command-letter> used by -e will be reversed. For example, 10c with -e would be c10 with -f.

  3. The form used for ranges of line numbers will be space-character-separated, rather than comma-separated.

 Diff -c or -C Output Format
With the -c or -C option, the output format will consist of affected lines along with surrounding lines of context. The affected lines will show which ones need to be deleted or changed in file1, and those added from file2. With the -c option, three lines of context, if available, will be written before and after the affected lines. With the -C option, the user can specify how many lines of context will be written. The exact format follows.

The name and last modification time of each file will be output in the following format:

"*** %s %s\n", file1,
<file1 time stamp>
"--- %s %s\n", file2,
<file2 time stamp>

and a string of 15 asterisks:

"***************\n"

Each <file> field will be the pathname of the corresponding file being compared. The pathname written for standard input is unspecified.

In the POSIX locale, each <timestamp> field will be equivalent to the output from the following command:


date "+%a %b %e %T %Y"

without the trailing newline character, executed at the time of last modification of the corresponding file (or the current time, if the file is standard input).

Then, the following output formats will be applied for every set of changes.

First, the range of lines in file1 will be written in the following format:

"*** %d,%d ****\n", <beginning line number>, <ending line number>

Next, the affected lines along with lines of context (unaffected lines) will be written. Unaffected lines will be written in the following format:

"%s", <unaffected_line>

Deleted lines will be written as:

"-2%s", <deleted_line>

Changed lines will be written as:

"!%s", <changed_line>

Next, the range of lines in file2 will be written in the following format:

"--- %d,%d ----\n", <beginning line number>, <ending line number>

Then, lines of context and changed lines will be written as described in the previous formats. Lines added from file2 will be written in the following format:

"+%s", <added_line>

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:
0
No differences were found.
1
Differences were found.
>1
An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

If lines at the end of a file are changed and other lines are added, diff output may show this as a delete and add, as a change, or as a change and add; diff is not expected to know which happened and users should not care about the difference in output as long as it clearly shows the differences between the files.

 EXAMPLES

If dir1 is a directory containing a directory named x, dir2 is a directory containing a directory named x, dir1/x and dir2/x both contain files named date.out, and dir2/x contains a file named y, the command:

diff -r dir1 dir2

could produce output similar to:

Common subdirectories: dir1/x and dir2/x
Only in dir2/x: y
diff -r dir1/x/date.out dir2/x/date.out
1c1
< Mon Jul  2 13:12:16 PDT 1990
---
> Tue Jun 19 21:41:39 PDT 1990

 FUTURE DIRECTIONS

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

 SEE ALSO

cmp, comm, dircmp, ed.

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]