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