xref: /openbsd-src/usr.bin/diff/diff.1 (revision 11efff7f3ac2b3cfeff0c0cddc14294d9b3aca4f)
1.\" $OpenBSD: diff.1,v 1.27 2004/12/09 18:56:10 millert Exp $
2.\"
3.\" Copyright (c) 1980, 1990, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
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.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
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.
29.\"
30.\"     @(#)diff.1	8.1 (Berkeley) 6/30/93
31.\"
32.Dd July 21, 2003
33.Dt DIFF 1
34.Os
35.Sh NAME
36.Nm diff
37.Nd differential file and directory comparator
38.Sh SYNOPSIS
39.Nm diff
40.Op Fl abdilpqtTw
41.Op Fl I Ar pattern
42.Oo
43.Fl c | e | f |
44.Fl n | u
45.Oc
46.Op Fl L Ar label
47.Ar file1 file2
48.Nm diff
49.Op Fl abdilpqtTw
50.Op Fl I Ar pattern
51.Op Fl L Ar label
52.Fl C Ar number
53.Ar file1 file2
54.Nm diff
55.Op Fl abdilqtw
56.Op Fl I Ar pattern
57.Fl D Ar string
58.Ar file1 file2
59.Nm diff
60.Op Fl abdilpqtTw
61.Op Fl I Ar pattern
62.Op Fl L Ar label
63.Fl U Ar number
64.Ar file1 file2
65.Nm diff
66.Op Fl abdilNPpqtTw
67.Op Fl I Ar pattern
68.Oo
69.Fl c | e | f |
70.Fl n | u
71.Oc
72.Bk -words
73.Op Fl L Ar label
74.Op Fl r
75.Op Fl s
76.Op Fl S Ar name
77.Op Fl X Ar file
78.Op Fl x Ar pattern
79.Ek
80.Ar dir1 dir2
81.Sh DESCRIPTION
82The
83.Nm
84utility compares the contents of
85.Ar file1
86and
87.Ar file2
88and writes to the standard output the list of changes necessary to
89convert one file into the other.
90No output is produced if the files are identical.
91.Pp
92Output options (mutually exclusive):
93.Bl -tag -width Ds
94.It Fl c
95Produces a diff with 3 lines of context.
96With
97.Fl c
98the output format is modified slightly:
99the output begins with identification of the files involved and
100their creation dates and then each change is separated
101by a line with fifteen
102.Li * Ns 's .
103The lines removed from
104.Ar file1
105are marked with
106.Sq \&-\ \& ;
107those added to
108.Ar file2
109are marked
110.Sq \+\ \& .
111Lines which are changed from one file to the other are marked in
112both files with
113.Sq !\ \& .
114Changes which lie within 3 lines of each other are grouped together on
115output.
116.It Fl e
117Produces output in a form suitable as input for the editor utility,
118.Xr ed 1 ,
119which can then be used to convert file1 into file2.
120.Pp
121Extra commands are added to the output when comparing directories with
122.Fl e ,
123so that the result is a
124.Xr sh 1
125script for converting text files which are common to the two directories
126from their state in
127.Ar dir1
128to their state in
129.Ar dir2 .
130.It Fl f
131Identical output to that of the
132.Fl e
133flag, but in reverse order.
134It cannot be digested by
135.Xr ed 1 .
136.It Fl n
137Produces a script similar to that of
138.Fl e ,
139but in the opposite order and with a count of changed lines on each
140insert or delete command.
141This is the form used by
142.Xr rcsdiff 1 .
143.It Fl q
144Just print a line when the files differ.
145Does not output a list of changes.
146.It Fl u
147Produces a
148.Em unified
149diff with 3 lines of context.
150A unified diff is similar to the context diff produced by the
151.Fl c
152option.
153However, unlike with
154.Fl c ,
155all lines to be changed (added and/or removed) are present in
156a single section.
157.It Fl C Ar number
158Like
159.Fl c
160but produces a diff with
161.Ar number
162lines of context.
163.It Fl D Ar string
164Creates a merged version of
165.Ar file1
166and
167.Ar file2
168on the standard output, with C preprocessor controls included so that
169a compilation of the result without defining
170.Ar string
171is equivalent to compiling
172.Ar file1 ,
173while defining
174.Ar string
175will yield
176.Ar file2 .
177.It Fl U Ar number
178Like
179.Fl u
180but produces a diff with
181.Ar number
182lines of context.
183.El
184.Pp
185Comparison options:
186.Bl -tag -width Ds
187.It Fl a
188Treat all files as
189.Tn ASCII .
190.It Fl b
191Causes trailing blanks (spaces and tabs) to be ignored, and other
192strings of blanks to compare equal.
193.It Fl d
194Try very hard to produce a diff as small as possible.
195This may consume a lot of processing power and memory when processing
196large files with many changes.
197.It Fl I Ar pattern
198Ignores changes, insertions, and deletions whose lines match the
199extended regular expression
200.Ar pattern .
201Multiple
202.Fl I
203patterns may be specified.
204All lines in the change must match some pattern for the change to be
205ignored.
206See
207.Xr re_format 7
208for more information on regular expression patterns.
209.It Fl i
210Ignores the case of letters.
211E.g.,
212.Dq A
213will compare equal to
214.Dq a .
215.It Fl l
216Long output format; each text file
217.Nm diff Ns \'d
218is piped through
219.Xr pr 1
220to paginate it;
221other differences are remembered and summarized
222after all text file differences are reported.
223.It Fl L Ar label
224Print
225.Ar label
226instead of the first (and second, if this option is specified twice)
227file name and time in the context or unified diff header.
228.It Fl p
229With unified and context diffs, show with each change
230the first 40 characters of the last line before the context beginning
231with a letter, an underscore or a dollar sign.
232For C source code following standard layout conventions, this will
233show the prototype of the function the change applies to.
234.It Fl t
235Will expand tabs in output lines.
236Normal or
237.Fl c
238output adds character(s) to the front of each line which may screw up
239the indentation of the original source lines and make the output listing
240difficult to interpret.
241This option will preserve the original source's indentation.
242.It Fl T
243Print a tab rather than a space before the rest of the line for the
244normal, context or unified output formats.
245This makes the alignment of tabs in the line consistent.
246.It Fl w
247Is similar to
248.Fl b
249but causes whitespace (blanks and tabs) to be totally ignored.
250E.g.,
251.Dq if (\ \&a == b \&)
252will compare equal to
253.Dq if(a==b) .
254.El
255.Pp
256Directory comparison options:
257.Bl -tag -width Ds
258.It Fl N
259If a file is found in only one directory, act as if it was found in the
260other directory too but was of zero size.
261.It Fl P
262If a file is found only in
263.Ar dir2 ,
264act as if it was found in
265.Ar dir1
266too but was of zero size.
267.It Fl r
268Causes application of
269.Nm
270recursively to common subdirectories encountered.
271.It Fl s
272Causes
273.Nm
274to report files which are the same, which are otherwise not mentioned.
275.It Fl S Ar name
276Re-starts a directory
277.Nm
278in the middle, beginning with file
279.Ar name .
280.It Fl X Ar file
281Exclude files and subdirectories from comparison whose basenames match
282lines in
283.Ar file .
284Multiple
285.Fl X
286options may be specified.
287.It Fl x Ar pattern
288Exclude files and subdirectories from comparison whose basenames match
289.Ar pattern .
290Patterns are matched using shell-style globbing via
291.Xr fnmatch 3 .
292Multiple
293.Fl x
294options may be specified.
295.El
296.Pp
297If both arguments are directories,
298.Nm
299sorts the contents of the directories by name, and then runs the
300regular file
301.Nm
302algorithm, producing a change list,
303on text files which are different.
304Binary files which differ,
305common subdirectories, and files which appear in only one directory
306are described as such.
307In directory mode only regular files and directories are compared.
308If a non-regular file such as a device special file or
309.Tn FIFO
310is encountered, a diagnostic message is printed.
311.Pp
312If only one of
313.Ar file1
314and
315.Ar file2
316is a directory,
317.Nm
318is applied to the non-directory file and the file contained in
319the directory file with a filename that is the same as the
320last component of the non-directory file.
321.Pp
322If either
323.Ar file1
324or
325.Ar file2
326is
327.Sq Fl ,
328the standard input is
329used in its place.
330.Ss Output Style
331The default (without
332.Fl e ,
333.Fl c ,
334or
335.Fl n
336.\" -C
337options)
338output contains lines of these forms, where
339.Va XX , YY , ZZ , QQ
340are line numbers respective of file order.
341.Pp
342.Bl -tag -width "XX,YYcZZ,QQ" -compact
343.It Li XX Ns Ic a Ns Li YY
344At (the end of) line
345.Va XX
346of
347.Ar file1 ,
348append the contents
349of line
350.Va YY
351of
352.Ar file2
353to make them equal.
354.It Li XX Ns Ic a Ns Li YY,ZZ
355Same as above, but append the range of lines,
356.Va YY
357through
358.Va ZZ
359of
360.Ar file2
361to line
362.Va XX
363of file1.
364.It Li XX Ns Ic d Ns Li YY
365At line
366.Va XX
367delete
368the line.
369The value
370.Va YY
371tells to which line the change would bring
372.Ar file1
373in line with
374.Ar file1 .
375.It Li XX,YY Ns Ic d Ns Li ZZ
376Delete the range of lines
377.Va XX
378through
379.Va YY
380in
381.Ar file1 .
382.It Li XX Ns Ic c Ns Li YY
383Change the line
384.Va XX
385in
386.Ar file1
387to the line
388.Va YY
389in
390.Ar file2 .
391.It Li XX,YY Ns Ic c Ns Li ZZ
392Replace the range of specified lines with the line
393.Va ZZ .
394.It Li XX,YY Ns Ic c Ns Li ZZ,QQ
395Replace the range
396.Va XX , Ns Va YY
397from
398.Ar file1
399with the range
400.Va ZZ , Ns Va QQ
401from
402.Ar file2 .
403.El
404.Pp
405These lines resemble
406.Xr ed 1
407subcommands to convert
408.Ar file1
409into
410.Ar file2 .
411The line numbers before the action letters pertain to
412.Ar file1 ;
413those after pertain to
414.Ar file2 .
415Thus, by exchanging
416.Ic a
417for
418.Ic d
419and reading the line in reverse order, one can also
420determine how to convert
421.Ar file2
422into
423.Ar file1 .
424As in
425.Xr ed 1 ,
426identical
427pairs (where num1 = num2) are abbreviated as a single
428number.
429.Sh ENVIRONMENT
430.Bl -tag -width TMPDIR
431.It Ev TMPDIR
432If the environment variable
433.Ev TMPDIR
434exists,
435.Nm
436will use the directory specified by
437.Ev TMPDIR
438as the temporary directory.
439.El
440.Sh FILES
441.Bl -tag -width /tmp/diff.XXXXXXXX -compact
442.It Pa /tmp/diff. Ns Ar XXXXXXXX
443Temporary file used when comparing a device or the standard input.
444Note that the temporary file is unlinked as soon as it is created
445so it will not show up in a directory listing.
446.El
447.Sh DIAGNOSTICS
448The
449.Nm
450utility exits with one of the following values:
451.Pp
452.Bl -tag -width Ds -compact -offset indent
453.It \&0
454No differences were found.
455.It \&1
456Differences were found.
457.It \*[Gt]\&1
458An error occurred.
459.El
460.Sh SEE ALSO
461.Xr cmp 1 ,
462.Xr comm 1 ,
463.Xr diff3 1 ,
464.Xr ed 1 ,
465.Xr pr 1 ,
466.Xr fnmatch 3 ,
467.Xr re_format 7
468.Sh STANDARDS
469The
470.Nm
471utility is expected to be a superset of the
472.St -p1003.1-2001
473specification.
474.Sh HISTORY
475A
476.Nm
477command appeared in
478.At v6 .
479.Sh BUGS
480When comparing directories with the
481.Fl b ,
482.Fl w
483or
484.Fl i
485options specified,
486.Nm
487first compares the files ala
488.Xr cmp 1 ,
489and then decides to run the
490.Nm
491algorithm if they are not equal.
492This may cause a small amount of spurious output if the files
493then turn out to be identical because the only differences are
494insignificant whitespace or case differences.
495