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