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