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