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