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 April 27, 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 --expand-tabs
 188 .Op --ignore-all-blanks
 189 .Op --ignore-blank-lines
 190 .Op --ignore-case
 191 .Op --minimal
 192 .Op --no-ignore-file-name-case
 193 .Op --strip-trailing-cr
 194 .Op --suppress-common-lines
 195 .Op --tabsize Ar number
 196 .Op --text
 197 .Op --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
 281 .Xr rcsdiff 1 .
 282 .It Fl q -brief
 283 Just print a line when the files differ.
 284 Does not output a list of changes.
 285 .It Fl U Ar number Fl -unified Ar number
 286 Like
 287 .Fl u
 288 but produces a diff with
 289 .Ar number
 290 lines of context.
 291 .It Fl u
 292 Produces a
 293 .Em unified
 294 diff with 3 lines of context.
 295 A unified diff is similar to the context diff produced by the
 296 .Fl c
 297 option.
 298 However, unlike with
 299 .Fl c ,
 300 all lines to be changed (added and/or removed) are present in
 301 a single section.
 302 .It Fl y Fl -side-by-side
 303 Output in two columns with a marker between them.
 304 The marker can be one
 305 of the following:
 306 .Pp
 307 .Bl -tag -width Ds -offset indent -compact
 308 .It space
 309 Corresponding lines are identical.
 310 .It '|'
 311 Corresponding lines are different.
 312 .It '<'
 313 Files differ and only the first file contains the line.
 314 .It '>'
 315 Files differ and only the second file contains the line.
 316 .El
 317 .El
 318 .Pp
 319 Comparison options:
 320 .Bl -tag -width Ds
 321 .It Fl a -text
 322 Treat all files as ASCII text.
 323 Normally
 324 .Nm
 325 will simply print
 326 .Dq Binary files ... differ
 327 if files contain binary characters.
 328 Use of this option forces
 329 .Nm
 330 to produce a diff.
 331 .It Fl B Fl -ignore-blank-lines
 332 Causes chunks that include only blank lines to be ignored.
 333 .It Fl b
 334 Causes trailing blanks (spaces and tabs) to be ignored, and other
 335 strings of blanks to compare equal.
 336 .It Fl d -minimal
 337 Try very hard to produce a diff as small as possible.
 338 This may consume a lot of processing power and memory when processing
 339 large files with many changes.
 340 .It Fl I Ar pattern Fl -ignore-matching-lines Ar pattern
 341 Ignores changes, insertions, and deletions whose lines match the
 342 extended regular expression
 343 .Ar pattern .
 344 Multiple
 345 .Fl I
 346 patterns may be specified.
 347 All lines in the change must match some pattern for the change to be
 348 ignored.
 349 See
 350 .Xr re_format 7
 351 for more information on regular expression patterns.
 352 .It Fl i -ignore-case
 353 Ignores the case of letters.
 354 E.g.,
 355 .Dq A
 356 will compare equal to
 357 .Dq a .
 358 .It Fl l -paginate
 359 Pass the output through
 360 .Xr pr 1
 361 to paginate it.
 362 .It Fl L Ar label Fl -label Ar label
 363 Print
 364 .Ar label
 365 instead of the first (and second, if this option is specified twice)
 366 file name and time in the context or unified diff header.
 367 .It Fl p -show-c-function
 368 With unified and context diffs, show with each change
 369 the first 40 characters of the last line before the context beginning
 370 with a letter, an underscore or a dollar sign.
 371 For C source code following standard layout conventions, this will
 372 show the prototype of the function the change applies to.
 373 .It Fl T -initial-tab
 374 Print a tab rather than a space before the rest of the line for the
 375 normal, context or unified output formats.
 376 This makes the alignment of tabs in the line consistent.
 377 .It Fl t -expand-tabs
 378 Will expand tabs in output lines.
 379 Normal or
 380 .Fl c
 381 output adds character(s) to the front of each line which may screw up
 382 the indentation of the original source lines and make the output listing
 383 difficult to interpret.
 384 This option will preserve the original source's indentation.
 385 .It Fl w -ignore-all-blanks
 386 Is similar to
 387 .Fl b -ignore-space-change
 388 but causes whitespace (blanks and tabs) to be totally ignored.
 389 E.g.,
 390 .Dq if (\ \&a == b \&)
 391 will compare equal to
 392 .Dq if(a==b) .
 393 .It Fl W Ar number Fl -width Ar number
 394 Output at most
 395 .Ar number
 396 columns when using side by side format.
 397 The default value is 130.
 398 .It Fl -changed-group-format Ar GFMT
 399 Format input groups in the provided
 400 .Pp
 401 the format is a string with special keywords:
 402 .Bl -tag -width %<
 403 .It %<
 404 lines from FILE1
 405 .It %<
 406 lines from FILE2
 407 .El
 408 .It Fl -ignore-file-name-case
 409 ignore case when comparing file names
 410 .It Fl -no-ignore-file-name-case
 411 do not ignore case wen comparing file names (default)
 412 .It Fl -normal
 413 default diff output
 414 .It Fl -speed-large-files
 415 stub option for compatibility with GNU diff
 416 .It Fl -strip-trailing-cr
 417 strip carriage return on input files
 418 .It Fl -suppress-common-lines
 419 Do not output common lines when using the side by side format
 420 .It Fl -tabsize Ar number
 421 Number of spaces representing a tab (default 8)
 422 .El
 423 .Pp
 424 Directory comparison options:
 425 .Bl -tag -width Ds
 426 .It Fl N -new-file
 427 If a file is found in only one directory, act as if it was found in the
 428 other directory too but was of zero size.
 429 .It Fl P -unidirectional-new-file
 430 If a file is found only in
 431 .Ar dir2 ,
 432 act as if it was found in
 433 .Ar dir1
 434 too but was of zero size.
 435 .It Fl r -recursive
 436 Causes application of
 437 .Nm
 438 recursively to common subdirectories encountered.
 439 .It Fl S Ar name Fl -starting-file Ar name
 440 Re-starts a directory
 441 .Nm
 442 in the middle, beginning with file
 443 .Ar name .
 444 .It Fl s -report-identical-files
 445 Causes
 446 .Nm
 447 to report files which are the same, which are otherwise not mentioned.
 448 .It Fl X Ar file Fl -exclude-from Ar file
 449 Exclude files and subdirectories from comparison whose basenames match
 450 lines in
 451 .Ar file .
 452 Multiple
 453 .Fl X
 454 options may be specified.
 455 .It Fl x Ar pattern Fl -exclude Ar pattern
 456 Exclude files and subdirectories from comparison whose basenames match
 457 .Ar pattern .
 458 Patterns are matched using shell-style globbing via
 459 .Xr fnmatch 3 .
 460 Multiple
 461 .Fl x
 462 options may be specified.
 463 .El
 464 .Pp
 465 If both arguments are directories,
 466 .Nm
 467 sorts the contents of the directories by name, and then runs the
 468 regular file
 469 .Nm
 470 algorithm, producing a change list,
 471 on text files which are different.
 472 Binary files which differ,
 473 common subdirectories, and files which appear in only one directory
 474 are described as such.
 475 In directory mode only regular files and directories are compared.
 476 If a non-regular file such as a device special file or FIFO is encountered,
 477 a diagnostic message is printed.
 478 .Pp
 479 If only one of
 480 .Ar file1
 481 and
 482 .Ar file2
 483 is a directory,
 484 .Nm
 485 is applied to the non-directory file and the file contained in
 486 the directory file with a filename that is the same as the
 487 last component of the non-directory file.
 488 .Pp
 489 If either
 490 .Ar file1
 491 or
 492 .Ar file2
 493 is
 494 .Sq - ,
 495 the standard input is
 496 used in its place.
 497 .Ss Output Style
 498 The default (without
 499 .Fl e ,
 500 .Fl c ,
 501 or
 502 .Fl n -rcs
 503 .\" -C
 504 options)
 505 output contains lines of these forms, where
 506 .Va XX , YY , ZZ , QQ
 507 are line numbers respective of file order.
 508 .Pp
 509 .Bl -tag -width "XX,YYcZZ,QQ" -compact
 510 .It Li XX Ns Ic a Ns Li YY
 511 At (the end of) line
 512 .Va XX
 513 of
 514 .Ar file1 ,
 515 append the contents
 516 of line
 517 .Va YY
 518 of
 519 .Ar file2
 520 to make them equal.
 521 .It Li XX Ns Ic a Ns Li YY,ZZ
 522 Same as above, but append the range of lines,
 523 .Va YY
 524 through
 525 .Va ZZ
 526 of
 527 .Ar file2
 528 to line
 529 .Va XX
 530 of file1.
 531 .It Li XX Ns Ic d Ns Li YY
 532 At line
 533 .Va XX
 534 delete
 535 the line.
 536 The value
 537 .Va YY
 538 tells to which line the change would bring
 539 .Ar file1
 540 in line with
 541 .Ar file2 .
 542 .It Li XX,YY Ns Ic d Ns Li ZZ
 543 Delete the range of lines
 544 .Va XX
 545 through
 546 .Va YY
 547 in
 548 .Ar file1 .
 549 .It Li XX Ns Ic c Ns Li YY
 550 Change the line
 551 .Va XX
 552 in
 553 .Ar file1
 554 to the line
 555 .Va YY
 556 in
 557 .Ar file2 .
 558 .It Li XX,YY Ns Ic c Ns Li ZZ
 559 Replace the range of specified lines with the line
 560 .Va ZZ .
 561 .It Li XX,YY Ns Ic c Ns Li ZZ,QQ
 562 Replace the range
 563 .Va XX , Ns Va YY
 564 from
 565 .Ar file1
 566 with the range
 567 .Va ZZ , Ns Va QQ
 568 from
 569 .Ar file2 .
 570 .El
 571 .Pp
 572 These lines resemble
 573 .Xr ed 1
 574 subcommands to convert
 575 .Ar file1
 576 into
 577 .Ar file2 .
 578 The line numbers before the action letters pertain to
 579 .Ar file1 ;
 580 those after pertain to
 581 .Ar file2 .
 582 Thus, by exchanging
 583 .Ic a
 584 for
 585 .Ic d
 586 and reading the line in reverse order, one can also
 587 determine how to convert
 588 .Ar file2
 589 into
 590 .Ar file1 .
 591 As in
 592 .Xr ed 1 ,
 593 identical
 594 pairs (where num1 = num2) are abbreviated as a single
 595 number.
 596 .Sh FILES
 597 .Bl -tag -width /tmp/diff.XXXXXXXX -compact
 598 .It Pa /tmp/diff.XXXXXXXX
 599 Temporary file used when comparing a device or the standard input.
 600 Note that the temporary file is unlinked as soon as it is created
 601 so it will not show up in a directory listing.
 602 .El
 603 .Sh EXIT STATUS
 604 The
 605 .Nm
 606 utility exits with one of the following values:
 607 .Pp
 608 .Bl -tag -width Ds -offset indent -compact
 609 .It 0
 610 No differences were found.
 611 .It 1
 612 Differences were found.
 613 .It >1
 614 An error occurred.
 615 .El
 616 .Sh SEE ALSO
 617 .Xr cmp 1 ,
 618 .Xr comm 1 ,
 619 .Xr diff3 1 ,
 620 .Xr ed 1 ,
 621 .Xr patch 1 ,
 622 .Xr pr 1 ,
 623 .Xr sdiff 1
 624 .Rs
 625 .%A James W. Hunt
 626 .%A M. Douglas McIlroy
 627 .%T "An Algorithm for Differential File Comparison"
 628 .%J Computing Science Technical Report
 629 .%Q Bell Laboratories 41
 630 .%D June 1976
 631 .Re
 632 .Sh STANDARDS
 633 The
 634 .Nm
 635 utility is compliant with the
 636 .St -p1003.1-2008
 637 specification.
 638 .Pp
 639 The flags
 640 .Op Fl aDdIiLlNnPpqSsTtwXx
 641 are extensions to that specification.
 642 .Sh HISTORY
 643 A
 644 .Nm
 645 command appeared in
 646 .At v6 .