usr.bin/diff/diff.1

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