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