Annotation of src/usr.bin/diff/diff.1, Revision 1.4
1.4 ! deraadt 1: .\" $OpenBSD: diff.1,v 1.3 2003/06/25 03:02:33 tedu Exp $
1.2 deraadt 2: .\" Copyright (c) 1980, 1990, 1993
3: .\" The Regents of the University of California. All rights reserved.
1.1 deraadt 4: .\"
1.2 deraadt 5: .\" Redistribution and use in source and binary forms, with or without
6: .\" modification, are permitted provided that the following conditions
7: .\" are met:
8: .\" 1. Redistributions of source code must retain the above copyright
9: .\" notice, this list of conditions and the following disclaimer.
10: .\" 2. Redistributions in binary form must reproduce the above copyright
11: .\" notice, this list of conditions and the following disclaimer in the
12: .\" documentation and/or other materials provided with the distribution.
1.4 ! deraadt 13: .\" 3. Neither the name of the University nor the names of its contributors
1.2 deraadt 14: .\" may be used to endorse or promote products derived from this software
15: .\" without specific prior written permission.
1.1 deraadt 16: .\"
1.2 deraadt 17: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
18: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
21: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27: .\" SUCH DAMAGE.
1.1 deraadt 28: .\"
1.2 deraadt 29: .\" @(#)diff.1 8.1 (Berkeley) 6/30/93
30: .\"
31: .Dd June 30, 1993
1.1 deraadt 32: .Dt DIFF 1
33: .Os BSD 4
34: .Sh NAME
35: .Nm diff
36: .Nd differential file and directory comparator
37: .Sh SYNOPSIS
38: .Nm diff
39: .Op Fl cefhn
40: .Op Fl biwt
41: .Ar file1 file2
42: .Nm diff
1.2 deraadt 43: .Op Fl D Ns Ar string
1.1 deraadt 44: .Op Fl biw
45: .Ar file1 file2
46: .Nm diff
47: .Op Fl l
48: .Op Fl r
49: .Op Fl s
50: .Op Fl cefhn
51: .Op Fl biwt
1.2 deraadt 52: .Op Fl S Ns Ar name
1.1 deraadt 53: .Ar dir1 dir2
54: .Sh DESCRIPTION
55: The
56: .Nm diff
57: utility compares the contents of
58: .Ar file1
59: and
60: .Ar file2
61: and writes to the standard output the list of changes necessary to
62: convert one file into the other.
63: No output is produced if the files are identical.
64: .Pp
65: Output options (mutually exclusive):
1.2 deraadt 66: .Bl -tag -width Ds
67: .It Fl c
1.1 deraadt 68: produces a diff with lines of context.
1.2 deraadt 69: The default is to present 3 lines of context and may be changed, e.g., to 10, by
1.1 deraadt 70: .Fl c10 .
71: With
72: .Fl c
73: the output format is modified slightly:
74: the output beginning with identification of the files involved and
75: their creation dates and then each change is separated
76: by a line with a dozen *'s.
77: The lines removed from
78: .Ar file1
79: are marked with `\(mi '; those added to
80: .Ar file2
81: are marked `+ '. Lines which are changed from one
1.2 deraadt 82: file to the other are marked in both files with `! '.
1.1 deraadt 83: Changes which lie within <context> lines of each other are grouped
84: together on output. (This is a change from the previous ``diff -c''
85: but the resulting output is usually much easier to interpret.)
1.2 deraadt 86: .It Fl e
1.1 deraadt 87: produces output in a form suitable as input for the editor utility,
88: .Xr ed 1 ,
89: which can then be used to convert file1 into file2.
90: .Pp
91: Extra commands are added to the output when comparing directories with
92: .Fl e ,
93: so that the result is a
94: .Xr sh 1
95: script for converting text files which are common to the two directories
96: from their state in
97: .Ar dir1
98: to their state in
99: .Ar dir2 .
1.2 deraadt 100: .It Fl f
101: identical output to that of the
1.1 deraadt 102: .Fl e
103: flag, but in reverse order. It cannot
104: be digested by
105: .Xr ed 1 .
1.2 deraadt 106: .It Fl h
1.1 deraadt 107: Invokes an alternate algorithm which can handle files of very long lengths.
108: There is a trade off. The algorithm can only deal with changes which are
109: clearly delimited and brief. Long sections of changes and overlaps will
110: confuse it.
1.2 deraadt 111: .It Fl n
1.1 deraadt 112: produces a script similar to that of
113: .Fl e ,
114: but in the opposite order and with a count of changed lines on each
115: insert or delete command. This is the form used by
116: .Xr rcsdiff 1 .
1.2 deraadt 117: .It Fl D Ns Ar string
1.1 deraadt 118: creates a merged version of
119: .Ar file1
120: and
121: .Ar file2
122: on the standard output, with C preprocessor controls included so that
123: a compilation of the result without defining
124: .Ar string
125: is equivalent
126: to compiling
127: .Ar file1 ,
128: while defining
129: .Ar string
130: will yield
131: .Ar file2 .
1.2 deraadt 132: .El
1.1 deraadt 133: .Pp
134: Comparison options:
1.2 deraadt 135: .Bl -tag -width Ds
136: .It Fl b
1.1 deraadt 137: causes trailing blanks (spaces and tabs) to be ignored, and other
138: strings of blanks to compare equal.
1.2 deraadt 139: .It Fl i
1.1 deraadt 140: ignores the case of letters. E.g., ``A'' will compare equal to ``a''.
1.2 deraadt 141: .It Fl t
1.1 deraadt 142: will expand tabs in output lines. Normal or
143: .Fl c
144: output adds character(s) to the front of each line which may screw up
145: the indentation of the original source lines and make the output listing
146: difficult to interpret. This option will preserve the original source's
147: indentation.
1.2 deraadt 148: .It Fl w
1.1 deraadt 149: is similar to
150: .Fl b
151: but causes whitespace (blanks and tabs) to be totally ignored. E.g.,
152: ``if\ (\ a\ ==\ b\ )'' will compare equal to ``if(a==b)''.
1.2 deraadt 153: .El
1.1 deraadt 154: .Pp
155: Directory comparison options:
1.2 deraadt 156: .Bl -tag -width Ds
157: .It Fl l
1.1 deraadt 158: long output format; each text file
1.2 deraadt 159: .Nm diff Ns \'d
1.1 deraadt 160: is piped through
161: .Xr pr 1
162: to paginate it,
163: other differences are remembered and summarized
164: after all text file differences are reported.
1.2 deraadt 165: .It Fl r
1.1 deraadt 166: causes application of
167: .Nm diff
168: recursively to common subdirectories encountered.
1.2 deraadt 169: .It Fl s
1.1 deraadt 170: causes
171: .Nm diff
172: to report files which are the same, which are otherwise not mentioned.
1.2 deraadt 173: .It Fl S Ns Ar name
1.1 deraadt 174: re-starts a directory
175: .Nm diff
176: in the middle beginning with file
177: .Ar name .
1.2 deraadt 178: .El
1.1 deraadt 179: .Pp
180: If both arguments are directories,
181: .Nm diff
182: sorts the contents of the directories by name, and then runs the
183: regular file
184: .Nm diff
185: algorithm, producing a change list,
186: on text files which are different.
187: Binary files which differ,
188: common subdirectories, and files which appear in only one directory
189: are described as such.
190: .Pp
191: If only one of
192: .Ar file1
193: and
194: .Ar file2
195: is a directory,
196: .Nm diff
197: is applied to the non-directory file and the file contained in
198: the directory file with a filename that is the same as the
199: last component of the non-directory file.
200: .Pp
1.2 deraadt 201: If either
1.1 deraadt 202: .Ar file1
203: or
204: .Ar file2
205: is
1.2 deraadt 206: .Sq Fl ,
1.1 deraadt 207: the standard input is
208: used in its place.
209: .Ss Output Style
210: The default (without
211: .Fl e ,
212: .Fl c ,
213: or
214: .Fl n
215: .\" -C
216: options)
217: output contains lines of these forms, where
218: .Va XX , YY , ZZ , QQ
219: are line numbers respective of file order.
220: .Pp
1.2 deraadt 221: .Bl -tag -width "XX,YYcZZ,QQ" -compact
222: .It Li XX Ns Ic a Ns Li YY
1.1 deraadt 223: At (the end of) line
224: .Va XX
225: of
226: .Ar file1 ,
227: append the contents
228: of line
229: .Va YY
230: of
231: .Ar file2
232: to make them equal.
1.2 deraadt 233: .It Li XX Ns Ic a Ns Li YY,ZZ
1.1 deraadt 234: Same as above, but append the range of lines,
235: .Va YY
236: through
237: .Va ZZ
238: of
239: .Ar file2
240: to line
241: .Va XX
242: of file1.
1.2 deraadt 243: .It Li XX Ns Ic d Ns Li YY
1.1 deraadt 244: At line
245: .Va XX
246: delete
247: the line. The value
248: .Va YY
249: tells to which line the change
250: would bring
251: .Ar file1
252: in line with
253: .Ar file1 .
1.2 deraadt 254: .It Li XX,YY Ns Ic d Ns Li ZZ
1.1 deraadt 255: Delete the range of lines
256: .Va XX
257: through
258: .Va YY
259: in
260: .Ar file1 .
1.2 deraadt 261: .It Li XX Ns Ic c Ns Li YY
1.1 deraadt 262: Change the line
263: .Va XX
264: in
265: .Ar file1
266: to the line
267: .Va YY
268: in
269: .Ar file2.
1.2 deraadt 270: .It Li XX,YY Ns Ic c Ns Li ZZ
1.1 deraadt 271: Replace the range of specified lines with the line
272: .Va ZZ .
1.2 deraadt 273: .It Li XX,YY Ns Ic c Ns Li ZZ,QQ
1.1 deraadt 274: Replace the range
1.2 deraadt 275: .Va XX , Ns YY
1.1 deraadt 276: from
277: .Ar file1
278: with the range
1.2 deraadt 279: .Va ZZ , Ns QQ
1.1 deraadt 280: from
281: .Ar file2 .
1.2 deraadt 282: .El
1.1 deraadt 283: .Pp
284: These lines resemble
285: .Xr ed 1
286: subcommands to convert
287: .Ar file1
288: into
289: .Ar file2 .
290: The line numbers before the action letters pertain to
291: .Ar file1 ;
292: those after pertain to
293: .Ar file2 .
294: Thus, by exchanging
295: .Ic a
296: for
297: .Ic d
298: and reading the line in reverse order, one can also
299: determine how to convert
300: .Ar file2
301: into
302: .Ar file1 .
303: As in
304: .Xr ed 1 ,
305: identical
306: pairs (where num1 = num2) are abbreviated as a single
307: number.
308: .Sh ENVIRONMENT
1.2 deraadt 309: .Bl -tag -width TMPDIR
310: .It Ev TMPDIR
1.1 deraadt 311: If the environment variable
312: .Ev TMPDIR
313: exists,
1.2 deraadt 314: .Nm diff
315: will use the directory specified by
1.1 deraadt 316: .Ev TMPDIR
1.2 deraadt 317: as the temporary directory.
318: .El
1.1 deraadt 319: .Sh FILES
1.2 deraadt 320: .Bl -tag -width /usr/bin/diffh -compact
321: .It Pa /tmp/d?????
322: .It Pa /usr/bin/diffh
1.1 deraadt 323: Alternate algorithm version (used by option
324: .Fl h ) .
1.2 deraadt 325: .It Pa /usr/bin/diff
1.1 deraadt 326: for directory diffs
1.2 deraadt 327: .It Pa /usr/bin/pr
1.1 deraadt 328: used by the
329: .Fl l
330: option.
1.2 deraadt 331: .El
1.1 deraadt 332: .Sh SEE ALSO
333: .Xr cmp 1 ,
334: .Xr cc 1 ,
335: .Xr comm 1 ,
336: .Xr ed 1 ,
337: .Xr diff3 1
1.2 deraadt 338: .br
339: .ne 1i
1.1 deraadt 340: .Sh DIAGNOSTICS
341: The
342: .Nm diff
343: utility exits with one of the following values:
1.2 deraadt 344: .Pp
345: .Bl -tag -width Ds -compact -offset indent
346: .It \&0
1.1 deraadt 347: No differences were found.
1.2 deraadt 348: .It \&1
1.1 deraadt 349: Differences were found.
1.2 deraadt 350: .It "\&>\&1"
1.1 deraadt 351: An error occurred.
1.2 deraadt 352: .El
1.1 deraadt 353: .Sh BUGS
354: The
355: .Fl f
356: and
357: .Fl e
358: options
359: do not provide special handling for lines on which the
360: first and only character is
361: .Dq Li \&. .
362: This can cause problems for
363: .Xr ed 1 .
364: .Pp
365: When comparing directories with the
366: .Fl b ,
367: .Fl w
368: or
369: .Fl i
370: options specified,
371: .Nm diff
372: first compares the files ala
373: .Ar cmp ,
374: and then decides to run the
375: .Nm diff
376: algorithm if they are not equal.
377: This may cause a small amount of spurious output if the files
378: then turn out to be identical because the only differences are
379: insignificant white space or case differences.
1.2 deraadt 380: .Sh HISTORY
381: A
382: .Nm
383: command appeared in
384: .At v6 .