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 February 07, 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
  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
  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
 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
 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
 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
 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. 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
 322 .Tn ASCII
 323 text.
 324 Normally
 325 .Nm
 326 will simply print
 327 .Dq Binary files ... differ
 328 if files contain binary characters.
 329 Use of this option forces
 330 .Nm
 331 to produce a diff.
 332 .It Fl B Fl -ignore-blank-lines
 333 Causes chunks that include only blank lines to be ignored.
 334 .It Fl b
 335 Causes trailing blanks (spaces and tabs) to be ignored, and other
 336 strings of blanks to compare equal.
 337 .It Fl d -minimal
 338 Try very hard to produce a diff as small as possible.
 339 This may consume a lot of processing power and memory when processing
 340 large files with many changes.
 341 .It Fl I Ar pattern Fl -ignore-matching-lines Ar pattern
 342 Ignores changes, insertions, and deletions whose lines match the
 343 extended regular expression
 344 .Ar pattern .
 345 Multiple
 346 .Fl I
 347 patterns may be specified.
 348 All lines in the change must match some pattern for the change to be
 349 ignored.
 350 See
 351 .Xr re_format 7
 352 for more information on regular expression patterns.
 353 .It Fl i -ignore-case
 354 Ignores the case of letters.
 355 E.g.,
 356 .Dq A
 357 will compare equal to
 358 .Dq a .
 359 .It Fl l -paginate
 360 Pass the output through
 361 .Xr pr 1
 362 to paginate it.
 363 .It Fl L Ar label Fl -label Ar label
 364 Print
 365 .Ar label
 366 instead of the first (and second, if this option is specified twice)
 367 file name and time in the context or unified diff header.
 368 .It Fl p -show-c-function
 369 With unified and context diffs, show with each change
 370 the first 40 characters of the last line before the context beginning
 371 with a letter, an underscore or a dollar sign.
 372 For C source code following standard layout conventions, this will
 373 show the prototype of the function the change applies to.
 374 .It Fl T -initial-tab
 375 Print a tab rather than a space before the rest of the line for the
 376 normal, context or unified output formats.
 377 This makes the alignment of tabs in the line consistent.
 378 .It Fl t -expand-tabs
 379 Will expand tabs in output lines.
 380 Normal or
 381 .Fl c
 382 output adds character(s) to the front of each line which may screw up
 383 the indentation of the original source lines and make the output listing
 384 difficult to interpret.
 385 This option will preserve the original source's indentation.
 386 .It Fl w -ignore-all-blanks
 387 Is similar to
 388 .Fl b -ignore-space-change
 389 but causes whitespace (blanks and tabs) to be totally ignored.
 390 E.g.,
 391 .Dq if (\ \&a == b \&)
 392 will compare equal to
 393 .Dq if(a==b) .
 394 .It Fl W Ar number Fl -width Ar number
 395 Output at most
 396 .Ar number
 397 columns when using side by side format. 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
 477 .Tn FIFO
 478 is encountered, a diagnostic message is printed.
 479 .Pp
 480 If only one of
 481 .Ar file1
 482 and
 483 .Ar file2
 484 is a directory,
 485 .Nm
 486 is applied to the non-directory file and the file contained in
 487 the directory file with a filename that is the same as the
 488 last component of the non-directory file.
 489 .Pp
 490 If either
 491 .Ar file1
 492 or
 493 .Ar file2
 494 is
 495 .Sq - ,
 496 the standard input is
 497 used in its place.
 498 .Ss Output Style
 499 The default (without
 500 .Fl e ,
 501 .Fl c ,
 502 or
 503 .Fl n -rcs
 504 .\" -C
 505 options)
 506 output contains lines of these forms, where
 507 .Va XX , YY , ZZ , QQ
 508 are line numbers respective of file order.
 509 .Pp
 510 .Bl -tag -width "XX,YYcZZ,QQ" -compact
 511 .It Li XX Ns Ic a Ns Li YY
 512 At (the end of) line
 513 .Va XX
 514 of
 515 .Ar file1 ,
 516 append the contents
 517 of line
 518 .Va YY
 519 of
 520 .Ar file2
 521 to make them equal.
 522 .It Li XX Ns Ic a Ns Li YY,ZZ
 523 Same as above, but append the range of lines,
 524 .Va YY
 525 through
 526 .Va ZZ
 527 of
 528 .Ar file2
 529 to line
 530 .Va XX
 531 of file1.
 532 .It Li XX Ns Ic d Ns Li YY
 533 At line
 534 .Va XX
 535 delete
 536 the line.
 537 The value
 538 .Va YY
 539 tells to which line the change would bring
 540 .Ar file1
 541 in line with
 542 .Ar file2 .
 543 .It Li XX,YY Ns Ic d Ns Li ZZ
 544 Delete the range of lines
 545 .Va XX
 546 through
 547 .Va YY
 548 in
 549 .Ar file1 .
 550 .It Li XX Ns Ic c Ns Li YY
 551 Change the line
 552 .Va XX
 553 in
 554 .Ar file1
 555 to the line
 556 .Va YY
 557 in
 558 .Ar file2 .
 559 .It Li XX,YY Ns Ic c Ns Li ZZ
 560 Replace the range of specified lines with the line
 561 .Va ZZ .
 562 .It Li XX,YY Ns Ic c Ns Li ZZ,QQ
 563 Replace the range
 564 .Va XX , Ns Va YY
 565 from
 566 .Ar file1
 567 with the range
 568 .Va ZZ , Ns Va QQ
 569 from
 570 .Ar file2 .
 571 .El
 572 .Pp
 573 These lines resemble
 574 .Xr ed 1
 575 subcommands to convert
 576 .Ar file1
 577 into
 578 .Ar file2 .
 579 The line numbers before the action letters pertain to
 580 .Ar file1 ;
 581 those after pertain to
 582 .Ar file2 .
 583 Thus, by exchanging
 584 .Ic a
 585 for
 586 .Ic d
 587 and reading the line in reverse order, one can also
 588 determine how to convert
 589 .Ar file2
 590 into
 591 .Ar file1 .
 592 As in
 593 .Xr ed 1 ,
 594 identical
 595 pairs (where num1 = num2) are abbreviated as a single
 596 number.
 597 .Sh FILES
 598 .Bl -tag -width /tmp/diff.XXXXXXXX -compact
 599 .It Pa /tmp/diff. Ns Ar XXXXXXXX
 600 Temporary file used when comparing a device or the standard input.
 601 Note that the temporary file is unlinked as soon as it is created
 602 so it will not show up in a directory listing.
 603 .El
 604 .Sh EXIT STATUS
 605 The
 606 .Nm
 607 utility exits with one of the following values:
 608 .Pp
 609 .Bl -tag -width Ds -offset indent -compact
 610 .It 0
 611 No differences were found.
 612 .It 1
 613 Differences were found.
 614 .It >1
 615 An error occurred.
 616 .El
 617 .Sh SEE ALSO
 618 .Xr cmp 1 ,
 619 .Xr comm 1 ,
 620 .Xr diff3 1 ,
 621 .Xr ed 1 ,
 622 .Xr patch 1 ,
 623 .Xr pr 1 ,
 624 .Xr sdiff 1
 625 .Rs
 626 .%A James W. Hunt
 627 .%A M. Douglas McIlroy
 628 .%T "An Algorithm for Differential File Comparison"
 629 .%J Computing Science Technical Report
 630 .%Q Bell Laboratories 41
 631 .%D June 1976
 632 .Re
 633 .Sh STANDARDS
 634 The
 635 .Nm
 636 utility is compliant with the
 637 .St -p1003.1-2008
 638 specification.
 639 .Pp
 640 The flags
 641 .Op Fl aDdIiLlNnPpqSsTtwXx
 642 are extensions to that specification.
 643 .Sh HISTORY
 644 A
 645 .Nm
 646 command appeared in
 647 .At v6 .