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