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