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