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