Annotation of src/usr.bin/diff/diff.1, Revision 1.13
1.13 ! millert 1: .\" $OpenBSD: diff.1,v 1.12 2003/07/06 22:02:36 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.13 ! millert 40: .Op Fl abiqtw
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.13 ! millert 47: .Op Fl abiqtw
1.6 millert 48: .Op Fl C Ar number
49: .Ar file1 file2
50: .Nm diff
1.13 ! millert 51: .Op Fl abiqtw
1.6 millert 52: .Op Fl D Ar string
1.1 deraadt 53: .Ar file1 file2
54: .Nm diff
1.13 ! millert 55: .Op Fl abiqtw
1.6 millert 56: .Op Fl U Ar number
1.1 deraadt 57: .Ar file1 file2
58: .Nm diff
1.13 ! millert 59: .Op Fl abiNqtw
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.2 deraadt 181: .It Fl i
1.5 jmc 182: Ignores the case of letters.
183: E.g.,
184: .Dq A
185: will compare equal to
186: .Dq a .
1.2 deraadt 187: .It Fl t
1.5 jmc 188: Will expand tabs in output lines.
189: Normal or
1.1 deraadt 190: .Fl c
191: output adds character(s) to the front of each line which may screw up
192: the indentation of the original source lines and make the output listing
1.5 jmc 193: difficult to interpret.
194: This option will preserve the original source's indentation.
1.2 deraadt 195: .It Fl w
1.5 jmc 196: Is similar to
1.1 deraadt 197: .Fl b
1.5 jmc 198: but causes whitespace (blanks and tabs) to be totally ignored.
199: E.g.,
200: .Dq if (\ \&a == b \&)
201: will compare equal to
202: .Dq if(a==b) .
1.2 deraadt 203: .El
1.1 deraadt 204: .Pp
205: Directory comparison options:
1.2 deraadt 206: .Bl -tag -width Ds
1.11 millert 207: .It Fl N
208: If a file is found in only one directory, act as if it was found in the
209: other directory too but was of zero size.
1.12 millert 210: .It Fl P
211: If a file is found only in
212: .Ar dir2 ,
213: act as if it was found in
214: .Ar dir1
215: too but was of zero size.
1.2 deraadt 216: .It Fl r
1.5 jmc 217: Causes application of
218: .Nm
1.1 deraadt 219: recursively to common subdirectories encountered.
1.2 deraadt 220: .It Fl s
1.5 jmc 221: Causes
222: .Nm
1.1 deraadt 223: to report files which are the same, which are otherwise not mentioned.
1.6 millert 224: .It Fl S Ar name
1.5 jmc 225: Re-starts a directory
226: .Nm
227: in the middle, beginning with file
1.1 deraadt 228: .Ar name .
1.11 millert 229: .It Fl X Ar file
230: Exclude files and subdirectories from comparison whose basenames match
231: lines in
232: .Ar file .
233: Multiple
234: .Fl X
235: options may be specified.
236: .It Fl x Ar pattern
237: Exclude files and subdirectories from comparison whose basenames match
238: .Ar pattern .
239: Patterns are matched using shell-style globbing via
240: .Xr fnmatch 3 .
241: Multiple
242: .Fl x
243: options may be specified.
1.2 deraadt 244: .El
1.1 deraadt 245: .Pp
246: If both arguments are directories,
1.5 jmc 247: .Nm
1.1 deraadt 248: sorts the contents of the directories by name, and then runs the
249: regular file
1.5 jmc 250: .Nm
1.1 deraadt 251: algorithm, producing a change list,
252: on text files which are different.
253: Binary files which differ,
254: common subdirectories, and files which appear in only one directory
255: are described as such.
256: .Pp
257: If only one of
258: .Ar file1
259: and
260: .Ar file2
261: is a directory,
1.5 jmc 262: .Nm
1.1 deraadt 263: is applied to the non-directory file and the file contained in
264: the directory file with a filename that is the same as the
265: last component of the non-directory file.
266: .Pp
1.2 deraadt 267: If either
1.1 deraadt 268: .Ar file1
269: or
270: .Ar file2
271: is
1.2 deraadt 272: .Sq Fl ,
1.1 deraadt 273: the standard input is
274: used in its place.
275: .Ss Output Style
276: The default (without
277: .Fl e ,
278: .Fl c ,
279: or
280: .Fl n
1.5 jmc 281: .\" -C
1.1 deraadt 282: options)
283: output contains lines of these forms, where
284: .Va XX , YY , ZZ , QQ
285: are line numbers respective of file order.
286: .Pp
1.2 deraadt 287: .Bl -tag -width "XX,YYcZZ,QQ" -compact
288: .It Li XX Ns Ic a Ns Li YY
1.1 deraadt 289: At (the end of) line
290: .Va XX
291: of
292: .Ar file1 ,
293: append the contents
294: of line
295: .Va YY
296: of
297: .Ar file2
298: to make them equal.
1.2 deraadt 299: .It Li XX Ns Ic a Ns Li YY,ZZ
1.1 deraadt 300: Same as above, but append the range of lines,
301: .Va YY
302: through
303: .Va ZZ
304: of
305: .Ar file2
306: to line
307: .Va XX
308: of file1.
1.2 deraadt 309: .It Li XX Ns Ic d Ns Li YY
1.1 deraadt 310: At line
311: .Va XX
312: delete
1.5 jmc 313: the line.
314: The value
1.1 deraadt 315: .Va YY
1.5 jmc 316: tells to which line the change would bring
1.1 deraadt 317: .Ar file1
318: in line with
319: .Ar file1 .
1.2 deraadt 320: .It Li XX,YY Ns Ic d Ns Li ZZ
1.1 deraadt 321: Delete the range of lines
322: .Va XX
323: through
324: .Va YY
325: in
326: .Ar file1 .
1.2 deraadt 327: .It Li XX Ns Ic c Ns Li YY
1.1 deraadt 328: Change the line
329: .Va XX
330: in
331: .Ar file1
332: to the line
333: .Va YY
334: in
1.5 jmc 335: .Ar file2 .
1.2 deraadt 336: .It Li XX,YY Ns Ic c Ns Li ZZ
1.1 deraadt 337: Replace the range of specified lines with the line
338: .Va ZZ .
1.2 deraadt 339: .It Li XX,YY Ns Ic c Ns Li ZZ,QQ
1.1 deraadt 340: Replace the range
1.2 deraadt 341: .Va XX , Ns YY
1.1 deraadt 342: from
343: .Ar file1
344: with the range
1.2 deraadt 345: .Va ZZ , Ns QQ
1.1 deraadt 346: from
347: .Ar file2 .
1.2 deraadt 348: .El
1.1 deraadt 349: .Pp
350: These lines resemble
351: .Xr ed 1
352: subcommands to convert
353: .Ar file1
354: into
355: .Ar file2 .
356: The line numbers before the action letters pertain to
357: .Ar file1 ;
358: those after pertain to
359: .Ar file2 .
360: Thus, by exchanging
361: .Ic a
362: for
363: .Ic d
364: and reading the line in reverse order, one can also
365: determine how to convert
366: .Ar file2
367: into
368: .Ar file1 .
369: As in
370: .Xr ed 1 ,
371: identical
372: pairs (where num1 = num2) are abbreviated as a single
373: number.
374: .Sh ENVIRONMENT
1.2 deraadt 375: .Bl -tag -width TMPDIR
376: .It Ev TMPDIR
1.1 deraadt 377: If the environment variable
378: .Ev TMPDIR
379: exists,
1.5 jmc 380: .Nm
1.2 deraadt 381: will use the directory specified by
1.1 deraadt 382: .Ev TMPDIR
1.2 deraadt 383: as the temporary directory.
384: .El
1.1 deraadt 385: .Sh FILES
1.6 millert 386: .Bl -tag -width /tmp/diff1.XXXXXXXX -compact
387: .It Pa /tmp/diff1.XXXXXXXX
388: Temporary file used when
389: .Ar file1
390: is a device or stdin.
391: .It Pa /tmp/diff2.XXXXXXXX
392: Temporary file used when
393: .Ar file2
394: is a device or stdin.
395: .It Pa /usr/bin/diff
396: For directory diffs.
1.2 deraadt 397: .El
1.1 deraadt 398: .Sh DIAGNOSTICS
399: The
1.5 jmc 400: .Nm
1.1 deraadt 401: utility exits with one of the following values:
1.2 deraadt 402: .Pp
403: .Bl -tag -width Ds -compact -offset indent
404: .It \&0
1.1 deraadt 405: No differences were found.
1.2 deraadt 406: .It \&1
1.1 deraadt 407: Differences were found.
1.5 jmc 408: .It \*[Gt]\&1
1.1 deraadt 409: An error occurred.
1.2 deraadt 410: .El
1.5 jmc 411: .Sh SEE ALSO
412: .Xr cmp 1 ,
413: .Xr comm 1 ,
414: .Xr diff3 1 ,
1.11 millert 415: .Xr ed 1 ,
416: .Xr fnmatch 3
1.5 jmc 417: .Sh HISTORY
418: A
419: .Nm
420: command appeared in
421: .At v6 .
1.1 deraadt 422: .Sh BUGS
423: The
424: .Fl f
425: and
426: .Fl e
427: options
428: do not provide special handling for lines on which the
429: first and only character is
430: .Dq Li \&. .
431: This can cause problems for
432: .Xr ed 1 .
433: .Pp
434: When comparing directories with the
435: .Fl b ,
436: .Fl w
437: or
438: .Fl i
439: options specified,
1.5 jmc 440: .Nm
1.1 deraadt 441: first compares the files ala
1.5 jmc 442: .Xr cmp 1 ,
1.1 deraadt 443: and then decides to run the
1.5 jmc 444: .Nm
1.1 deraadt 445: algorithm if they are not equal.
446: This may cause a small amount of spurious output if the files
447: then turn out to be identical because the only differences are
1.5 jmc 448: insignificant whitespace or case differences.