1DIFF(1P) POSIX Programmer's Manual DIFF(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 diff - compare two files
13
15 diff [-c| -e| -f| -C n][-br] file1 file2
16
18 The diff utility shall compare the contents of file1 and file2 and
19 write to standard output a list of changes necessary to convert file1
20 into file2. This list should be minimal. No output shall be produced if
21 the files are identical.
22
24 The diff utility shall conform to the Base Definitions volume of
25 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
26 The following options shall be supported:
28 -b Cause any amount of white space at the end of a line to be
30 treated as a single <newline> (that is, the white-space charac‐
31 ters preceding the <newline> are ignored) and other strings of
32 white-space characters, not including <newline>s, to compare
33 equal.
34 -c Produce output in a form that provides three lines of context.
36 -C n Produce output in a form that provides n lines of context (where
38 n shall be interpreted as a positive decimal integer).
39 -e Produce output in a form suitable as input for the ed utility,
41 which can then be used to convert file1 into file2.
42 -f Produce output in an alternative form, similar in format to -e,
44 but not intended to be suitable as input for the ed utility, and
45 in the opposite order.
46 -r Apply diff recursively to files and directories of the same name
48 when file1 and file2 are both directories.
49
52 The following operands shall be supported:
53 file1, file2
55 A pathname of a file to be compared. If either the file1 or
56 file2 operand is '-', the standard input shall be used in its
57 place.
58 If both file1 and file2 are directories, diff shall not compare block
61 special files, character special files, or FIFO special files to any
62 files and shall not compare regular files to directories. Further
63 details are as specified in Diff Directory Comparison Format . The
64 behavior of diff on other file types is implementation-defined when
65 found in directories.
66 If only one of file1 and file2 is a directory, diff shall be applied to
68 the non-directory file and the file contained in the directory file
69 with a filename that is the same as the last component of the non-
70 directory file.
71
73 The standard input shall be used only if one of the file1 or file2 op‐
74 erands references standard input. See the INPUT FILES section.
75
77 The input files may be of any type.
78
80 The following environment variables shall affect the execution of diff:
81 LANG Provide a default value for the internationalization variables
83 that are unset or null. (See the Base Definitions volume of
84 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
85 ables for the precedence of internationalization variables used
86 to determine the values of locale categories.)
87 LC_ALL If set to a non-empty string value, override the values of all
89 the other internationalization variables.
90 LC_CTYPE
92 Determine the locale for the interpretation of sequences of
93 bytes of text data as characters (for example, single-byte as
94 opposed to multi-byte characters in arguments and input files).
95 LC_MESSAGES
97 Determine the locale that should be used to affect the format
98 and contents of diagnostic messages written to standard error
99 and informative messages written to standard output.
100 LC_TIME
102 Determine the locale for affecting the format of file timestamps
103 written with the -C and -c options.
104 NLSPATH
106 Determine the location of message catalogs for the processing of
107 LC_MESSAGES .
108 TZ Determine the timezone used for calculating file timestamps
110 written with the -C and -c options. If TZ is unset or null, an
111 unspecified default timezone shall be used.
112
115 Default.
116
118 Diff Directory Comparison Format
119 If both file1 and file2 are directories, the following output formats
120 shall be used.
121 In the POSIX locale, each file that is present in only one directory
123 shall be reported using the following format:
124 "Only in %s: %s\n", <directory pathname>, <filename>
127 In the POSIX locale, subdirectories that are common to the two directo‐
129 ries may be reported with the following format:
130 "Common subdirectories: %s and %s\n", <directory1 pathname>,
133 <directory2 pathname>
134 For each file common to the two directories if the two files are not to
136 be compared, the following format shall be used in the POSIX locale:
137 "File %s is a %s while file %s is a %s\n", <directory1 pathname>,
140 <file type of directory1 pathname>, <directory2 pathname>,
141 <file type of directory2 pathname>
142 For each file common to the two directories, if the files are compared
144 and are identical, no output shall be written. If the two files differ,
145 the following format is written:
146 "diff %s %s %s\n", <diff_options>, <filename1>, <filename2>
149 where <diff_options> are the options as specified on the command line.
151 All directory pathnames listed in this section shall be relative to the
153 original command line arguments. All other names of files listed in
154 this section shall be filenames (pathname components).
155 Diff Binary Output Format
157 In the POSIX locale, if one or both of the files being compared are not
158 text files, an unspecified format shall be used that contains the path‐
159 names of two files being compared and the string "differ" .
160 If both files being compared are text files, depending on the options
162 specified, one of the following formats shall be used to write the dif‐
163 ferences.
164 Diff Default Output Format
166 The default (without -e, -f, -c, or -C options) diff utility output
167 shall contain lines of these forms:
168 "%da%d\n", <num1>, <num2>
171 "%da%d,%d\n", <num1>, <num2>, <num3>
174 "%dd%d\n", <num1>, <num2>
177 "%d,%dd%d\n", <num1>, <num2>, <num3>
180 "%dc%d\n", <num1>, <num2>
183 "%d,%dc%d\n", <num1>, <num2>, <num3>
186 "%dc%d,%d\n", <num1>, <num2>, <num3>
189 "%d,%dc%d,%d\n", <num1>, <num2>, <num3>, <num4>
192 These lines resemble ed subcommands to convert file1 into file2. The
194 line numbers before the action letters shall pertain to file1; those
195 after shall pertain to file2. Thus, by exchanging a for d and reading
196 the line in reverse order, one can also determine how to convert file2
197 into file1. As in ed, identical pairs (where num1= num2) are abbrevi‐
198 ated as a single number.
199 Following each of these lines, diff shall write to standard output all
201 lines affected in the first file using the format:
202 "< %s", <line>
205 and all lines affected in the second file using the format:
207 "> %s", <line>
210 If there are lines affected in both file1 and file2 (as with the c sub‐
212 command), the changes are separated with a line consisting of three
213 hyphens:
214 "---\n"
217 Diff -e Output Format
219 With the -e option, a script shall be produced that shall, when pro‐
220 vided as input to ed, along with an appended w (write) command, convert
221 file1 into file2. Only the a (append), c (change), d (delete), i
222 (insert), and s (substitute) commands of ed shall be used in this
223 script. Text lines, except those consisting of the single character
224 period ( '.' ), shall be output as they appear in the file.
225 Diff -f Output Format
227 With the -f option, an alternative format of script shall be produced.
228 It is similar to that produced by -e, with the following differences:
229 1. It is expressed in reverse sequence; the output of -e orders
231 changes from the end of the file to the beginning; the -f from
232 beginning to end.
233 2. The command form <lines> <command-letter> used by -e is reversed.
235 For example, 10c with -e would be c10 with -f.
236 3. The form used for ranges of line numbers is <space>-separated,
238 rather than comma-separated.
239 Diff -c or -C Output Format
241 With the -c or -C option, the output format shall consist of affected
242 lines along with surrounding lines of context. The affected lines shall
243 show which ones need to be deleted or changed in file1, and those added
244 from file2. With the -c option, three lines of context, if available,
245 shall be written before and after the affected lines. With the -C
246 option, the user can specify how many lines of context are written. The
247 exact format follows.
248 The name and last modification time of each file shall be output in the
250 following format:
251 "*** %s %s\n", file1, <file1 timestamp>
254 "--- %s %s\n", file2, <file2 timestamp>
255 Each <file> field shall be the pathname of the corresponding file being
257 compared. The pathname written for standard input is unspecified.
258 In the POSIX locale, each <timestamp> field shall be equivalent to the
260 output from the following command:
261 date "+%a %b %e %T %Y"
264 without the trailing <newline>, executed at the time of last modifica‐
266 tion of the corresponding file (or the current time, if the file is
267 standard input).
268 Then, the following output formats shall be applied for every set of
270 changes.
271 First, a line shall be written in the following format:
273 "***************\n"
276 Next, the range of lines in file1 shall be written in the following
278 format if the range contains two or more lines:
279 "*** %d,%d ****\n", <beginning line number>, <ending line number>
282 and the following format otherwise:
284 "*** %d ****\n", <ending line number>
287 The ending line number of an empty range shall be the number of the
289 preceding line, or 0 if the range is at the start of the file.
290 Next, the affected lines along with lines of context (unaffected lines)
292 shall be written. Unaffected lines shall be written in the following
293 format:
294 " %s", <unaffected_line>
297 Deleted lines shall be written as:
299 "- %s", <deleted_line>
302 Changed lines shall be written as:
304 "! %s", <changed_line>
307 Next, the range of lines in file2 shall be written in the following
309 format if the range contains two or more lines:
310 "--- %d,%d ----\n", <beginning line number>, <ending line number>
313 and the following format otherwise:
315 "--- %d ----\n", <ending line number>
318 Then, lines of context and changed lines shall be written as described
320 in the previous formats. Lines added from file2 shall be written in the
321 following format:
322 "+ %s", <added_line>
325
327 The standard error shall be used only for diagnostic messages.
328
330 None.
331
333 None.
334
336 The following exit values shall be returned:
337 0 No differences were found.
339 1 Differences were found.
341 >1 An error occurred.
343
346 Default.
347 The following sections are informative.
349
351 If lines at the end of a file are changed and other lines are added,
352 diff output may show this as a delete and add, as a change, or as a
353 change and add; diff is not expected to know which happened and users
354 should not care about the difference in output as long as it clearly
355 shows the differences between the files.
356
358 If dir1 is a directory containing a directory named x, dir2 is a direc‐
359 tory containing a directory named x, dir1/x and dir2/x both contain
360 files named date.out, and dir2/x contains a file named y, the command:
361 diff -r dir1 dir2
364 could produce output similar to:
366 Common subdirectories: dir1/x and dir2/x
369 Only in dir2/x: y
370 diff -r dir1/x/date.out dir2/x/date.out
371 1c1
372 < Mon Jul 2 13:12:16 PDT 1990
373 ---
374 > Tue Jun 19 21:41:39 PDT 1990
375
377 The -h option was omitted because it was insufficiently specified and
378 does not add to applications portability.
379 Historical implementations employ algorithms that do not always produce
381 a minimum list of differences; the current language about making every
382 effort is the best this volume of IEEE Std 1003.1-2001 can do, as there
383 is no metric that could be employed to judge the quality of implementa‐
384 tions against any and all file contents. The statement "This list
385 should be minimal'' clearly implies that implementations are not
386 expected to provide the following output when comparing two 100-line
387 files that differ in only one character on a single line:
388 1,100c1,100
391 all 100 lines from file1 preceded with "< "
392 ---
393 all 100 lines from file2 preceded with "> "
394 The "Only in" messages required when the -r option is specified are not
396 used by most historical implementations if the -e option is also speci‐
397 fied. It is required here because it provides useful information that
398 must be provided to update a target directory hierarchy to match a
399 source hierarchy. The "Common subdirectories" messages are written by
400 System V and 4.3 BSD when the -r option is specified. They are allowed
401 here but are not required because they are reporting on something that
402 is the same, not reporting a difference, and are not needed to update a
403 target hierarchy.
404 The -c option, which writes output in a format using lines of context,
406 has been included. The format is useful for a variety of reasons, among
407 them being much improved readability and the ability to understand dif‐
408 ference changes when the target file has line numbers that differ from
409 another similar, but slightly different, copy. The patch utility is
410 most valuable when working with difference listings using the context
411 format. The BSD version of -c takes an optional argument specifying
412 the amount of context. Rather than overloading -c and breaking the
413 Utility Syntax Guidelines for diff, the standard developers decided to
414 add a separate option for specifying a context diff with a specified
415 amount of context ( -C). Also, the format for context diffs was
416 extended slightly in 4.3 BSD to allow multiple changes that are within
417 context lines from each other to be merged together. The output format
418 contains an additional four asterisks after the range of affected lines
419 in the first filename. This was to provide a flag for old programs
420 (like old versions of patch) that only understand the old context for‐
421 mat. The version of context described here does not require that multi‐
422 ple changes within context lines be merged, but it does not prohibit it
423 either. The extension is upwards-compatible, so any vendors that wish
424 to retain the old version of diff can do so by adding the extra four
425 asterisks (that is, utilities that currently use diff and understand
426 the new merged format will also understand the old unmerged format, but
427 not vice versa).
428 The substitute command was added as an additional format for the -e
430 option. This was added to provide implementations with a way to fix the
431 classic "dot alone on a line" bug present in many versions of diff.
432 Since many implementations have fixed this bug, the standard developers
433 decided not to standardize broken behavior, but rather to provide the
434 necessary tool for fixing the bug. One way to fix this bug is to output
435 two periods whenever a lone period is needed, then terminate the append
436 command with a period, and then use the substitute command to convert
437 the two periods into one period.
438 The BSD-derived -r option was added to provide a mechanism for using
440 diff to compare two file system trees. This behavior is useful, is
441 standard practice on all BSD-derived systems, and is not easily repro‐
442 ducible with the find utility.
443 The requirement that diff not compare files in some circumstances, even
445 though they have the same name, is based on the actual output of his‐
446 torical implementations. The message specified here is already in use
447 when a directory is being compared to a non-directory. It is extended
448 here to preclude the problems arising from running into FIFOs and other
449 files that would cause diff to hang waiting for input with no indica‐
450 tion to the user that diff was hung. In most common usage, diff -r
451 should indicate differences in the file hierarchies, not the difference
452 of contents of devices pointed to by the hierarchies.
453 Many early implementations of diff require seekable files. Since the
455 System Interfaces volume of IEEE Std 1003.1-2001 supports named pipes,
456 the standard developers decided that such a restriction was unreason‐
457 able. Note also that the allowed filename - almost always refers to a
458 pipe.
459 No directory search order is specified for diff. The historical order‐
461 ing is, in fact, not optimal, in that it prints out all of the differ‐
462 ences at the current level, including the statements about all common
463 subdirectories before recursing into those subdirectories.
464 The message:
466 "diff %s %s %s\n", <diff_options>, <filename1>, <filename2>
469 does not vary by locale because it is the representation of a command,
471 not an English sentence.
472
474 None.
475
477 cmp, comm, ed, find
478
480 Portions of this text are reprinted and reproduced in electronic form
481 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
482 -- Portable Operating System Interface (POSIX), The Open Group Base
483 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
484 Electrical and Electronics Engineers, Inc and The Open Group. In the
485 event of any discrepancy between this version and the original IEEE and
486 The Open Group Standard, the original IEEE and The Open Group Standard
487 is the referee document. The original Standard can be obtained online
488 at http://www.opengroup.org/unix/online.html .
489IEEE/The Open Group 2003 DIFF(1P)