Annotation of src/usr.bin/diff/diff.1, Revision 1.30
1.30 ! jmc 1: .\" $OpenBSD: diff.1,v 1.29 2005/12/27 12:48:56 jmc Exp $
1.6 millert 2: .\"
1.2 deraadt 3: .\" Copyright (c) 1980, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 deraadt 5: .\"
1.2 deraadt 6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.4 deraadt 14: .\" 3. Neither the name of the University nor the names of its contributors
1.2 deraadt 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
1.1 deraadt 17: .\"
1.2 deraadt 18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
1.1 deraadt 29: .\"
1.2 deraadt 30: .\" @(#)diff.1 8.1 (Berkeley) 6/30/93
31: .\"
1.16 millert 32: .Dd July 21, 2003
1.1 deraadt 33: .Dt DIFF 1
1.5 jmc 34: .Os
1.1 deraadt 35: .Sh NAME
36: .Nm diff
37: .Nd differential file and directory comparator
38: .Sh SYNOPSIS
39: .Nm diff
1.23 otto 40: .Op Fl abdilpqtTw
1.26 otto 41: .Op Fl I Ar pattern
1.6 millert 42: .Oo
1.26 otto 43: .Fl c | e | f |
44: .Fl n | u
1.6 millert 45: .Oc
1.16 millert 46: .Op Fl L Ar label
1.6 millert 47: .Ar file1 file2
48: .Nm diff
1.23 otto 49: .Op Fl abdilpqtTw
1.26 otto 50: .Op Fl I Ar pattern
1.16 millert 51: .Op Fl L Ar label
52: .Fl C Ar number
1.6 millert 53: .Ar file1 file2
54: .Nm diff
1.19 otto 55: .Op Fl abdilqtw
1.26 otto 56: .Op Fl I Ar pattern
1.16 millert 57: .Fl D Ar string
1.1 deraadt 58: .Ar file1 file2
59: .Nm diff
1.23 otto 60: .Op Fl abdilpqtTw
1.26 otto 61: .Op Fl I Ar pattern
1.16 millert 62: .Op Fl L Ar label
63: .Fl U Ar number
1.1 deraadt 64: .Ar file1 file2
65: .Nm diff
1.23 otto 66: .Op Fl abdilNPpqtTw
1.26 otto 67: .Op Fl I Ar pattern
1.6 millert 68: .Oo
1.26 otto 69: .Fl c | e | f |
70: .Fl n | u
1.6 millert 71: .Oc
1.11 millert 72: .Bk -words
1.16 millert 73: .Op Fl L Ar label
1.1 deraadt 74: .Op Fl r
75: .Op Fl s
1.6 millert 76: .Op Fl S Ar name
1.11 millert 77: .Op Fl X Ar file
78: .Op Fl x Ar pattern
79: .Ek
1.1 deraadt 80: .Ar dir1 dir2
81: .Sh DESCRIPTION
82: The
1.5 jmc 83: .Nm
1.1 deraadt 84: utility compares the contents of
85: .Ar file1
86: and
87: .Ar file2
88: and writes to the standard output the list of changes necessary to
89: convert one file into the other.
90: No output is produced if the files are identical.
91: .Pp
1.22 jmc 92: Output options (mutually exclusive):
1.2 deraadt 93: .Bl -tag -width Ds
94: .It Fl c
1.6 millert 95: Produces a diff with 3 lines of context.
1.1 deraadt 96: With
97: .Fl c
98: the output format is modified slightly:
1.21 jmc 99: the output begins with identification of the files involved and
1.1 deraadt 100: their creation dates and then each change is separated
1.26 otto 101: by a line with fifteen
102: .Li * Ns 's .
1.1 deraadt 103: The lines removed from
104: .Ar file1
1.5 jmc 105: are marked with
1.26 otto 106: .Sq \&-\ \& ;
1.5 jmc 107: those added to
1.1 deraadt 108: .Ar file2
1.5 jmc 109: are marked
110: .Sq \+\ \& .
111: Lines which are changed from one file to the other are marked in
112: both files with
113: .Sq !\ \& .
1.19 otto 114: Changes which lie within 3 lines of each other are grouped together on
115: output.
1.2 deraadt 116: .It Fl e
1.5 jmc 117: Produces output in a form suitable as input for the editor utility,
1.1 deraadt 118: .Xr ed 1 ,
119: which can then be used to convert file1 into file2.
120: .Pp
121: Extra commands are added to the output when comparing directories with
122: .Fl e ,
123: so that the result is a
1.5 jmc 124: .Xr sh 1
1.1 deraadt 125: script for converting text files which are common to the two directories
126: from their state in
127: .Ar dir1
128: to their state in
129: .Ar dir2 .
1.2 deraadt 130: .It Fl f
1.5 jmc 131: Identical output to that of the
1.1 deraadt 132: .Fl e
1.5 jmc 133: flag, but in reverse order.
134: It cannot be digested by
1.1 deraadt 135: .Xr ed 1 .
1.2 deraadt 136: .It Fl n
1.5 jmc 137: Produces a script similar to that of
1.1 deraadt 138: .Fl e ,
139: but in the opposite order and with a count of changed lines on each
1.5 jmc 140: insert or delete command.
141: This is the form used by
142: .Xr rcsdiff 1 .
1.13 millert 143: .It Fl q
144: Just print a line when the files differ.
145: Does not output a list of changes.
1.6 millert 146: .It Fl u
147: Produces a
148: .Em unified
149: diff with 3 lines of context.
150: A unified diff is similar to the context diff produced by the
151: .Fl c
152: option.
153: However, unlike with
154: .Fl c ,
155: all lines to be changed (added and/or removed) are present in
156: a single section.
157: .It Fl C Ar number
158: Like
159: .Fl c
160: but produces a diff with
161: .Ar number
162: lines of context.
163: .It Fl D Ar string
1.5 jmc 164: Creates a merged version of
1.1 deraadt 165: .Ar file1
166: and
167: .Ar file2
168: on the standard output, with C preprocessor controls included so that
169: a compilation of the result without defining
170: .Ar string
1.5 jmc 171: is equivalent to compiling
1.1 deraadt 172: .Ar file1 ,
173: while defining
174: .Ar string
175: will yield
176: .Ar file2 .
1.6 millert 177: .It Fl U Ar number
178: Like
179: .Fl u
180: but produces a diff with
181: .Ar number
182: lines of context.
1.2 deraadt 183: .El
1.1 deraadt 184: .Pp
185: Comparison options:
1.2 deraadt 186: .Bl -tag -width Ds
1.11 millert 187: .It Fl a
1.26 otto 188: Treat all files as
1.28 jmc 189: .Tn ASCII
190: text.
191: Normally
192: .Nm
193: will simply print
194: .Dq Binary files ... differ
195: if files contain binary characters.
196: Use of this option forces
197: .Nm
198: to produce a diff.
1.2 deraadt 199: .It Fl b
1.5 jmc 200: Causes trailing blanks (spaces and tabs) to be ignored, and other
1.1 deraadt 201: strings of blanks to compare equal.
1.22 jmc 202: .It Fl d
203: Try very hard to produce a diff as small as possible.
204: This may consume a lot of processing power and memory when processing
205: large files with many changes.
1.26 otto 206: .It Fl I Ar pattern
207: Ignores changes, insertions, and deletions whose lines match the
208: extended regular expression
209: .Ar pattern .
210: Multiple
211: .Fl I
212: patterns may be specified.
213: All lines in the change must match some pattern for the change to be
214: ignored.
215: See
216: .Xr re_format 7
217: for more information on regular expression patterns.
1.16 millert 218: .It Fl i
219: Ignores the case of letters.
220: E.g.,
221: .Dq A
222: will compare equal to
223: .Dq a .
1.14 millert 224: .It Fl l
225: Long output format; each text file
226: .Nm diff Ns \'d
227: is piped through
228: .Xr pr 1
229: to paginate it;
230: other differences are remembered and summarized
231: after all text file differences are reported.
1.16 millert 232: .It Fl L Ar label
233: Print
234: .Ar label
1.27 millert 235: instead of the first (and second, if this option is specified twice)
236: file name and time in the context or unified diff header.
1.23 otto 237: .It Fl p
238: With unified and context diffs, show with each change
239: the first 40 characters of the last line before the context beginning
240: with a letter, an underscore or a dollar sign.
241: For C source code following standard layout conventions, this will
242: show the prototype of the function the change applies to.
1.2 deraadt 243: .It Fl t
1.5 jmc 244: Will expand tabs in output lines.
245: Normal or
1.1 deraadt 246: .Fl c
247: output adds character(s) to the front of each line which may screw up
248: the indentation of the original source lines and make the output listing
1.5 jmc 249: difficult to interpret.
250: This option will preserve the original source's indentation.
1.16 millert 251: .It Fl T
252: Print a tab rather than a space before the rest of the line for the
253: normal, context or unified output formats.
254: This makes the alignment of tabs in the line consistent.
1.2 deraadt 255: .It Fl w
1.5 jmc 256: Is similar to
1.1 deraadt 257: .Fl b
1.5 jmc 258: but causes whitespace (blanks and tabs) to be totally ignored.
259: E.g.,
260: .Dq if (\ \&a == b \&)
261: will compare equal to
262: .Dq if(a==b) .
1.2 deraadt 263: .El
1.1 deraadt 264: .Pp
265: Directory comparison options:
1.2 deraadt 266: .Bl -tag -width Ds
1.11 millert 267: .It Fl N
268: If a file is found in only one directory, act as if it was found in the
269: other directory too but was of zero size.
1.12 millert 270: .It Fl P
271: If a file is found only in
272: .Ar dir2 ,
273: act as if it was found in
274: .Ar dir1
275: too but was of zero size.
1.2 deraadt 276: .It Fl r
1.5 jmc 277: Causes application of
278: .Nm
1.1 deraadt 279: recursively to common subdirectories encountered.
1.2 deraadt 280: .It Fl s
1.5 jmc 281: Causes
282: .Nm
1.1 deraadt 283: to report files which are the same, which are otherwise not mentioned.
1.6 millert 284: .It Fl S Ar name
1.5 jmc 285: Re-starts a directory
286: .Nm
287: in the middle, beginning with file
1.1 deraadt 288: .Ar name .
1.11 millert 289: .It Fl X Ar file
290: Exclude files and subdirectories from comparison whose basenames match
291: lines in
292: .Ar file .
293: Multiple
294: .Fl X
295: options may be specified.
296: .It Fl x Ar pattern
297: Exclude files and subdirectories from comparison whose basenames match
298: .Ar pattern .
299: Patterns are matched using shell-style globbing via
300: .Xr fnmatch 3 .
301: Multiple
302: .Fl x
303: options may be specified.
1.2 deraadt 304: .El
1.1 deraadt 305: .Pp
306: If both arguments are directories,
1.5 jmc 307: .Nm
1.1 deraadt 308: sorts the contents of the directories by name, and then runs the
309: regular file
1.5 jmc 310: .Nm
1.1 deraadt 311: algorithm, producing a change list,
312: on text files which are different.
313: Binary files which differ,
314: common subdirectories, and files which appear in only one directory
315: are described as such.
1.25 millert 316: In directory mode only regular files and directories are compared.
1.26 otto 317: If a non-regular file such as a device special file or
318: .Tn FIFO
319: is encountered, a diagnostic message is printed.
1.1 deraadt 320: .Pp
321: If only one of
322: .Ar file1
323: and
324: .Ar file2
325: is a directory,
1.5 jmc 326: .Nm
1.1 deraadt 327: is applied to the non-directory file and the file contained in
328: the directory file with a filename that is the same as the
329: last component of the non-directory file.
330: .Pp
1.2 deraadt 331: If either
1.1 deraadt 332: .Ar file1
333: or
334: .Ar file2
335: is
1.2 deraadt 336: .Sq Fl ,
1.1 deraadt 337: the standard input is
338: used in its place.
339: .Ss Output Style
340: The default (without
341: .Fl e ,
342: .Fl c ,
343: or
344: .Fl n
1.5 jmc 345: .\" -C
1.1 deraadt 346: options)
347: output contains lines of these forms, where
348: .Va XX , YY , ZZ , QQ
349: are line numbers respective of file order.
350: .Pp
1.2 deraadt 351: .Bl -tag -width "XX,YYcZZ,QQ" -compact
352: .It Li XX Ns Ic a Ns Li YY
1.1 deraadt 353: At (the end of) line
354: .Va XX
355: of
356: .Ar file1 ,
357: append the contents
358: of line
359: .Va YY
360: of
361: .Ar file2
362: to make them equal.
1.2 deraadt 363: .It Li XX Ns Ic a Ns Li YY,ZZ
1.1 deraadt 364: Same as above, but append the range of lines,
365: .Va YY
366: through
367: .Va ZZ
368: of
369: .Ar file2
370: to line
371: .Va XX
372: of file1.
1.2 deraadt 373: .It Li XX Ns Ic d Ns Li YY
1.1 deraadt 374: At line
375: .Va XX
376: delete
1.5 jmc 377: the line.
378: The value
1.1 deraadt 379: .Va YY
1.5 jmc 380: tells to which line the change would bring
1.1 deraadt 381: .Ar file1
382: in line with
383: .Ar file1 .
1.2 deraadt 384: .It Li XX,YY Ns Ic d Ns Li ZZ
1.1 deraadt 385: Delete the range of lines
386: .Va XX
387: through
388: .Va YY
389: in
390: .Ar file1 .
1.2 deraadt 391: .It Li XX Ns Ic c Ns Li YY
1.1 deraadt 392: Change the line
393: .Va XX
394: in
395: .Ar file1
396: to the line
397: .Va YY
398: in
1.5 jmc 399: .Ar file2 .
1.2 deraadt 400: .It Li XX,YY Ns Ic c Ns Li ZZ
1.1 deraadt 401: Replace the range of specified lines with the line
402: .Va ZZ .
1.2 deraadt 403: .It Li XX,YY Ns Ic c Ns Li ZZ,QQ
1.1 deraadt 404: Replace the range
1.26 otto 405: .Va XX , Ns Va YY
1.1 deraadt 406: from
407: .Ar file1
408: with the range
1.26 otto 409: .Va ZZ , Ns Va QQ
1.1 deraadt 410: from
411: .Ar file2 .
1.2 deraadt 412: .El
1.1 deraadt 413: .Pp
414: These lines resemble
415: .Xr ed 1
416: subcommands to convert
417: .Ar file1
418: into
419: .Ar file2 .
420: The line numbers before the action letters pertain to
421: .Ar file1 ;
422: those after pertain to
423: .Ar file2 .
424: Thus, by exchanging
425: .Ic a
426: for
427: .Ic d
428: and reading the line in reverse order, one can also
429: determine how to convert
430: .Ar file2
431: into
432: .Ar file1 .
433: As in
434: .Xr ed 1 ,
435: identical
436: pairs (where num1 = num2) are abbreviated as a single
437: number.
438: .Sh ENVIRONMENT
1.2 deraadt 439: .Bl -tag -width TMPDIR
440: .It Ev TMPDIR
1.1 deraadt 441: If the environment variable
442: .Ev TMPDIR
443: exists,
1.5 jmc 444: .Nm
1.2 deraadt 445: will use the directory specified by
1.1 deraadt 446: .Ev TMPDIR
1.2 deraadt 447: as the temporary directory.
448: .El
1.1 deraadt 449: .Sh FILES
1.17 millert 450: .Bl -tag -width /tmp/diff.XXXXXXXX -compact
1.26 otto 451: .It Pa /tmp/diff. Ns Ar XXXXXXXX
1.17 millert 452: Temporary file used when comparing a device or the standard input.
453: Note that the temporary file is unlinked as soon as it is created
454: so it will not show up in a directory listing.
1.2 deraadt 455: .El
1.1 deraadt 456: .Sh DIAGNOSTICS
457: The
1.5 jmc 458: .Nm
1.1 deraadt 459: utility exits with one of the following values:
1.2 deraadt 460: .Pp
461: .Bl -tag -width Ds -compact -offset indent
1.30 ! jmc 462: .It 0
1.1 deraadt 463: No differences were found.
1.30 ! jmc 464: .It 1
1.1 deraadt 465: Differences were found.
1.30 ! jmc 466: .It \*(Gt1
1.1 deraadt 467: An error occurred.
1.2 deraadt 468: .El
1.5 jmc 469: .Sh SEE ALSO
470: .Xr cmp 1 ,
471: .Xr comm 1 ,
472: .Xr diff3 1 ,
1.11 millert 473: .Xr ed 1 ,
1.14 millert 474: .Xr pr 1 ,
1.29 jmc 475: .Xr sdiff 1 ,
1.26 otto 476: .Xr fnmatch 3 ,
477: .Xr re_format 7
1.15 millert 478: .Sh STANDARDS
479: The
480: .Nm
481: utility is expected to be a superset of the
1.24 jmc 482: .St -p1003.1-2001
1.15 millert 483: specification.
1.5 jmc 484: .Sh HISTORY
485: A
486: .Nm
487: command appeared in
488: .At v6 .
1.1 deraadt 489: .Sh BUGS
490: When comparing directories with the
491: .Fl b ,
492: .Fl w
493: or
494: .Fl i
495: options specified,
1.5 jmc 496: .Nm
1.1 deraadt 497: first compares the files ala
1.5 jmc 498: .Xr cmp 1 ,
1.1 deraadt 499: and then decides to run the
1.5 jmc 500: .Nm
1.1 deraadt 501: algorithm if they are not equal.
502: This may cause a small amount of spurious output if the files
503: then turn out to be identical because the only differences are
1.5 jmc 504: insignificant whitespace or case differences.