STANDARD INPUT

The standard input shall be used only if one of the file1 or file2 operands references standard input. See Input Files.

INPUT FILES

The input files shall be text files.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of diff:

LANG

This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.

LC_ALL

This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

LC_CTYPE

This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments and input files).

LC_MESSAGES

This variable shall determine the language in which messages should be written.

LC_TIME

This variable shall determine the locale for affecting the format of file time stamps written with the −C and −c options.

TZ

This variable shall determine the locale for affecting the time zone used for calculating file time stamps written with the −C and −c options.

ASYNCHRONOUS EVENTS

Default.

DIFF DIRECTORY COMPARISON FORMAT

If both file1 and file2 are directories, the following output formats shall be used. In the POSIX Locale, each file that is present in only one directory shall 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 shall be used to write the differences. All directory pathnames listed in this subclause shall be relative to the original command line arguments. All other names of files listed in this subclause shall be filenames (pathname components).

DIFF DEFAULT OUTPUT FORMAT

The default (without −e, −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 shall pertain to file1; those after shall 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 shall 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 shall be produced that shall, when provided as input to ed (see ed(1) ), 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 shall be used in this script. Text line(s), except those consisting of the single character period (.), shall be output as they appear in the file.

DIFF −C OR −C OUTPUT FORMAT

With the −c or −C option, the output format shall consist of affected lines along with surrounding lines of context. The affected lines shall 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, shall be written before and after the affected lines. With the −C option, the user can specify how many lines of context shall be written. The exact format follows. The name and last modification time of each file shall 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 shall be the pathname of the corresponding file being compared. The pathname written for standard input is unspecified. In the POSIX Locale, each <time stamp> field shall be equivalent to the output from the following command:

date "+%a %b %e %T %Y" without the trailing <newline>, 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 shall be applied for every set of changes. First, the range of lines in file1 shall 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) shall be written. Unaffected lines shall be written in the following format: "∆∆%s", <unaffected_line> Deleted lines shall be written as: "-∆%s", <deleted_line> Changed lines shall be written as: "!∆%s", <changed_line> Next, the range of lines in file2 shall be written in the following format: "--- %d,%d ----\n", <beginning line number>, <ending line number> Then, lines of context and changed lines shall be written as described in the previous formats. Lines added from file2 shall be written in the following format: "+∆%s", <added_line>

STANDARD ERROR

Used only for diagnostic messages.

OUTPUT FILES

None.

EXAMPLES

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

HISTORY OF DECISIONS MADE

The −h option was removed because it was insufficiently specified and it does not add to application portability. Current implementations employ algorithms that do not always produce a minimum list of differences; the current language about making every effort is the best the standard can do, as there is no metric that could be employed to judge the quality of implementations against any and all file contents. The statement ‘‘This list should be minimal’’ clearly implies that implementations are not expected to provide the following output when comparing two 100-line files that differ in only one character on a single line: 1,100c1,100 all 100 lines from file1 preceded with "< "

all 100 lines from file2 preceded with "> " The ‘‘Only in’’ messages required by this standard when the −r option is specified, is not used by most historical implementations if the −e option is also specified. It is required here because it provides useful information that must be provided to update a target directory hierarchy to match a source hierarchy. The ‘‘Common subdirectories’’ messages are written by System V and bc(1) BSD when the −r option is specified. They are allowed here, but are not required because they are

reporting on something that is the same, not reporting a difference, and are not needed to update a target hierarchy. The −c option, which writes output in a format using lines of context, has been included. The format is useful for a variety of reasons, among them being much improved readability, and the ability to understand difference changes when the target file has line numbers that differ from another similar, but slightly different, copy. An important utility, patch, which has proved itself indispensable to the USENET community, often only works with difference listings using the context format. The BSD version of −c takes an optional argument specifying the amount of context. Rather than overloading −c and breaking the Utility Syntax Guidelines for diff, the working group decided to add a separate option for specifying a context diff with a specified amount of context (−C). Also, the format for context diffs was extended slightly in bc(1) BSD to allow multiple changes that are within context lines from each other to be merged together. The output format contains an additional four asterisks after the range of affected lines in the first filename. This was to provide a flag for old programs (like old versions of patch) that only understand the old context format. The version of context described here does not require that multiple changes within context lines be merged, but does not prohibit it either. The extension is upward compatible, so any vendors that wish to retain the old version of diff can do so by just adding the extra four asterisks (that is, utilities that currently use diff and understand the new merged format will also understand the old unmerged format, but not vice-versa). The substitute command was added as an additional format for the −e option. This was added to provide implementations a way to fix the classic ‘‘dot alone on a line’’ bug present in many versions of diff. Since many implementations have fixed this bug the working group decided not to standardize broken behavior, but rather, provide the necessary tool for fixing the bug. One way to fix this bug is to output two periods whenever a lone period is needed, then terminate the append command with a period, and then use the substitute command to convert the two periods into one period. The −f flag was not included as it provides no additional functionality over the −e option. The BSD -derived −r option was added to provide a mechanism for using diff to compare two file system trees. This behavior is useful, is standard practice on all BSD -derived systems, and is not easily reproducible with the find utility. The requirement that diff not compare files in some circumstances, even though they have the same name, was added in response to ballot objections and digging further into the actual output of historical implementations. The message specified here is already in use when a directory is being compared to a nondirectory. It is extended here to preclude the problems arising from running into FIFOs and other files that would cause diff to hang waiting for input with no indication to the user that diff was hung. In most common usage, diff −r should indicate differences in the file hierarchies, not the difference of contents of devices pointed to by the hierarchies.

Many early implementations of diff require seekable files. Since POSIX. 1 {8} supports named pipes, the working group decided that such a restriction was unreasonable. Note also that the allowed file name − almost always refers to a pipe. No directory search order is being specified in DIFF DIRECTORY COMPARISON FORMAT . The historical ordering is, in fact, not optimal, in that it prints out all of the differences at the current level, including the statements about all common subdirectories before recursing into those subdirectories. The message

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

does not vary by locale because it is the representation of a command, not an English sentence.