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