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