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