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