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