1 .Dd 2015-03-02 2 .Dt DIFF 7 3 .Os 4 .Sh NAME 5 .Nm diff 6 .Nd Comparing and Merging Files 7 .Sh Comparing and Merging Files 8 .Sh Overview 9 Computer users often find occasion to ask how two files differ. Perhaps one 10 file is a newer version of the other file. Or maybe the two files started 11 out as identical copies but were changed by different people. 12 .Pp 13 You can use the 14 .Xr diff 15 command to show differences between two files, or each corresponding file 16 in two directories. 17 .Xr diff 18 outputs differences between files line by line in any of several formats, 19 selectable by command line options. This set of differences is often called 20 a 21 .Em diff 22 or 23 .Em patch . 24 For files that are identical, 25 .Xr diff 26 normally produces no output; for binary (non-text) files, 27 .Xr diff 28 normally reports only that they are different. 29 .Pp 30 You can use the 31 .Xr cmp 32 command to show the byte and line numbers where two files differ. 33 .Xr cmp 34 can also show all the bytes that differ between the two files, side by side. 35 A way to compare two files character by character is the Emacs command 36 .Li M-x compare-windows . 37 See Section.Dq Other Window , 38 for more information on that command. 39 .Pp 40 You can use the 41 .Xr diff3 42 command to show differences among three files. When two people have made independent 43 changes to a common original, 44 .Xr diff3 45 can report the differences between the original and the two changed versions, 46 and can produce a merged file that contains both persons' changes together 47 with warnings about conflicts. 48 .Pp 49 You can use the 50 .Xr sdiff 51 command to merge two files interactively. 52 .Pp 53 You can use the set of differences produced by 54 .Xr diff 55 to distribute updates to text files (such as program source code) to other 56 people. This method is especially useful when the differences are small compared 57 to the complete files. Given 58 .Xr diff 59 output, you can use the 60 .Xr patch 61 program to update, or 62 .Em patch , 63 a copy of the file. If you think of 64 .Xr diff 65 as subtracting one file from another to produce their difference, you can 66 think of 67 .Xr patch 68 as adding the difference to one file to reproduce the other. 69 .Pp 70 This manual first concentrates on making diffs, and later shows how to use 71 diffs to update files. 72 .Pp 73 GNU 74 .Xr diff 75 was written by Paul Eggert, Mike Haertel, David Hayes, Richard Stallman, and 76 Len Tower. Wayne Davison designed and implemented the unified output format. 77 The basic algorithm is described by Eugene W. Myers in \(lqAn O(ND) Difference 78 Algorithm and its Variations\(rq, 79 .Em Algorithmica 80 Vol. 1 No. 2, 1986, pp. 251--266; and in \(lqA File Comparison Program\(rq, Webb Miller 81 and Eugene W. Myers, 82 .Em Software---Practice and Experience 83 Vol. 15 No. 11, 1985, pp. 1025--1040. The algorithm was independently discovered 84 as described by E. Ukkonen in \(lqAlgorithms for Approximate String Matching\(rq, 85 .Em Information and Control 86 Vol. 64, 1985, pp. 100--118. Unless the 87 .Op --minimal 88 option is used, 89 .Xr diff 90 uses a heuristic by Paul Eggert that limits the cost to O(N^1.5 log N) at 91 the price of producing suboptimal output for large inputs with many differences. 92 Related algorithms are surveyed by Alfred V. Aho in section 6.3 of \(lqAlgorithms 93 for Finding Patterns in Strings\(rq, 94 .Em Handbook of Theoretical Computer Science 95 (Jan Van Leeuwen, ed.), Vol. A, 96 .Em Algorithms and Complexity , 97 Elsevier/MIT Press, 1990, pp. 255--300. 98 .Pp 99 GNU 100 .Xr diff3 101 was written by Randy Smith. GNU 102 .Xr sdiff 103 was written by Thomas Lord. GNU 104 .Xr cmp 105 was written by Torbj\(:orn Granlund and David MacKenzie. 106 .Pp 107 GNU 108 .Xr patch 109 was written mainly by Larry Wall and Paul Eggert; several GNU enhancements 110 were contributed by Wayne Davison and David MacKenzie. Parts of this manual 111 are adapted from a manual page written by Larry Wall, with his permission. 112 .Pp 113 .Sh What Comparison Means 114 There are several ways to think about the differences between two files. One 115 way to think of the differences is as a series of lines that were deleted 116 from, inserted in, or changed in one file to produce the other file. 117 .Xr diff 118 compares two files line by line, finds groups of lines that differ, and reports 119 each group of differing lines. It can report the differing lines in several 120 formats, which have different purposes. 121 .Pp 122 GNU 123 .Xr diff 124 can show whether files are different without detailing the differences. It 125 also provides ways to suppress certain kinds of differences that are not important 126 to you. Most commonly, such differences are changes in the amount of white 127 space between words or lines. 128 .Xr diff 129 also provides ways to suppress differences in alphabetic case or in lines 130 that match a regular expression that you provide. These options can accumulate; 131 for example, you can ignore changes in both white space and alphabetic case. 132 .Pp 133 Another way to think of the differences between two files is as a sequence 134 of pairs of bytes that can be either identical or different. 135 .Xr cmp 136 reports the differences between two files byte by byte, instead of line by 137 line. As a result, it is often more useful than 138 .Xr diff 139 for comparing binary files. For text files, 140 .Xr cmp 141 is useful mainly when you want to know only whether two files are identical, 142 or whether one file is a prefix of the other. 143 .Pp 144 To illustrate the effect that considering changes byte by byte can have compared 145 with considering them line by line, think of what happens if a single newline 146 character is added to the beginning of a file. If that file is then compared 147 with an otherwise identical file that lacks the newline at the beginning, 148 .Xr diff 149 will report that a blank line has been added to the file, while 150 .Xr cmp 151 will report that almost every byte of the two files differs. 152 .Pp 153 .Xr diff3 154 normally compares three input files line by line, finds groups of lines that 155 differ, and reports each group of differing lines. Its output is designed 156 to make it easy to inspect two different sets of changes to the same file. 157 .Pp 158 .Ss Hunks 159 When comparing two files, 160 .Xr diff 161 finds sequences of lines common to both files, interspersed with groups of 162 differing lines called 163 .Em hunks . 164 Comparing two identical files yields one sequence of common lines and no hunks, 165 because no lines differ. Comparing two entirely different files yields no 166 common lines and one large hunk that contains all lines of both files. In 167 general, there are many ways to match up lines between two given files. 168 .Xr diff 169 tries to minimize the total hunk size by finding large sequences of common 170 lines interspersed with small hunks of differing lines. 171 .Pp 172 For example, suppose the file 173 .Pa F 174 contains the three lines 175 .Li a , 176 .Li b , 177 .Li c , 178 and the file 179 .Pa G 180 contains the same three lines in reverse order 181 .Li c , 182 .Li b , 183 .Li a . 184 If 185 .Xr diff 186 finds the line 187 .Li c 188 as common, then the command 189 .Li diff F G 190 produces this output: 191 .Pp 192 .Bd -literal -offset indent 193 1,2d0 194 < a 195 < b 196 3a2,3 197 > b 198 > a 199 .Ed 200 .Pp 201 But if 202 .Xr diff 203 notices the common line 204 .Li b 205 instead, it produces this output: 206 .Pp 207 .Bd -literal -offset indent 208 1c1 209 < a 210 --- 211 > c 212 3c3 213 < c 214 --- 215 > a 216 .Ed 217 .Pp 218 It is also possible to find 219 .Li a 220 as the common line. 221 .Xr diff 222 does not always find an optimal matching between the files; it takes shortcuts 223 to run faster. But its output is usually close to the shortest possible. You 224 can adjust this tradeoff with the 225 .Op -d 226 or 227 .Op --minimal 228 option (see Section 229 .Dq diff Performance ) . 230 .Pp 231 .Ss Suppressing Differences in Blank and Tab Spacing 232 The 233 .Op -E 234 or 235 .Op --ignore-tab-expansion 236 option ignores the distinction between tabs and spaces on input. A tab is 237 considered to be equivalent to the number of spaces to the next tab stop (see Section 238 .Dq Tabs ) . 239 .Pp 240 The 241 .Op -b 242 or 243 .Op --ignore-space-change 244 option is stronger. It ignores white space at line end, and considers all 245 other sequences of one or more white space characters within a line to be 246 equivalent. With this option, 247 .Xr diff 248 considers the following two lines to be equivalent, where 249 .Li $ 250 denotes the line end: 251 .Pp 252 .Bd -literal -offset indent 253 Here lyeth muche rychnesse in lytell space. -- John Heywood$ 254 Here lyeth muche rychnesse in lytell space. -- John Heywood $ 255 .Ed 256 .Pp 257 The 258 .Op -w 259 or 260 .Op --ignore-all-space 261 option is stronger still. It ignores differences even if one line has white 262 space where the other line has none. 263 .Em White space 264 characters include tab, newline, vertical tab, form feed, carriage return, 265 and space; some locales may define additional characters to be white space. 266 With this option, 267 .Xr diff 268 considers the following two lines to be equivalent, where 269 .Li $ 270 denotes the line end and 271 .Li ^M 272 denotes a carriage return: 273 .Pp 274 .Bd -literal -offset indent 275 Here lyeth muche rychnesse in lytell space.-- John Heywood$ 276 He relyeth much erychnes seinly tells pace. --John Heywood ^M$ 277 .Ed 278 .Pp 279 .Ss Suppressing Differences Whose Lines Are All Blank 280 The 281 .Op -B 282 or 283 .Op --ignore-blank-lines 284 option ignores changes that consist entirely of blank lines. With this option, 285 for example, a file containing 286 .Bd -literal -offset indent 287 1. A point is that which has no part. 288 289 2. A line is breadthless length. 290 -- Euclid, The Elements, I 291 .Ed 292 is considered identical to a file containing 293 .Bd -literal -offset indent 294 1. A point is that which has no part. 295 2. A line is breadthless length. 296 297 298 -- Euclid, The Elements, I 299 .Ed 300 .Pp 301 Normally this option affects only lines that are completely empty, but if 302 you also specify the 303 .Op -b 304 or 305 .Op --ignore-space-change 306 option, or the 307 .Op -w 308 or 309 .Op --ignore-all-space 310 option, lines are also affected if they look empty but contain white space. 311 In other words, 312 .Op -B 313 is equivalent to 314 .Li -I '^$' 315 by default, but it is equivalent to 316 .Op -I '^[[:space:]]*$' 317 if 318 .Op -b 319 or 320 .Op -w 321 is also specified. 322 .Pp 323 .Ss Suppressing Differences Whose Lines All Match a Regular Expression 324 To ignore insertions and deletions of lines that match a 325 .Xr grep 326 -style regular expression, use the 327 .Op -I Va regexp 328 or 329 .Op --ignore-matching-lines= Va regexp 330 option. You should escape regular expressions that contain shell metacharacters 331 to prevent the shell from expanding them. For example, 332 .Li diff -I '^[[:digit:]]' 333 ignores all changes to lines beginning with a digit. 334 .Pp 335 However, 336 .Op -I 337 only ignores the insertion or deletion of lines that contain the regular expression 338 if every changed line in the hunk---every insertion and every deletion---matches 339 the regular expression. In other words, for each nonignorable change, 340 .Xr diff 341 prints the complete set of changes in its vicinity, including the ignorable 342 ones. 343 .Pp 344 You can specify more than one regular expression for lines to ignore by using 345 more than one 346 .Op -I 347 option. 348 .Xr diff 349 tries to match each line against each regular expression. 350 .Pp 351 .Ss Suppressing Case Differences 352 GNU 353 .Xr diff 354 can treat lower case letters as equivalent to their upper case counterparts, 355 so that, for example, it considers 356 .Li Funky Stuff , 357 .Li funky STUFF , 358 and 359 .Li fUNKy stuFf 360 to all be the same. To request this, use the 361 .Op -i 362 or 363 .Op --ignore-case 364 option. 365 .Pp 366 .Ss Summarizing Which Files Differ 367 When you only want to find out whether files are different, and you don't 368 care what the differences are, you can use the summary output format. In this 369 format, instead of showing the differences between the files, 370 .Xr diff 371 simply reports whether files differ. The 372 .Op -q 373 or 374 .Op --brief 375 option selects this output format. 376 .Pp 377 This format is especially useful when comparing the contents of two directories. 378 It is also much faster than doing the normal line by line comparisons, because 379 .Xr diff 380 can stop analyzing the files as soon as it knows that there are any differences. 381 .Pp 382 You can also get a brief indication of whether two files differ by using 383 .Xr cmp . 384 For files that are identical, 385 .Xr cmp 386 produces no output. When the files differ, by default, 387 .Xr cmp 388 outputs the byte and line number where the first difference occurs, or reports 389 that one file is a prefix of the other. You can use the 390 .Op -s , 391 .Op --quiet , 392 or 393 .Op --silent 394 option to suppress that information, so that 395 .Xr cmp 396 produces no output and reports whether the files differ using only its exit 397 status (see Section 398 .Dq Invoking cmp ) . 399 .Pp 400 Unlike 401 .Xr diff , 402 .Xr cmp 403 cannot compare directories; it can only compare two files. 404 .Pp 405 .Ss Binary Files and Forcing Text Comparisons 406 If 407 .Xr diff 408 thinks that either of the two files it is comparing is binary (a non-text 409 file), it normally treats that pair of files much as if the summary output 410 format had been selected (see Section 411 .Dq Brief ) , 412 and reports only that the binary files are different. This is because line 413 by line comparisons are usually not meaningful for binary files. 414 .Pp 415 .Xr diff 416 determines whether a file is text or binary by checking the first few bytes 417 in the file; the exact number of bytes is system dependent, but it is typically 418 several thousand. If every byte in that part of the file is non-null, 419 .Xr diff 420 considers the file to be text; otherwise it considers the file to be binary. 421 .Pp 422 Sometimes you might want to force 423 .Xr diff 424 to consider files to be text. For example, you might be comparing text files 425 that contain null characters; 426 .Xr diff 427 would erroneously decide that those are non-text files. Or you might be comparing 428 documents that are in a format used by a word processing system that uses 429 null characters to indicate special formatting. You can force 430 .Xr diff 431 to consider all files to be text files, and compare them line by line, by 432 using the 433 .Op -a 434 or 435 .Op --text 436 option. If the files you compare using this option do not in fact contain 437 text, they will probably contain few newline characters, and the 438 .Xr diff 439 output will consist of hunks showing differences between long lines of whatever 440 characters the files contain. 441 .Pp 442 You can also force 443 .Xr diff 444 to report only whether files differ (but not how). Use the 445 .Op -q 446 or 447 .Op --brief 448 option for this. 449 .Pp 450 Normally, differing binary files count as trouble because the resulting 451 .Xr diff 452 output does not capture all the differences. This trouble causes 453 .Xr diff 454 to exit with status 2. However, this trouble cannot occur with the 455 .Op -a 456 or 457 .Op --text 458 option, or with the 459 .Op -q 460 or 461 .Op --brief 462 option, as these options both cause 463 .Xr diff 464 to generate a form of output that represents differences as requested. 465 .Pp 466 In operating systems that distinguish between text and binary files, 467 .Xr diff 468 normally reads and writes all data as text. Use the 469 .Op --binary 470 option to force 471 .Xr diff 472 to read and write binary data instead. This option has no effect on a POSIX-compliant 473 system like GNU or traditional Unix. However, many personal computer operating 474 systems represent the end of a line with a carriage return followed by a newline. 475 On such systems, 476 .Xr diff 477 normally ignores these carriage returns on input and generates them at the 478 end of each output line, but with the 479 .Op --binary 480 option 481 .Xr diff 482 treats each carriage return as just another input character, and does not 483 generate a carriage return at the end of each output line. This can be useful 484 when dealing with non-text files that are meant to be interchanged with POSIX-compliant 485 systems. 486 .Pp 487 The 488 .Op --strip-trailing-cr 489 causes 490 .Xr diff 491 to treat input lines that end in carriage return followed by newline as if 492 they end in plain newline. This can be useful when comparing text that is 493 imperfectly imported from many personal computer operating systems. This option 494 affects how lines are read, which in turn affects how they are compared and 495 output. 496 .Pp 497 If you want to compare two files byte by byte, you can use the 498 .Xr cmp 499 program with the 500 .Op -l 501 or 502 .Op --verbose 503 option to show the values of each differing byte in the two files. With GNU 504 .Xr cmp , 505 you can also use the 506 .Op -b 507 or 508 .Op --print-bytes 509 option to show the ASCII representation of those bytes.See Section 510 .Dq Invoking cmp , 511 for more information. 512 .Pp 513 If 514 .Xr diff3 515 thinks that any of the files it is comparing is binary (a non-text file), 516 it normally reports an error, because such comparisons are usually not useful. 517 .Xr diff3 518 uses the same test as 519 .Xr diff 520 to decide whether a file is binary. As with 521 .Xr diff , 522 if the input files contain a few non-text bytes but otherwise are like text 523 files, you can force 524 .Xr diff3 525 to consider all files to be text files and compare them line by line by using 526 the 527 .Op -a 528 or 529 .Op --text 530 option. 531 .Pp 532 .Sh Xr diff Output Formats 533 .Xr diff 534 has several mutually exclusive options for output format. The following sections 535 describe each format, illustrating how 536 .Xr diff 537 reports the differences between two sample input files. 538 .Pp 539 .Ss Two Sample Input Files 540 Here are two sample files that we will use in numerous examples to illustrate 541 the output of 542 .Xr diff 543 and how various options can change it. 544 .Pp 545 This is the file 546 .Pa lao : 547 .Pp 548 .Bd -literal -offset indent 549 The Way that can be told of is not the eternal Way; 550 The name that can be named is not the eternal name. 551 The Nameless is the origin of Heaven and Earth; 552 The Named is the mother of all things. 553 Therefore let there always be non-being, 554 so we may see their subtlety, 555 And let there always be being, 556 so we may see their outcome. 557 The two are the same, 558 But after they are produced, 559 they have different names. 560 .Ed 561 .Pp 562 This is the file 563 .Pa tzu : 564 .Pp 565 .Bd -literal -offset indent 566 The Nameless is the origin of Heaven and Earth; 567 The named is the mother of all things. 568 569 Therefore let there always be non-being, 570 so we may see their subtlety, 571 And let there always be being, 572 so we may see their outcome. 573 The two are the same, 574 But after they are produced, 575 they have different names. 576 They both may be called deep and profound. 577 Deeper and more profound, 578 The door of all subtleties! 579 .Ed 580 .Pp 581 In this example, the first hunk contains just the first two lines of 582 .Pa lao , 583 the second hunk contains the fourth line of 584 .Pa lao 585 opposing the second and third lines of 586 .Pa tzu , 587 and the last hunk contains just the last three lines of 588 .Pa tzu . 589 .Pp 590 .Ss Showing Differences in Their Context 591 Usually, when you are looking at the differences between files, you will also 592 want to see the parts of the files near the lines that differ, to help you 593 understand exactly what has changed. These nearby parts of the files are called 594 the 595 .Em context . 596 .Pp 597 GNU 598 .Xr diff 599 provides two output formats that show context around the differing lines: 600 .Em context format 601 and 602 .Em unified format . 603 It can optionally show in which function or section of the file the differing 604 lines are found. 605 .Pp 606 If you are distributing new versions of files to other people in the form 607 of 608 .Xr diff 609 output, you should use one of the output formats that show context so that 610 they can apply the diffs even if they have made small changes of their own 611 to the files. 612 .Xr patch 613 can apply the diffs in this case by searching in the files for the lines of 614 context around the differing lines; if those lines are actually a few lines 615 away from where the diff says they are, 616 .Xr patch 617 can adjust the line numbers accordingly and still apply the diff correctly.See Section 618 .Dq Imperfect , 619 for more information on using 620 .Xr patch 621 to apply imperfect diffs. 622 .Pp 623 .Em Context Format 624 .Pp 625 The context output format shows several lines of context around the lines 626 that differ. It is the standard format for distributing updates to source 627 code. 628 .Pp 629 To select this output format, use the 630 .Op -C Va lines , 631 .Op --context[= Va lines] , 632 or 633 .Op -c 634 option. The argument 635 .Va lines 636 that some of these options take is the number of lines of context to show. 637 If you do not specify 638 .Va lines , 639 it defaults to three. For proper operation, 640 .Xr patch 641 typically needs at least two lines of context. 642 .Pp 643 .No An Example of Context Format 644 .Pp 645 Here is the output of 646 .Li diff -c lao tzu 647 (see Section 648 .Dq Sample diff Input , 649 for the complete contents of the two files). Notice that up to three lines 650 that are not different are shown around each line that is different; they 651 are the context lines. Also notice that the first two hunks have run together, 652 because their contents overlap. 653 .Pp 654 .Bd -literal -offset indent 655 *** lao 2002-02-21 23:30:39.942229878 -0800 656 --- tzu 2002-02-21 23:30:50.442260588 -0800 657 *************** 658 *** 1,7 **** 659 - The Way that can be told of is not the eternal Way; 660 - The name that can be named is not the eternal name. 661 The Nameless is the origin of Heaven and Earth; 662 ! The Named is the mother of all things. 663 Therefore let there always be non-being, 664 so we may see their subtlety, 665 And let there always be being, 666 --- 1,6 ---- 667 The Nameless is the origin of Heaven and Earth; 668 ! The named is the mother of all things. 669 ! 670 Therefore let there always be non-being, 671 so we may see their subtlety, 672 And let there always be being, 673 *************** 674 *** 9,11 **** 675 --- 8,13 ---- 676 The two are the same, 677 But after they are produced, 678 they have different names. 679 + They both may be called deep and profound. 680 + Deeper and more profound, 681 + The door of all subtleties! 682 .Ed 683 .Pp 684 .No An Example of Context Format with Less Context 685 .Pp 686 Here is the output of 687 .Li diff -C 1 lao tzu 688 (see Section 689 .Dq Sample diff Input , 690 for the complete contents of the two files). Notice that at most one context 691 line is reported here. 692 .Pp 693 .Bd -literal -offset indent 694 *** lao 2002-02-21 23:30:39.942229878 -0800 695 --- tzu 2002-02-21 23:30:50.442260588 -0800 696 *************** 697 *** 1,5 **** 698 - The Way that can be told of is not the eternal Way; 699 - The name that can be named is not the eternal name. 700 The Nameless is the origin of Heaven and Earth; 701 ! The Named is the mother of all things. 702 Therefore let there always be non-being, 703 --- 1,4 ---- 704 The Nameless is the origin of Heaven and Earth; 705 ! The named is the mother of all things. 706 ! 707 Therefore let there always be non-being, 708 *************** 709 *** 11 **** 710 --- 10,13 ---- 711 they have different names. 712 + They both may be called deep and profound. 713 + Deeper and more profound, 714 + The door of all subtleties! 715 .Ed 716 .Pp 717 .No Detailed Description of Context Format 718 .Pp 719 The context output format starts with a two-line header, which looks like 720 this: 721 .Pp 722 .Bd -literal -offset indent 723 *** from-file from-file-modification-time 724 --- to-file to-file-modification time 725 .Ed 726 .Pp 727 The time stamp normally looks like 728 .Li 2002-02-21 23:30:39.942229878 -0800 729 to indicate the date, time with fractional seconds, and time zone in 730 .Lk ftp://ftp.isi.edu/in-notes/rfc2822.txt . 731 (The fractional seconds are omitted on hosts that do not support fractional 732 time stamps.) However, a traditional time stamp like 733 .Li Thu Feb 21 23:30:39 2002 734 is used if the 735 .Ev LC_TIME 736 locale category is either 737 .Li C 738 or 739 .Li POSIX . 740 .Pp 741 You can change the header's content with the 742 .Op --label= Va label 743 option; see Alternate Names. 744 .Pp 745 Next come one or more hunks of differences; each hunk shows one area where 746 the files differ. Context format hunks look like this: 747 .Pp 748 .Bd -literal -offset indent 749 *************** 750 *** from-file-line-numbers **** 751 from-file-line 752 from-file-line... 753 --- to-file-line-numbers ---- 754 to-file-line 755 to-file-line... 756 .Ed 757 .Pp 758 If a hunk contains two or more lines, its line numbers look like 759 .Li Va start, Va end . 760 Otherwise only its end line number appears. An empty hunk is considered to 761 end at the line that precedes the hunk. 762 .Pp 763 The lines of context around the lines that differ start with two space characters. 764 The lines that differ between the two files start with one of the following 765 indicator characters, followed by a space character: 766 .Pp 767 .Bl -tag -width Ds 768 .It ! 769 A line that is part of a group of one or more lines that changed between the 770 two files. There is a corresponding group of lines marked with 771 .Li ! 772 in the part of this hunk for the other file. 773 .Pp 774 .It + 775 An \(lqinserted\(rq line in the second file that corresponds to nothing in the first 776 file. 777 .Pp 778 .It - 779 A \(lqdeleted\(rq line in the first file that corresponds to nothing in the second 780 file. 781 .El 782 .Pp 783 If all of the changes in a hunk are insertions, the lines of 784 .Va from-file 785 are omitted. If all of the changes are deletions, the lines of 786 .Va to-file 787 are omitted. 788 .Pp 789 .Em Unified Format 790 .Pp 791 The unified output format is a variation on the context format that is more 792 compact because it omits redundant context lines. To select this output format, 793 use the 794 .Op -U Va lines , 795 .Op --unified[= Va lines] , 796 or 797 .Op -u 798 option. The argument 799 .Va lines 800 is the number of lines of context to show. When it is not given, it defaults 801 to three. 802 .Pp 803 At present, only GNU 804 .Xr diff 805 can produce this format and only GNU 806 .Xr patch 807 can automatically apply diffs in this format. For proper operation, 808 .Xr patch 809 typically needs at least three lines of context. 810 .Pp 811 .No An Example of Unified Format 812 .Pp 813 Here is the output of the command 814 .Li diff -u lao tzu 815 (see Section 816 .Dq Sample diff Input , 817 for the complete contents of the two files): 818 .Pp 819 .Bd -literal -offset indent 820 --- lao 2002-02-21 23:30:39.942229878 -0800 821 +++ tzu 2002-02-21 23:30:50.442260588 -0800 822 @@ -1,7 +1,6 @@ 823 -The Way that can be told of is not the eternal Way; 824 -The name that can be named is not the eternal name. 825 The Nameless is the origin of Heaven and Earth; 826 -The Named is the mother of all things. 827 +The named is the mother of all things. 828 + 829 Therefore let there always be non-being, 830 so we may see their subtlety, 831 And let there always be being, 832 @@ -9,3 +8,6 @@ 833 The two are the same, 834 But after they are produced, 835 they have different names. 836 +They both may be called deep and profound. 837 +Deeper and more profound, 838 +The door of all subtleties! 839 .Ed 840 .Pp 841 .No Detailed Description of Unified Format 842 .Pp 843 The unified output format starts with a two-line header, which looks like 844 this: 845 .Pp 846 .Bd -literal -offset indent 847 --- from-file from-file-modification-time 848 +++ to-file to-file-modification-time 849 .Ed 850 .Pp 851 The time stamp looks like 852 .Li 2002-02-21 23:30:39.942229878 -0800 853 to indicate the date, time with fractional seconds, and time zone. The fractional 854 seconds are omitted on hosts that do not support fractional time stamps. 855 .Pp 856 You can change the header's content with the 857 .Op --label= Va label 858 option; seeSee Section 859 .Dq Alternate Names . 860 .Pp 861 Next come one or more hunks of differences; each hunk shows one area where 862 the files differ. Unified format hunks look like this: 863 .Pp 864 .Bd -literal -offset indent 865 @@ from-file-line-numbers to-file-line-numbers @@ 866 line-from-either-file 867 line-from-either-file... 868 .Ed 869 .Pp 870 If a hunk contains just one line, only its start line number appears. Otherwise 871 its line numbers look like 872 .Li Va start, Va count . 873 An empty hunk is considered to start at the line that follows the hunk. 874 .Pp 875 If a hunk and its context contain two or more lines, its line numbers look 876 like 877 .Li Va start, Va count . 878 Otherwise only its end line number appears. An empty hunk is considered to 879 end at the line that precedes the hunk. 880 .Pp 881 The lines common to both files begin with a space character. The lines that 882 actually differ between the two files have one of the following indicator 883 characters in the left print column: 884 .Pp 885 .Bl -tag -width Ds 886 .It + 887 A line was added here to the first file. 888 .Pp 889 .It - 890 A line was removed here from the first file. 891 .El 892 .Pp 893 .Em Showing Which Sections Differences Are in 894 .Pp 895 Sometimes you might want to know which part of the files each change falls 896 in. If the files are source code, this could mean which function was changed. 897 If the files are documents, it could mean which chapter or appendix was changed. 898 GNU 899 .Xr diff 900 can show this by displaying the nearest section heading line that precedes 901 the differing lines. Which lines are \(lqsection headings\(rq is determined by a regular 902 expression. 903 .Pp 904 .No Showing Lines That Match Regular Expressions 905 .Pp 906 To show in which sections differences occur for files that are not source 907 code for C or similar languages, use the 908 .Op -F Va regexp 909 or 910 .Op --show-function-line= Va regexp 911 option. 912 .Xr diff 913 considers lines that match the 914 .Xr grep 915 -style regular expression 916 .Va regexp 917 to be the beginning of a section of the file. Here are suggested regular expressions 918 for some common languages: 919 .Pp 920 .Bl -tag -width Ds 921 .It ^[[:alpha:]$_] 922 C, C++, Prolog 923 .It ^( 924 Lisp 925 .It ^@node 926 Texinfo 927 .El 928 .Pp 929 This option does not automatically select an output format; in order to use 930 it, you must select the context format (see Section 931 .Dq Context Format ) 932 or unified format (see Section 933 .Dq Unified Format ) . 934 In other output formats it has no effect. 935 .Pp 936 The 937 .Op -F 938 or 939 .Op --show-function-line 940 option finds the nearest unchanged line that precedes each hunk of differences 941 and matches the given regular expression. Then it adds that line to the end 942 of the line of asterisks in the context format, or to the 943 .Li @@ 944 line in unified format. If no matching line exists, this option leaves the 945 output for that hunk unchanged. If that line is more than 40 characters long, 946 it outputs only the first 40 characters. You can specify more than one regular 947 expression for such lines; 948 .Xr diff 949 tries to match each line against each regular expression, starting with the 950 last one given. This means that you can use 951 .Op -p 952 and 953 .Op -F 954 together, if you wish. 955 .Pp 956 .No Showing C Function Headings 957 .Pp 958 To show in which functions differences occur for C and similar languages, 959 you can use the 960 .Op -p 961 or 962 .Op --show-c-function 963 option. This option automatically defaults to the context output format (see Section 964 .Dq Context Format ) , 965 with the default number of lines of context. You can override that number 966 with 967 .Op -C Va lines 968 elsewhere in the command line. You can override both the format and the number 969 with 970 .Op -U Va lines 971 elsewhere in the command line. 972 .Pp 973 The 974 .Op -p 975 or 976 .Op --show-c-function 977 option is equivalent to 978 .Op -F '^[[:alpha:]$_]' 979 if the unified format is specified, otherwise 980 .Op -c -F '^[[:alpha:]$_]' 981 (see Section 982 .Dq Specified Headings ) . 983 GNU 984 .Xr diff 985 provides this option for the sake of convenience. 986 .Pp 987 .Em Showing Alternate File Names 988 .Pp 989 If you are comparing two files that have meaningless or uninformative names, 990 you might want 991 .Xr diff 992 to show alternate names in the header of the context and unified output formats. 993 To do this, use the 994 .Op --label= Va label 995 option. The first time you give this option, its argument replaces the name 996 and date of the first file in the header; the second time, its argument replaces 997 the name and date of the second file. If you give this option more than twice, 998 .Xr diff 999 reports an error. The 1000 .Op --label 1001 option does not affect the file names in the 1002 .Xr pr 1003 header when the 1004 .Op -l 1005 or 1006 .Op --paginate 1007 option is used (see Section 1008 .Dq Pagination ) . 1009 .Pp 1010 Here are the first two lines of the output from 1011 .Li diff -C 2 --label=original --label=modified lao tzu : 1012 .Pp 1013 .Bd -literal -offset indent 1014 *** original 1015 --- modified 1016 .Ed 1017 .Pp 1018 .Ss Showing Differences Side by Side 1019 .Xr diff 1020 can produce a side by side difference listing of two files. The files are 1021 listed in two columns with a gutter between them. The gutter contains one 1022 of the following markers: 1023 .Pp 1024 .Bl -tag -width Ds 1025 .It white space 1026 The corresponding lines are in common. That is, either the lines are identical, 1027 or the difference is ignored because of one of the 1028 .Op --ignore 1029 options (see Section 1030 .Dq White Space ) . 1031 .Pp 1032 .It Li | 1033 The corresponding lines differ, and they are either both complete or both 1034 incomplete. 1035 .Pp 1036 .It Li < 1037 The files differ and only the first file contains the line. 1038 .Pp 1039 .It Li > 1040 The files differ and only the second file contains the line. 1041 .Pp 1042 .It Li ( 1043 Only the first file contains the line, but the difference is ignored. 1044 .Pp 1045 .It Li ) 1046 Only the second file contains the line, but the difference is ignored. 1047 .Pp 1048 .It Li \e 1049 The corresponding lines differ, and only the first line is incomplete. 1050 .Pp 1051 .It Li / 1052 The corresponding lines differ, and only the second line is incomplete. 1053 .El 1054 .Pp 1055 Normally, an output line is incomplete if and only if the lines that it contains 1056 are incomplete;See Section 1057 .Dq Incomplete Lines . 1058 However, when an output line represents two differing lines, one might be 1059 incomplete while the other is not. In this case, the output line is complete, 1060 but its the gutter is marked 1061 .Li \e 1062 if the first line is incomplete, 1063 .Li / 1064 if the second line is. 1065 .Pp 1066 Side by side format is sometimes easiest to read, but it has limitations. 1067 It generates much wider output than usual, and truncates lines that are too 1068 long to fit. Also, it relies on lining up output more heavily than usual, 1069 so its output looks particularly bad if you use varying width fonts, nonstandard 1070 tab stops, or nonprinting characters. 1071 .Pp 1072 You can use the 1073 .Xr sdiff 1074 command to interactively merge side by side differences.See Section 1075 .Dq Interactive Merging , 1076 for more information on merging files. 1077 .Pp 1078 .Em Controlling Side by Side Format 1079 .Pp 1080 The 1081 .Op -y 1082 or 1083 .Op --side-by-side 1084 option selects side by side format. Because side by side output lines contain 1085 two input lines, the output is wider than usual: normally 130 print columns, 1086 which can fit onto a traditional printer line. You can set the width of the 1087 output with the 1088 .Op -W Va columns 1089 or 1090 .Op --width= Va columns 1091 option. The output is split into two halves of equal width, separated by a 1092 small gutter to mark differences; the right half is aligned to a tab stop 1093 so that tabs line up. Input lines that are too long to fit in half of an output 1094 line are truncated for output. 1095 .Pp 1096 The 1097 .Op --left-column 1098 option prints only the left column of two common lines. The 1099 .Op --suppress-common-lines 1100 option suppresses common lines entirely. 1101 .Pp 1102 .Em An Example of Side by Side Format 1103 .Pp 1104 Here is the output of the command 1105 .Li diff -y -W 72 lao tzu 1106 (see Section 1107 .Dq Sample diff Input , 1108 for the complete contents of the two files). 1109 .Pp 1110 .Bd -literal -offset indent 1111 The Way that can be told of is n < 1112 The name that can be named is no < 1113 The Nameless is the origin of He The Nameless is the origin of He 1114 The Named is the mother of all t | The named is the mother of all t 1115 > 1116 Therefore let there always be no Therefore let there always be no 1117 so we may see their subtlety, so we may see their subtlety, 1118 And let there always be being, And let there always be being, 1119 so we may see their outcome. so we may see their outcome. 1120 The two are the same, The two are the same, 1121 But after they are produced, But after they are produced, 1122 they have different names. they have different names. 1123 > They both may be called deep and 1124 > Deeper and more profound, 1125 > The door of all subtleties! 1126 .Ed 1127 .Pp 1128 .Ss Showing Differences Without Context 1129 The \(lqnormal\(rq 1130 .Xr diff 1131 output format shows each hunk of differences without any surrounding context. 1132 Sometimes such output is the clearest way to see how lines have changed, without 1133 the clutter of nearby unchanged lines (although you can get similar results 1134 with the context or unified formats by using 0 lines of context). However, 1135 this format is no longer widely used for sending out patches; for that purpose, 1136 the context format (see Section 1137 .Dq Context Format ) 1138 and the unified format (see Section 1139 .Dq Unified Format ) 1140 are superior. Normal format is the default for compatibility with older versions 1141 of 1142 .Xr diff 1143 and the POSIX standard. Use the 1144 .Op --normal 1145 option to select this output format explicitly. 1146 .Pp 1147 .Em An Example of Normal Format 1148 .Pp 1149 Here is the output of the command 1150 .Li diff lao tzu 1151 (see Section 1152 .Dq Sample diff Input , 1153 for the complete contents of the two files). Notice that it shows only the 1154 lines that are different between the two files. 1155 .Pp 1156 .Bd -literal -offset indent 1157 1,2d0 1158 < The Way that can be told of is not the eternal Way; 1159 < The name that can be named is not the eternal name. 1160 4c2,3 1161 < The Named is the mother of all things. 1162 --- 1163 > The named is the mother of all things. 1164 > 1165 11a11,13 1166 > They both may be called deep and profound. 1167 > Deeper and more profound, 1168 > The door of all subtleties! 1169 .Ed 1170 .Pp 1171 .Em Detailed Description of Normal Format 1172 .Pp 1173 The normal output format consists of one or more hunks of differences; each 1174 hunk shows one area where the files differ. Normal format hunks look like 1175 this: 1176 .Pp 1177 .Bd -literal -offset indent 1178 change-command 1179 < from-file-line 1180 < from-file-line... 1181 --- 1182 > to-file-line 1183 > to-file-line... 1184 .Ed 1185 .Pp 1186 There are three types of change commands. Each consists of a line number or 1187 comma-separated range of lines in the first file, a single character indicating 1188 the kind of change to make, and a line number or comma-separated range of 1189 lines in the second file. All line numbers are the original line numbers in 1190 each file. The types of change commands are: 1191 .Pp 1192 .Bl -tag -width Ds 1193 .It Va la Va r 1194 Add the lines in range 1195 .Va r 1196 of the second file after line 1197 .Va l 1198 of the first file. For example, 1199 .Li 8a12,15 1200 means append lines 12--15 of file 2 after line 8 of file 1; or, if changing 1201 file 2 into file 1, delete lines 12--15 of file 2. 1202 .Pp 1203 .It Va fc Va t 1204 Replace the lines in range 1205 .Va f 1206 of the first file with lines in range 1207 .Va t 1208 of the second file. This is like a combined add and delete, but more compact. 1209 For example, 1210 .Li 5,7c8,10 1211 means change lines 5--7 of file 1 to read as lines 8--10 of file 2; or, if 1212 changing file 2 into file 1, change lines 8--10 of file 2 to read as lines 1213 5--7 of file 1. 1214 .Pp 1215 .It Va rd Va l 1216 Delete the lines in range 1217 .Va r 1218 from the first file; line 1219 .Va l 1220 is where they would have appeared in the second file had they not been deleted. 1221 For example, 1222 .Li 5,7d3 1223 means delete lines 5--7 of file 1; or, if changing file 2 into file 1, append 1224 lines 5--7 of file 1 after line 3 of file 2. 1225 .El 1226 .Pp 1227 .Ss Making Edit Scripts 1228 Several output modes produce command scripts for editing 1229 .Va from-file 1230 to produce 1231 .Va to-file . 1232 .Pp 1233 .Em Xr ed Scripts 1234 .Pp 1235 .Xr diff 1236 can produce commands that direct the 1237 .Xr ed 1238 text editor to change the first file into the second file. Long ago, this 1239 was the only output mode that was suitable for editing one file into another 1240 automatically; today, with 1241 .Xr patch , 1242 it is almost obsolete. Use the 1243 .Op -e 1244 or 1245 .Op --ed 1246 option to select this output format. 1247 .Pp 1248 Like the normal format (see Section 1249 .Dq Normal ) , 1250 this output format does not show any context; unlike the normal format, it 1251 does not include the information necessary to apply the diff in reverse (to 1252 produce the first file if all you have is the second file and the diff). 1253 .Pp 1254 If the file 1255 .Pa d 1256 contains the output of 1257 .Li diff -e old new , 1258 then the command 1259 .Li (cat d && echo w) | ed - old 1260 edits 1261 .Pa old 1262 to make it a copy of 1263 .Pa new . 1264 More generally, if 1265 .Pa d1 , 1266 .Pa d2 , 1267 \&..., 1268 .Pa dN 1269 contain the outputs of 1270 .Li diff -e old new1 , 1271 .Li diff -e new1 new2 , 1272 \&..., 1273 .Li diff -e newN-1 newN , 1274 respectively, then the command 1275 .Li (cat d1 d2 ... dN && echo w) | ed - old 1276 edits 1277 .Pa old 1278 to make it a copy of 1279 .Pa newN . 1280 .Pp 1281 .No Example Xr ed Script 1282 .Pp 1283 Here is the output of 1284 .Li diff -e lao tzu 1285 (see Section 1286 .Dq Sample diff Input , 1287 for the complete contents of the two files): 1288 .Pp 1289 .Bd -literal -offset indent 1290 11a 1291 They both may be called deep and profound. 1292 Deeper and more profound, 1293 The door of all subtleties! 1294 \&. 1295 4c 1296 The named is the mother of all things. 1297 1298 \&. 1299 1,2d 1300 .Ed 1301 .Pp 1302 .No Detailed Description of Xr ed Format 1303 .Pp 1304 The 1305 .Xr ed 1306 output format consists of one or more hunks of differences. The changes closest 1307 to the ends of the files come first so that commands that change the number 1308 of lines do not affect how 1309 .Xr ed 1310 interprets line numbers in succeeding commands. 1311 .Xr ed 1312 format hunks look like this: 1313 .Pp 1314 .Bd -literal -offset indent 1315 change-command 1316 to-file-line 1317 to-file-line... 1318 \&. 1319 .Ed 1320 .Pp 1321 Because 1322 .Xr ed 1323 uses a single period on a line to indicate the end of input, GNU 1324 .Xr diff 1325 protects lines of changes that contain a single period on a line by writing 1326 two periods instead, then writing a subsequent 1327 .Xr ed 1328 command to change the two periods into one. The 1329 .Xr ed 1330 format cannot represent an incomplete line, so if the second file ends in 1331 a changed incomplete line, 1332 .Xr diff 1333 reports an error and then pretends that a newline was appended. 1334 .Pp 1335 There are three types of change commands. Each consists of a line number or 1336 comma-separated range of lines in the first file and a single character indicating 1337 the kind of change to make. All line numbers are the original line numbers 1338 in the file. The types of change commands are: 1339 .Pp 1340 .Bl -tag -width Ds 1341 .It Va la 1342 Add text from the second file after line 1343 .Va l 1344 in the first file. For example, 1345 .Li 8a 1346 means to add the following lines after line 8 of file 1. 1347 .Pp 1348 .It Va rc 1349 Replace the lines in range 1350 .Va r 1351 in the first file with the following lines. Like a combined add and delete, 1352 but more compact. For example, 1353 .Li 5,7c 1354 means change lines 5--7 of file 1 to read as the text file 2. 1355 .Pp 1356 .It Va rd 1357 Delete the lines in range 1358 .Va r 1359 from the first file. For example, 1360 .Li 5,7d 1361 means delete lines 5--7 of file 1. 1362 .El 1363 .Pp 1364 .Em Forward Xr ed Scripts 1365 .Pp 1366 .Xr diff 1367 can produce output that is like an 1368 .Xr ed 1369 script, but with hunks in forward (front to back) order. The format of the 1370 commands is also changed slightly: command characters precede the lines they 1371 modify, spaces separate line numbers in ranges, and no attempt is made to 1372 disambiguate hunk lines consisting of a single period. Like 1373 .Xr ed 1374 format, forward 1375 .Xr ed 1376 format cannot represent incomplete lines. 1377 .Pp 1378 Forward 1379 .Xr ed 1380 format is not very useful, because neither 1381 .Xr ed 1382 nor 1383 .Xr patch 1384 can apply diffs in this format. It exists mainly for compatibility with older 1385 versions of 1386 .Xr diff . 1387 Use the 1388 .Op -f 1389 or 1390 .Op --forward-ed 1391 option to select it. 1392 .Pp 1393 .Em RCS Scripts 1394 .Pp 1395 The RCS output format is designed specifically for use by the Revision Control 1396 System, which is a set of free programs used for organizing different versions 1397 and systems of files. Use the 1398 .Op -n 1399 or 1400 .Op --rcs 1401 option to select this output format. It is like the forward 1402 .Xr ed 1403 format (see Section 1404 .Dq Forward ed ) , 1405 but it can represent arbitrary changes to the contents of a file because it 1406 avoids the forward 1407 .Xr ed 1408 format's problems with lines consisting of a single period and with incomplete 1409 lines. Instead of ending text sections with a line consisting of a single 1410 period, each command specifies the number of lines it affects; a combination 1411 of the 1412 .Li a 1413 and 1414 .Li d 1415 commands are used instead of 1416 .Li c . 1417 Also, if the second file ends in a changed incomplete line, then the output 1418 also ends in an incomplete line. 1419 .Pp 1420 Here is the output of 1421 .Li diff -n lao tzu 1422 (see Section 1423 .Dq Sample diff Input , 1424 for the complete contents of the two files): 1425 .Pp 1426 .Bd -literal -offset indent 1427 d1 2 1428 d4 1 1429 a4 2 1430 The named is the mother of all things. 1431 1432 a11 3 1433 They both may be called deep and profound. 1434 Deeper and more profound, 1435 The door of all subtleties! 1436 .Ed 1437 .Pp 1438 .Ss Merging Files with If-then-else 1439 You can use 1440 .Xr diff 1441 to merge two files of C source code. The output of 1442 .Xr diff 1443 in this format contains all the lines of both files. Lines common to both 1444 files are output just once; the differing parts are separated by the C preprocessor 1445 directives 1446 .Li #ifdef Va name 1447 or 1448 .Li #ifndef Va name , 1449 .Li #else , 1450 and 1451 .Li #endif . 1452 When compiling the output, you select which version to use by either defining 1453 or leaving undefined the macro 1454 .Va name . 1455 .Pp 1456 To merge two files, use 1457 .Xr diff 1458 with the 1459 .Op -D Va name 1460 or 1461 .Op --ifdef= Va name 1462 option. The argument 1463 .Va name 1464 is the C preprocessor identifier to use in the 1465 .Li #ifdef 1466 and 1467 .Li #ifndef 1468 directives. 1469 .Pp 1470 For example, if you change an instance of 1471 .Li wait (&s) 1472 to 1473 .Li waitpid (-1, &s, 0) 1474 and then merge the old and new files with the 1475 .Op --ifdef=HAVE_WAITPID 1476 option, then the affected part of your code might look like this: 1477 .Pp 1478 .Bd -literal -offset indent 1479 do { 1480 #ifndef HAVE_WAITPID 1481 if ((w = wait (&s)) < 0 && errno != EINTR) 1482 #else /* HAVE_WAITPID */ 1483 if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR) 1484 #endif /* HAVE_WAITPID */ 1485 return w; 1486 } while (w != child); 1487 .Ed 1488 .Pp 1489 You can specify formats for languages other than C by using line group formats 1490 and line formats, as described in the next sections. 1491 .Pp 1492 .Em Line Group Formats 1493 .Pp 1494 Line group formats let you specify formats suitable for many applications 1495 that allow if-then-else input, including programming languages and text formatting 1496 languages. A line group format specifies the output format for a contiguous 1497 group of similar lines. 1498 .Pp 1499 For example, the following command compares the TeX files 1500 .Pa old 1501 and 1502 .Pa new , 1503 and outputs a merged file in which old regions are surrounded by 1504 .Li \ebegin{em} 1505 - 1506 .Li \eend{em} 1507 lines, and new regions are surrounded by 1508 .Li \ebegin{bf} 1509 - 1510 .Li \eend{bf} 1511 lines. 1512 .Pp 1513 .Bd -literal -offset indent 1514 diff \e 1515 --old-group-format='\ebegin{em} 1516 %<\eend{em} 1517 \&' \e 1518 --new-group-format='\ebegin{bf} 1519 %>\eend{bf} 1520 \&' \e 1521 old new 1522 .Ed 1523 .Pp 1524 The following command is equivalent to the above example, but it is a little 1525 more verbose, because it spells out the default line group formats. 1526 .Pp 1527 .Bd -literal -offset indent 1528 diff \e 1529 --old-group-format='\ebegin{em} 1530 %<\eend{em} 1531 \&' \e 1532 --new-group-format='\ebegin{bf} 1533 %>\eend{bf} 1534 \&' \e 1535 --unchanged-group-format='%=' \e 1536 --changed-group-format='\ebegin{em} 1537 %<\eend{em} 1538 \ebegin{bf} 1539 %>\eend{bf} 1540 \&' \e 1541 old new 1542 .Ed 1543 .Pp 1544 Here is a more advanced example, which outputs a diff listing with headers 1545 containing line numbers in a \(lqplain English\(rq style. 1546 .Pp 1547 .Bd -literal -offset indent 1548 diff \e 1549 --unchanged-group-format=\(rq \e 1550 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 1551 %<' \e 1552 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 1553 %>' \e 1554 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 1555 %<-------- to: 1556 %>' \e 1557 old new 1558 .Ed 1559 .Pp 1560 To specify a line group format, use 1561 .Xr diff 1562 with one of the options listed below. You can specify up to four line group 1563 formats, one for each kind of line group. You should quote 1564 .Va format , 1565 because it typically contains shell metacharacters. 1566 .Pp 1567 .Bl -tag -width Ds 1568 .It --old-group-format= Va format 1569 These line groups are hunks containing only lines from the first file. The 1570 default old group format is the same as the changed group format if it is 1571 specified; otherwise it is a format that outputs the line group as-is. 1572 .Pp 1573 .It --new-group-format= Va format 1574 These line groups are hunks containing only lines from the second file. The 1575 default new group format is same as the changed group format if it is specified; 1576 otherwise it is a format that outputs the line group as-is. 1577 .Pp 1578 .It --changed-group-format= Va format 1579 These line groups are hunks containing lines from both files. The default 1580 changed group format is the concatenation of the old and new group formats. 1581 .Pp 1582 .It --unchanged-group-format= Va format 1583 These line groups contain lines common to both files. The default unchanged 1584 group format is a format that outputs the line group as-is. 1585 .El 1586 .Pp 1587 In a line group format, ordinary characters represent themselves; conversion 1588 specifications start with 1589 .Li % 1590 and have one of the following forms. 1591 .Pp 1592 .Bl -tag -width Ds 1593 .It %< 1594 stands for the lines from the first file, including the trailing newline. 1595 Each line is formatted according to the old line format (see Section 1596 .Dq Line Formats ) . 1597 .Pp 1598 .It %> 1599 stands for the lines from the second file, including the trailing newline. 1600 Each line is formatted according to the new line format. 1601 .Pp 1602 .It %= 1603 stands for the lines common to both files, including the trailing newline. 1604 Each line is formatted according to the unchanged line format. 1605 .Pp 1606 .It %% 1607 stands for 1608 .Li % . 1609 .Pp 1610 .It %c' Va C' 1611 where 1612 .Va C 1613 is a single character, stands for 1614 .Va C . 1615 .Va C 1616 may not be a backslash or an apostrophe. For example, 1617 .Li %c':' 1618 stands for a colon, even inside the then-part of an if-then-else format, which 1619 a colon would normally terminate. 1620 .Pp 1621 .It %c'\e Va O' 1622 where 1623 .Va O 1624 is a string of 1, 2, or 3 octal digits, stands for the character with octal 1625 code 1626 .Va O . 1627 For example, 1628 .Li %c'\e0' 1629 stands for a null character. 1630 .Pp 1631 .It Va F Va n 1632 where 1633 .Va F 1634 is a 1635 .Li printf 1636 conversion specification and 1637 .Va n 1638 is one of the following letters, stands for 1639 .Va n 1640 \&'s value formatted with 1641 .Va F . 1642 .Pp 1643 .Bl -tag -width Ds 1644 .It e 1645 The line number of the line just before the group in the old file. 1646 .Pp 1647 .It f 1648 The line number of the first line in the group in the old file; equals 1649 .Va e 1650 + 1. 1651 .Pp 1652 .It l 1653 The line number of the last line in the group in the old file. 1654 .Pp 1655 .It m 1656 The line number of the line just after the group in the old file; equals 1657 .Va l 1658 + 1. 1659 .Pp 1660 .It n 1661 The number of lines in the group in the old file; equals 1662 .Va l 1663 - 1664 .Va f 1665 + 1. 1666 .Pp 1667 .It E, F, L, M, N 1668 Likewise, for lines in the new file. 1669 .Pp 1670 .El 1671 The 1672 .Li printf 1673 conversion specification can be 1674 .Li %d , 1675 .Li %o , 1676 .Li %x , 1677 or 1678 .Li %X , 1679 specifying decimal, octal, lower case hexadecimal, or upper case hexadecimal 1680 output respectively. After the 1681 .Li % 1682 the following options can appear in sequence: a series of zero or more flags; 1683 an integer specifying the minimum field width; and a period followed by an 1684 optional integer specifying the minimum number of digits. The flags are 1685 .Li - 1686 for left-justification, 1687 .Li ' 1688 for separating the digit into groups as specified by the 1689 .Ev LC_NUMERIC 1690 locale category, and 1691 .Li 0 1692 for padding with zeros instead of spaces. For example, 1693 .Li %5dN 1694 prints the number of new lines in the group in a field of width 5 characters, 1695 using the 1696 .Li printf 1697 format 1698 .Li "%5d" . 1699 .Pp 1700 .It ( Va A= Va B? Va T: Va E) 1701 If 1702 .Va A 1703 equals 1704 .Va B 1705 then 1706 .Va T 1707 else 1708 .Va E . 1709 .Va A 1710 and 1711 .Va B 1712 are each either a decimal constant or a single letter interpreted as above. 1713 This format spec is equivalent to 1714 .Va T 1715 if 1716 .Va A 1717 \&'s value equals 1718 .Va B 1719 \&'s; otherwise it is equivalent to 1720 .Va E . 1721 .Pp 1722 For example, 1723 .Li %(N=0?no:%dN) line%(N=1?:s) 1724 is equivalent to 1725 .Li no lines 1726 if 1727 .Va N 1728 (the number of lines in the group in the new file) is 0, to 1729 .Li 1 line 1730 if 1731 .Va N 1732 is 1, and to 1733 .Li %dN lines 1734 otherwise. 1735 .El 1736 .Pp 1737 .Em Line Formats 1738 .Pp 1739 Line formats control how each line taken from an input file is output as part 1740 of a line group in if-then-else format. 1741 .Pp 1742 For example, the following command outputs text with a one-character change 1743 indicator to the left of the text. The first character of output is 1744 .Li - 1745 for deleted lines, 1746 .Li | 1747 for added lines, and a space for unchanged lines. The formats contain newline 1748 characters where newlines are desired on output. 1749 .Pp 1750 .Bd -literal -offset indent 1751 diff \e 1752 --old-line-format='-%l 1753 \&' \e 1754 --new-line-format='|%l 1755 \&' \e 1756 --unchanged-line-format=' %l 1757 \&' \e 1758 old new 1759 .Ed 1760 .Pp 1761 To specify a line format, use one of the following options. You should quote 1762 .Va format , 1763 since it often contains shell metacharacters. 1764 .Pp 1765 .Bl -tag -width Ds 1766 .It --old-line-format= Va format 1767 formats lines just from the first file. 1768 .Pp 1769 .It --new-line-format= Va format 1770 formats lines just from the second file. 1771 .Pp 1772 .It --unchanged-line-format= Va format 1773 formats lines common to both files. 1774 .Pp 1775 .It --line-format= Va format 1776 formats all lines; in effect, it sets all three above options simultaneously. 1777 .El 1778 .Pp 1779 In a line format, ordinary characters represent themselves; conversion specifications 1780 start with 1781 .Li % 1782 and have one of the following forms. 1783 .Pp 1784 .Bl -tag -width Ds 1785 .It %l 1786 stands for the contents of the line, not counting its trailing newline (if 1787 any). This format ignores whether the line is incomplete;See Section 1788 .Dq Incomplete Lines . 1789 .Pp 1790 .It %L 1791 stands for the contents of the line, including its trailing newline (if any). 1792 If a line is incomplete, this format preserves its incompleteness. 1793 .Pp 1794 .It %% 1795 stands for 1796 .Li % . 1797 .Pp 1798 .It %c' Va C' 1799 where 1800 .Va C 1801 is a single character, stands for 1802 .Va C . 1803 .Va C 1804 may not be a backslash or an apostrophe. For example, 1805 .Li %c':' 1806 stands for a colon. 1807 .Pp 1808 .It %c'\e Va O' 1809 where 1810 .Va O 1811 is a string of 1, 2, or 3 octal digits, stands for the character with octal 1812 code 1813 .Va O . 1814 For example, 1815 .Li %c'\e0' 1816 stands for a null character. 1817 .Pp 1818 .It Va Fn 1819 where 1820 .Va F 1821 is a 1822 .Li printf 1823 conversion specification, stands for the line number formatted with 1824 .Va F . 1825 For example, 1826 .Li %.5dn 1827 prints the line number using the 1828 .Li printf 1829 format 1830 .Li "%.5d" . 1831 See Section.Dq Line Group Formats , 1832 for more about printf conversion specifications. 1833 .Pp 1834 .El 1835 The default line format is 1836 .Li %l 1837 followed by a newline character. 1838 .Pp 1839 If the input contains tab characters and it is important that they line up 1840 on output, you should ensure that 1841 .Li %l 1842 or 1843 .Li %L 1844 in a line format is just after a tab stop (e.g. by preceding 1845 .Li %l 1846 or 1847 .Li %L 1848 with a tab character), or you should use the 1849 .Op -t 1850 or 1851 .Op --expand-tabs 1852 option. 1853 .Pp 1854 Taken together, the line and line group formats let you specify many different 1855 formats. For example, the following command uses a format similar to normal 1856 .Xr diff 1857 format. You can tailor this command to get fine control over 1858 .Xr diff 1859 output. 1860 .Pp 1861 .Bd -literal -offset indent 1862 diff \e 1863 --old-line-format='< %l 1864 \&' \e 1865 --new-line-format='> %l 1866 \&' \e 1867 --old-group-format='%df%(f=l?:,%dl)d%dE 1868 %<' \e 1869 --new-group-format='%dea%dF%(F=L?:,%dL) 1870 %>' \e 1871 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 1872 %<--- 1873 %>' \e 1874 --unchanged-group-format=\(rq \e 1875 old new 1876 .Ed 1877 .Pp 1878 .Em An Example of If-then-else Format 1879 .Pp 1880 Here is the output of 1881 .Li diff -DTWO lao tzu 1882 (see Section 1883 .Dq Sample diff Input , 1884 for the complete contents of the two files): 1885 .Pp 1886 .Bd -literal -offset indent 1887 #ifndef TWO 1888 The Way that can be told of is not the eternal Way; 1889 The name that can be named is not the eternal name. 1890 #endif /* ! TWO */ 1891 The Nameless is the origin of Heaven and Earth; 1892 #ifndef TWO 1893 The Named is the mother of all things. 1894 #else /* TWO */ 1895 The named is the mother of all things. 1896 1897 #endif /* TWO */ 1898 Therefore let there always be non-being, 1899 so we may see their subtlety, 1900 And let there always be being, 1901 so we may see their outcome. 1902 The two are the same, 1903 But after they are produced, 1904 they have different names. 1905 #ifdef TWO 1906 They both may be called deep and profound. 1907 Deeper and more profound, 1908 The door of all subtleties! 1909 #endif /* TWO */ 1910 .Ed 1911 .Pp 1912 .Em Detailed Description of If-then-else Format 1913 .Pp 1914 For lines common to both files, 1915 .Xr diff 1916 uses the unchanged line group format. For each hunk of differences in the 1917 merged output format, if the hunk contains only lines from the first file, 1918 .Xr diff 1919 uses the old line group format; if the hunk contains only lines from the second 1920 file, 1921 .Xr diff 1922 uses the new group format; otherwise, 1923 .Xr diff 1924 uses the changed group format. 1925 .Pp 1926 The old, new, and unchanged line formats specify the output format of lines 1927 from the first file, lines from the second file, and lines common to both 1928 files, respectively. 1929 .Pp 1930 The option 1931 .Op --ifdef= Va name 1932 is equivalent to the following sequence of options using shell syntax: 1933 .Pp 1934 .Bd -literal -offset indent 1935 --old-group-format='#ifndef name 1936 %<#endif /* ! name */ 1937 \&' \e 1938 --new-group-format='#ifdef name 1939 %>#endif /* name */ 1940 \&' \e 1941 --unchanged-group-format='%=' \e 1942 --changed-group-format='#ifndef name 1943 %<#else /* name */ 1944 %>#endif /* name */ 1945 \&' 1946 .Ed 1947 .Pp 1948 You should carefully check the 1949 .Xr diff 1950 output for proper nesting. For example, when using the 1951 .Op -D Va name 1952 or 1953 .Op --ifdef= Va name 1954 option, you should check that if the differing lines contain any of the C 1955 preprocessor directives 1956 .Li #ifdef , 1957 .Li #ifndef , 1958 .Li #else , 1959 .Li #elif , 1960 or 1961 .Li #endif , 1962 they are nested properly and match. If they don't, you must make corrections 1963 manually. It is a good idea to carefully check the resulting code anyway to 1964 make sure that it really does what you want it to; depending on how the input 1965 files were produced, the output might contain duplicate or otherwise incorrect 1966 code. 1967 .Pp 1968 The 1969 .Xr patch 1970 .Op -D Va name 1971 option behaves like the 1972 .Xr diff 1973 .Op -D Va name 1974 option, except it operates on a file and a diff to produce a merged file;See Section 1975 .Dq patch Options . 1976 .Pp 1977 .Sh Incomplete Lines 1978 When an input file ends in a non-newline character, its last line is called 1979 an 1980 .Em incomplete line 1981 because its last character is not a newline. All other lines are called 1982 .Em full lines 1983 and end in a newline character. Incomplete lines do not match full lines unless 1984 differences in white space are ignored (see Section 1985 .Dq White Space ) . 1986 .Pp 1987 An incomplete line is normally distinguished on output from a full line by 1988 a following line that starts with 1989 .Li \e . 1990 However, the RCS format (see Section 1991 .Dq RCS ) 1992 outputs the incomplete line as-is, without any trailing newline or following 1993 line. The side by side format normally represents incomplete lines as-is, 1994 but in some cases uses a 1995 .Li \e 1996 or 1997 .Li / 1998 gutter marker;See Section 1999 .Dq Side by Side . 2000 The if-then-else line format preserves a line's incompleteness with 2001 .Li %L , 2002 and discards the newline with 2003 .Li %l 2004 ;See Section 2005 .Dq Line Formats . 2006 Finally, with the 2007 .Xr ed 2008 and forward 2009 .Xr ed 2010 output formats (see Section 2011 .Dq Output Formats ) 2012 .Xr diff 2013 cannot represent an incomplete line, so it pretends there was a newline and 2014 reports an error. 2015 .Pp 2016 For example, suppose 2017 .Pa F 2018 and 2019 .Pa G 2020 are one-byte files that contain just 2021 .Li f 2022 and 2023 .Li g , 2024 respectively. Then 2025 .Li diff F G 2026 outputs 2027 .Pp 2028 .Bd -literal -offset indent 2029 1c1 2030 < f 2031 \e No newline at end of file 2032 --- 2033 > g 2034 \e No newline at end of file 2035 .Ed 2036 .Pp 2037 (The exact message may differ in non-English locales.) 2038 .Li diff -n F G 2039 outputs the following without a trailing newline: 2040 .Pp 2041 .Bd -literal -offset indent 2042 d1 1 2043 a1 1 2044 g 2045 .Ed 2046 .Pp 2047 .Li diff -e F G 2048 reports two errors and outputs the following: 2049 .Pp 2050 .Bd -literal -offset indent 2051 1c 2052 g 2053 \&. 2054 .Ed 2055 .Pp 2056 .Sh Comparing Directories 2057 You can use 2058 .Xr diff 2059 to compare some or all of the files in two directory trees. When both file 2060 name arguments to 2061 .Xr diff 2062 are directories, it compares each file that is contained in both directories, 2063 examining file names in alphabetical order as specified by the 2064 .Ev LC_COLLATE 2065 locale category. Normally 2066 .Xr diff 2067 is silent about pairs of files that contain no differences, but if you use 2068 the 2069 .Op -s 2070 or 2071 .Op --report-identical-files 2072 option, it reports pairs of identical files. Normally 2073 .Xr diff 2074 reports subdirectories common to both directories without comparing subdirectories' 2075 files, but if you use the 2076 .Op -r 2077 or 2078 .Op --recursive 2079 option, it compares every corresponding pair of files in the directory trees, 2080 as many levels deep as they go. 2081 .Pp 2082 For file names that are in only one of the directories, 2083 .Xr diff 2084 normally does not show the contents of the file that exists; it reports only 2085 that the file exists in that directory and not in the other. You can make 2086 .Xr diff 2087 act as though the file existed but was empty in the other directory, so that 2088 it outputs the entire contents of the file that actually exists. (It is output 2089 as either an insertion or a deletion, depending on whether it is in the first 2090 or the second directory given.) To do this, use the 2091 .Op -N 2092 or 2093 .Op --new-file 2094 option. 2095 .Pp 2096 If the older directory contains one or more large files that are not in the 2097 newer directory, you can make the patch smaller by using the 2098 .Op --unidirectional-new-file 2099 option instead of 2100 .Op -N . 2101 This option is like 2102 .Op -N 2103 except that it only inserts the contents of files that appear in the second 2104 directory but not the first (that is, files that were added). At the top of 2105 the patch, write instructions for the user applying the patch to remove the 2106 files that were deleted before applying the patch.See Section 2107 .Dq Making Patches , 2108 for more discussion of making patches for distribution. 2109 .Pp 2110 To ignore some files while comparing directories, use the 2111 .Op -x Va pattern 2112 or 2113 .Op --exclude= Va pattern 2114 option. This option ignores any files or subdirectories whose base names match 2115 the shell pattern 2116 .Va pattern . 2117 Unlike in the shell, a period at the start of the base of a file name matches 2118 a wildcard at the start of a pattern. You should enclose 2119 .Va pattern 2120 in quotes so that the shell does not expand it. For example, the option 2121 .Op -x '*.[ao]' 2122 ignores any file whose name ends with 2123 .Li .a 2124 or 2125 .Li .o . 2126 .Pp 2127 This option accumulates if you specify it more than once. For example, using 2128 the options 2129 .Op -x 'RCS' -x '*,v' 2130 ignores any file or subdirectory whose base name is 2131 .Li RCS 2132 or ends with 2133 .Li ,v . 2134 .Pp 2135 If you need to give this option many times, you can instead put the patterns 2136 in a file, one pattern per line, and use the 2137 .Op -X Va file 2138 or 2139 .Op --exclude-from= Va file 2140 option. Trailing white space and empty lines are ignored in the pattern file. 2141 .Pp 2142 If you have been comparing two directories and stopped partway through, later 2143 you might want to continue where you left off. You can do this by using the 2144 .Op -S Va file 2145 or 2146 .Op --starting-file= Va file 2147 option. This compares only the file 2148 .Va file 2149 and all alphabetically later files in the topmost directory level. 2150 .Pp 2151 If two directories differ only in that file names are lower case in one directory 2152 and upper case in the upper, 2153 .Xr diff 2154 normally reports many differences because it compares file names in a case 2155 sensitive way. With the 2156 .Op --ignore-file-name-case 2157 option, 2158 .Xr diff 2159 ignores case differences in file names, so that for example the contents of 2160 the file 2161 .Pa Tao 2162 in one directory are compared to the contents of the file 2163 .Pa TAO 2164 in the other. The 2165 .Op --no-ignore-file-name-case 2166 option cancels the effect of the 2167 .Op --ignore-file-name-case 2168 option, reverting to the default behavior. 2169 .Pp 2170 If an 2171 .Op -x Va pattern 2172 or 2173 .Op --exclude= Va pattern 2174 option, or an 2175 .Op -X Va file 2176 or 2177 .Op --exclude-from= Va file 2178 option, is specified while the 2179 .Op --ignore-file-name-case 2180 option is in effect, case is ignored when excluding file names matching the 2181 specified patterns. 2182 .Pp 2183 .Sh Making Xr diff Output Prettier 2184 .Xr diff 2185 provides several ways to adjust the appearance of its output. These adjustments 2186 can be applied to any output format. 2187 .Pp 2188 .Ss Preserving Tab Stop Alignment 2189 The lines of text in some of the 2190 .Xr diff 2191 output formats are preceded by one or two characters that indicate whether 2192 the text is inserted, deleted, or changed. The addition of those characters 2193 can cause tabs to move to the next tab stop, throwing off the alignment of 2194 columns in the line. GNU 2195 .Xr diff 2196 provides two ways to make tab-aligned columns line up correctly. 2197 .Pp 2198 The first way is to have 2199 .Xr diff 2200 convert all tabs into the correct number of spaces before outputting them; 2201 select this method with the 2202 .Op -t 2203 or 2204 .Op --expand-tabs 2205 option. To use this form of output with 2206 .Xr patch , 2207 you must give 2208 .Xr patch 2209 the 2210 .Op -l 2211 or 2212 .Op --ignore-white-space 2213 option (see Section 2214 .Dq Changed White Space , 2215 for more information). 2216 .Xr diff 2217 normally assumes that tab stops are set every 8 print columns, but this can 2218 be altered by the 2219 .Op --tabsize= Va columns 2220 option. 2221 .Pp 2222 The other method for making tabs line up correctly is to add a tab character 2223 instead of a space after the indicator character at the beginning of the line. 2224 This ensures that all following tab characters are in the same position relative 2225 to tab stops that they were in the original files, so that the output is aligned 2226 correctly. Its disadvantage is that it can make long lines too long to fit 2227 on one line of the screen or the paper. It also does not work with the unified 2228 output format, which does not have a space character after the change type 2229 indicator character. Select this method with the 2230 .Op -T 2231 or 2232 .Op --initial-tab 2233 option. 2234 .Pp 2235 .Ss Paginating Xr diff Output 2236 It can be convenient to have long output page-numbered and time-stamped. The 2237 .Op -l 2238 or 2239 .Op --paginate 2240 option does this by sending the 2241 .Xr diff 2242 output through the 2243 .Xr pr 2244 program. Here is what the page header might look like for 2245 .Li diff -lc lao tzu : 2246 .Pp 2247 .Bd -literal -offset indent 2248 2002-02-22 14:20 diff -lc lao tzu Page 1 2249 .Ed 2250 .Pp 2251 .Sh Xr diff Performance Tradeoffs 2252 GNU 2253 .Xr diff 2254 runs quite efficiently; however, in some circumstances you can cause it to 2255 run faster or produce a more compact set of changes. 2256 .Pp 2257 One way to improve 2258 .Xr diff 2259 performance is to use hard or symbolic links to files instead of copies. This 2260 improves performance because 2261 .Xr diff 2262 normally does not need to read two hard or symbolic links to the same file, 2263 since their contents must be identical. For example, suppose you copy a large 2264 directory hierarchy, make a few changes to the copy, and then often use 2265 .Li diff -r 2266 to compare the original to the copy. If the original files are read-only, 2267 you can greatly improve performance by creating the copy using hard or symbolic 2268 links (e.g., with GNU 2269 .Li cp -lR 2270 or 2271 .Li cp -sR ) . 2272 Before editing a file in the copy for the first time, you should break the 2273 link and replace it with a regular copy. 2274 .Pp 2275 You can also affect the performance of GNU 2276 .Xr diff 2277 by giving it options that change the way it compares files. Performance has 2278 more than one dimension. These options improve one aspect of performance at 2279 the cost of another, or they improve performance in some cases while hurting 2280 it in others. 2281 .Pp 2282 The way that GNU 2283 .Xr diff 2284 determines which lines have changed always comes up with a near-minimal set 2285 of differences. Usually it is good enough for practical purposes. If the 2286 .Xr diff 2287 output is large, you might want 2288 .Xr diff 2289 to use a modified algorithm that sometimes produces a smaller set of differences. 2290 The 2291 .Op -d 2292 or 2293 .Op --minimal 2294 option does this; however, it can also cause 2295 .Xr diff 2296 to run more slowly than usual, so it is not the default behavior. 2297 .Pp 2298 When the files you are comparing are large and have small groups of changes 2299 scattered throughout them, you can use the 2300 .Op --speed-large-files 2301 option to make a different modification to the algorithm that 2302 .Xr diff 2303 uses. If the input files have a constant small density of changes, this option 2304 speeds up the comparisons without changing the output. If not, 2305 .Xr diff 2306 might produce a larger set of differences; however, the output will still 2307 be correct. 2308 .Pp 2309 Normally 2310 .Xr diff 2311 discards the prefix and suffix that is common to both files before it attempts 2312 to find a minimal set of differences. This makes 2313 .Xr diff 2314 run faster, but occasionally it may produce non-minimal output. The 2315 .Op --horizon-lines= Va lines 2316 option prevents 2317 .Xr diff 2318 from discarding the last 2319 .Va lines 2320 lines of the prefix and the first 2321 .Va lines 2322 lines of the suffix. This gives 2323 .Xr diff 2324 further opportunities to find a minimal output. 2325 .Pp 2326 Suppose a run of changed lines includes a sequence of lines at one end and 2327 there is an identical sequence of lines just outside the other end. The 2328 .Xr diff 2329 command is free to choose which identical sequence is included in the hunk. 2330 In this case, 2331 .Xr diff 2332 normally shifts the hunk's boundaries when this merges adjacent hunks, or 2333 shifts a hunk's lines towards the end of the file. Merging hunks can make 2334 the output look nicer in some cases. 2335 .Pp 2336 .Sh Comparing Three Files 2337 Use the program 2338 .Xr diff3 2339 to compare three files and show any differences among them. ( 2340 .Xr diff3 2341 can also merge files; see diff3 Merging). 2342 .Pp 2343 The \(lqnormal\(rq 2344 .Xr diff3 2345 output format shows each hunk of differences without surrounding context. 2346 Hunks are labeled depending on whether they are two-way or three-way, and 2347 lines are annotated by their location in the input files. 2348 .Pp 2349 See Section.Dq Invoking diff3 , 2350 for more information on how to run 2351 .Xr diff3 . 2352 .Pp 2353 .Ss A Third Sample Input File 2354 Here is a third sample file that will be used in examples to illustrate the 2355 output of 2356 .Xr diff3 2357 and how various options can change it. The first two files are the same that 2358 we used for 2359 .Xr diff 2360 (see Section 2361 .Dq Sample diff Input ) . 2362 This is the third sample file, called 2363 .Pa tao : 2364 .Pp 2365 .Bd -literal -offset indent 2366 The Way that can be told of is not the eternal Way; 2367 The name that can be named is not the eternal name. 2368 The Nameless is the origin of Heaven and Earth; 2369 The named is the mother of all things. 2370 2371 Therefore let there always be non-being, 2372 so we may see their subtlety, 2373 And let there always be being, 2374 so we may see their result. 2375 The two are the same, 2376 But after they are produced, 2377 they have different names. 2378 2379 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2380 .Ed 2381 .Pp 2382 .Ss An Example of Xr diff3 Normal Format 2383 Here is the output of the command 2384 .Li diff3 lao tzu tao 2385 (see Section 2386 .Dq Sample diff3 Input , 2387 for the complete contents of the files). Notice that it shows only the lines 2388 that are different among the three files. 2389 .Pp 2390 .Bd -literal -offset indent 2391 ====2 2392 1:1,2c 2393 3:1,2c 2394 The Way that can be told of is not the eternal Way; 2395 The name that can be named is not the eternal name. 2396 2:0a 2397 ====1 2398 1:4c 2399 The Named is the mother of all things. 2400 2:2,3c 2401 3:4,5c 2402 The named is the mother of all things. 2403 2404 ====3 2405 1:8c 2406 2:7c 2407 so we may see their outcome. 2408 3:9c 2409 so we may see their result. 2410 ==== 2411 1:11a 2412 2:11,13c 2413 They both may be called deep and profound. 2414 Deeper and more profound, 2415 The door of all subtleties! 2416 3:13,14c 2417 2418 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2419 .Ed 2420 .Pp 2421 .Ss Detailed Description of Xr diff3 Normal Format 2422 Each hunk begins with a line marked 2423 .Li ==== . 2424 Three-way hunks have plain 2425 .Li ==== 2426 lines, and two-way hunks have 2427 .Li 1 , 2428 .Li 2 , 2429 or 2430 .Li 3 2431 appended to specify which of the three input files differ in that hunk. The 2432 hunks contain copies of two or three sets of input lines each preceded by 2433 one or two commands identifying where the lines came from. 2434 .Pp 2435 Normally, two spaces precede each copy of an input line to distinguish it 2436 from the commands. But with the 2437 .Op -T 2438 or 2439 .Op --initial-tab 2440 option, 2441 .Xr diff3 2442 uses a tab instead of two spaces; this lines up tabs correctly.See Section 2443 .Dq Tabs , 2444 for more information. 2445 .Pp 2446 Commands take the following forms: 2447 .Pp 2448 .Bl -tag -width Ds 2449 .It Va file: Va la 2450 This hunk appears after line 2451 .Va l 2452 of file 2453 .Va file , 2454 and contains no lines in that file. To edit this file to yield the other files, 2455 one must append hunk lines taken from the other files. For example, 2456 .Li 1:11a 2457 means that the hunk follows line 11 in the first file and contains no lines 2458 from that file. 2459 .Pp 2460 .It Va file: Va rc 2461 This hunk contains the lines in the range 2462 .Va r 2463 of file 2464 .Va file . 2465 The range 2466 .Va r 2467 is a comma-separated pair of line numbers, or just one number if the range 2468 is a singleton. To edit this file to yield the other files, one must change 2469 the specified lines to be the lines taken from the other files. For example, 2470 .Li 2:11,13c 2471 means that the hunk contains lines 11 through 13 from the second file. 2472 .El 2473 .Pp 2474 If the last line in a set of input lines is incomplete (see Section 2475 .Dq Incomplete Lines ) , 2476 it is distinguished on output from a full line by a following line that starts 2477 with 2478 .Li \e . 2479 .Pp 2480 .Ss Xr diff3 Hunks 2481 Groups of lines that differ in two or three of the input files are called 2482 .Em diff3 hunks , 2483 by analogy with 2484 .Xr diff 2485 hunks (see Section 2486 .Dq Hunks ) . 2487 If all three input files differ in a 2488 .Xr diff3 2489 hunk, the hunk is called a 2490 .Em three-way hunk 2491 ; if just two input files differ, it is a 2492 .Em two-way hunk . 2493 .Pp 2494 As with 2495 .Xr diff , 2496 several solutions are possible. When comparing the files 2497 .Li A , 2498 .Li B , 2499 and 2500 .Li C , 2501 .Xr diff3 2502 normally finds 2503 .Xr diff3 2504 hunks by merging the two-way hunks output by the two commands 2505 .Li diff A B 2506 and 2507 .Li diff A C . 2508 This does not necessarily minimize the size of the output, but exceptions 2509 should be rare. 2510 .Pp 2511 For example, suppose 2512 .Pa F 2513 contains the three lines 2514 .Li a , 2515 .Li b , 2516 .Li f , 2517 .Pa G 2518 contains the lines 2519 .Li g , 2520 .Li b , 2521 .Li g , 2522 and 2523 .Pa H 2524 contains the lines 2525 .Li a , 2526 .Li b , 2527 .Li h . 2528 .Li diff3 F G H 2529 might output the following: 2530 .Pp 2531 .Bd -literal -offset indent 2532 ====2 2533 1:1c 2534 3:1c 2535 a 2536 2:1c 2537 g 2538 ==== 2539 1:3c 2540 f 2541 2:3c 2542 g 2543 3:3c 2544 h 2545 .Ed 2546 .Pp 2547 because it found a two-way hunk containing 2548 .Li a 2549 in the first and third files and 2550 .Li g 2551 in the second file, then the single line 2552 .Li b 2553 common to all three files, then a three-way hunk containing the last line 2554 of each file. 2555 .Pp 2556 .Sh Merging From a Common Ancestor 2557 When two people have made changes to copies of the same file, 2558 .Xr diff3 2559 can produce a merged output that contains both sets of changes together with 2560 warnings about conflicts. 2561 .Pp 2562 One might imagine programs with names like 2563 .Xr diff4 2564 and 2565 .Xr diff5 2566 to compare more than three files simultaneously, but in practice the need 2567 rarely arises. You can use 2568 .Xr diff3 2569 to merge three or more sets of changes to a file by merging two change sets 2570 at a time. 2571 .Pp 2572 .Xr diff3 2573 can incorporate changes from two modified versions into a common preceding 2574 version. This lets you merge the sets of changes represented by the two newer 2575 files. Specify the common ancestor version as the second argument and the 2576 two newer versions as the first and third arguments, like this: 2577 .Pp 2578 .Bd -literal -offset indent 2579 diff3 mine older yours 2580 .Ed 2581 .Pp 2582 You can remember the order of the arguments by noting that they are in alphabetical 2583 order. 2584 .Pp 2585 You can think of this as subtracting 2586 .Va older 2587 from 2588 .Va yours 2589 and adding the result to 2590 .Va mine , 2591 or as merging into 2592 .Va mine 2593 the changes that would turn 2594 .Va older 2595 into 2596 .Va yours . 2597 This merging is well-defined as long as 2598 .Va mine 2599 and 2600 .Va older 2601 match in the neighborhood of each such change. This fails to be true when 2602 all three input files differ or when only 2603 .Va older 2604 differs; we call this a 2605 .Em conflict . 2606 When all three input files differ, we call the conflict an 2607 .Em overlap . 2608 .Pp 2609 .Xr diff3 2610 gives you several ways to handle overlaps and conflicts. You can omit overlaps 2611 or conflicts, or select only overlaps, or mark conflicts with special 2612 .Li <<<<<<< 2613 and 2614 .Li >>>>>>> 2615 lines. 2616 .Pp 2617 .Xr diff3 2618 can output the merge results as an 2619 .Xr ed 2620 script that that can be applied to the first file to yield the merged output. 2621 However, it is usually better to have 2622 .Xr diff3 2623 generate the merged output directly; this bypasses some problems with 2624 .Xr ed . 2625 .Pp 2626 .Ss Selecting Which Changes to Incorporate 2627 You can select all unmerged changes from 2628 .Va older 2629 to 2630 .Va yours 2631 for merging into 2632 .Va mine 2633 with the 2634 .Op -e 2635 or 2636 .Op --ed 2637 option. You can select only the nonoverlapping unmerged changes with 2638 .Op -3 2639 or 2640 .Op --easy-only , 2641 and you can select only the overlapping changes with 2642 .Op -x 2643 or 2644 .Op --overlap-only . 2645 .Pp 2646 The 2647 .Op -e , 2648 .Op -3 2649 and 2650 .Op -x 2651 options select only 2652 .Em unmerged changes , 2653 i.e. changes where 2654 .Va mine 2655 and 2656 .Va yours 2657 differ; they ignore changes from 2658 .Va older 2659 to 2660 .Va yours 2661 where 2662 .Va mine 2663 and 2664 .Va yours 2665 are identical, because they assume that such changes have already been merged. 2666 If this assumption is not a safe one, you can use the 2667 .Op -A 2668 or 2669 .Op --show-all 2670 option (see Section 2671 .Dq Marking Conflicts ) . 2672 .Pp 2673 Here is the output of the command 2674 .Xr diff3 2675 with each of these three options (see Section 2676 .Dq Sample diff3 Input , 2677 for the complete contents of the files). Notice that 2678 .Op -e 2679 outputs the union of the disjoint sets of changes output by 2680 .Op -3 2681 and 2682 .Op -x . 2683 .Pp 2684 Output of 2685 .Li diff3 -e lao tzu tao : 2686 .Bd -literal -offset indent 2687 11a 2688 2689 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2690 \&. 2691 8c 2692 so we may see their result. 2693 \&. 2694 .Ed 2695 .Pp 2696 Output of 2697 .Li diff3 -3 lao tzu tao : 2698 .Bd -literal -offset indent 2699 8c 2700 so we may see their result. 2701 \&. 2702 .Ed 2703 .Pp 2704 Output of 2705 .Li diff3 -x lao tzu tao : 2706 .Bd -literal -offset indent 2707 11a 2708 2709 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2710 \&. 2711 .Ed 2712 .Pp 2713 .Ss Marking Conflicts 2714 .Xr diff3 2715 can mark conflicts in the merged output by bracketing them with special marker 2716 lines. A conflict that comes from two files 2717 .Va A 2718 and 2719 .Va B 2720 is marked as follows: 2721 .Pp 2722 .Bd -literal -offset indent 2723 <<<<<<< A 2724 lines from A 2725 ======= 2726 lines from B 2727 >>>>>>> B 2728 .Ed 2729 .Pp 2730 A conflict that comes from three files 2731 .Va A , 2732 .Va B 2733 and 2734 .Va C 2735 is marked as follows: 2736 .Pp 2737 .Bd -literal -offset indent 2738 <<<<<<< A 2739 lines from A 2740 ||||||| B 2741 lines from B 2742 ======= 2743 lines from C 2744 >>>>>>> C 2745 .Ed 2746 .Pp 2747 The 2748 .Op -A 2749 or 2750 .Op --show-all 2751 option acts like the 2752 .Op -e 2753 option, except that it brackets conflicts, and it outputs all changes from 2754 .Va older 2755 to 2756 .Va yours , 2757 not just the unmerged changes. Thus, given the sample input files (see Section 2758 .Dq Sample diff3 Input ) , 2759 .Li diff3 -A lao tzu tao 2760 puts brackets around the conflict where only 2761 .Pa tzu 2762 differs: 2763 .Pp 2764 .Bd -literal -offset indent 2765 <<<<<<< tzu 2766 ======= 2767 The Way that can be told of is not the eternal Way; 2768 The name that can be named is not the eternal name. 2769 >>>>>>> tao 2770 .Ed 2771 .Pp 2772 And it outputs the three-way conflict as follows: 2773 .Pp 2774 .Bd -literal -offset indent 2775 <<<<<<< lao 2776 ||||||| tzu 2777 They both may be called deep and profound. 2778 Deeper and more profound, 2779 The door of all subtleties! 2780 ======= 2781 2782 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2783 >>>>>>> tao 2784 .Ed 2785 .Pp 2786 The 2787 .Op -E 2788 or 2789 .Op --show-overlap 2790 option outputs less information than the 2791 .Op -A 2792 or 2793 .Op --show-all 2794 option, because it outputs only unmerged changes, and it never outputs the 2795 contents of the second file. Thus the 2796 .Op -E 2797 option acts like the 2798 .Op -e 2799 option, except that it brackets the first and third files from three-way overlapping 2800 changes. Similarly, 2801 .Op -X 2802 acts like 2803 .Op -x , 2804 except it brackets all its (necessarily overlapping) changes. For example, 2805 for the three-way overlapping change above, the 2806 .Op -E 2807 and 2808 .Op -X 2809 options output the following: 2810 .Pp 2811 .Bd -literal -offset indent 2812 <<<<<<< lao 2813 ======= 2814 2815 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2816 >>>>>>> tao 2817 .Ed 2818 .Pp 2819 If you are comparing files that have meaningless or uninformative names, you 2820 can use the 2821 .Op --label= Va label 2822 option to show alternate names in the 2823 .Li <<<<<<< , 2824 .Li ||||||| 2825 and 2826 .Li >>>>>>> 2827 brackets. This option can be given up to three times, once for each input 2828 file. Thus 2829 .Li diff3 -A --label X --label Y --label Z A B C 2830 acts like 2831 .Li diff3 -A A B C , 2832 except that the output looks like it came from files named 2833 .Li X , 2834 .Li Y 2835 and 2836 .Li Z 2837 rather than from files named 2838 .Li A , 2839 .Li B 2840 and 2841 .Li C . 2842 .Pp 2843 .Ss Generating the Merged Output Directly 2844 With the 2845 .Op -m 2846 or 2847 .Op --merge 2848 option, 2849 .Xr diff3 2850 outputs the merged file directly. This is more efficient than using 2851 .Xr ed 2852 to generate it, and works even with non-text files that 2853 .Xr ed 2854 would reject. If you specify 2855 .Op -m 2856 without an 2857 .Xr ed 2858 script option, 2859 .Op -A 2860 is assumed. 2861 .Pp 2862 For example, the command 2863 .Li diff3 -m lao tzu tao 2864 (see Section 2865 .Dq Sample diff3 Input 2866 for a copy of the input files) would output the following: 2867 .Pp 2868 .Bd -literal -offset indent 2869 <<<<<<< tzu 2870 ======= 2871 The Way that can be told of is not the eternal Way; 2872 The name that can be named is not the eternal name. 2873 >>>>>>> tao 2874 The Nameless is the origin of Heaven and Earth; 2875 The Named is the mother of all things. 2876 Therefore let there always be non-being, 2877 so we may see their subtlety, 2878 And let there always be being, 2879 so we may see their result. 2880 The two are the same, 2881 But after they are produced, 2882 they have different names. 2883 <<<<<<< lao 2884 ||||||| tzu 2885 They both may be called deep and profound. 2886 Deeper and more profound, 2887 The door of all subtleties! 2888 ======= 2889 2890 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2891 >>>>>>> tao 2892 .Ed 2893 .Pp 2894 .Ss How Xr diff3 Merges Incomplete Lines 2895 With 2896 .Op -m , 2897 incomplete lines (see Section 2898 .Dq Incomplete Lines ) 2899 are simply copied to the output as they are found; if the merged output ends 2900 in an conflict and one of the input files ends in an incomplete line, succeeding 2901 .Li ||||||| , 2902 .Li ======= 2903 or 2904 .Li >>>>>>> 2905 brackets appear somewhere other than the start of a line because they are 2906 appended to the incomplete line. 2907 .Pp 2908 Without 2909 .Op -m , 2910 if an 2911 .Xr ed 2912 script option is specified and an incomplete line is found, 2913 .Xr diff3 2914 generates a warning and acts as if a newline had been present. 2915 .Pp 2916 .Ss Saving the Changed File 2917 Traditional Unix 2918 .Xr diff3 2919 generates an 2920 .Xr ed 2921 script without the trailing 2922 .Li w 2923 and 2924 .Li q 2925 commands that save the changes. System V 2926 .Xr diff3 2927 generates these extra commands. GNU 2928 .Xr diff3 2929 normally behaves like traditional Unix 2930 .Xr diff3 , 2931 but with the 2932 .Op -i 2933 option it behaves like System V 2934 .Xr diff3 2935 and appends the 2936 .Li w 2937 and 2938 .Li q 2939 commands. 2940 .Pp 2941 The 2942 .Op -i 2943 option requires one of the 2944 .Xr ed 2945 script options 2946 .Op -AeExX3 , 2947 and is incompatible with the merged output option 2948 .Op -m . 2949 .Pp 2950 .Sh Interactive Merging with Xr sdiff 2951 With 2952 .Xr sdiff , 2953 you can merge two files interactively based on a side-by-side 2954 .Op -y 2955 format comparison (see Section 2956 .Dq Side by Side ) . 2957 Use 2958 .Op -o Va file 2959 or 2960 .Op --output= Va file 2961 to specify where to put the merged text.See Section 2962 .Dq Invoking sdiff , 2963 for more details on the options to 2964 .Xr sdiff . 2965 .Pp 2966 Another way to merge files interactively is to use the Emacs Lisp package 2967 .Xr emerge . 2968 See Section.Dq emerge , 2969 for more information. 2970 .Pp 2971 .Ss Specifying Xr diff Options to Xr sdiff 2972 The following 2973 .Xr sdiff 2974 options have the same meaning as for 2975 .Xr diff . 2976 See Section.Dq diff Options , 2977 for the use of these options. 2978 .Pp 2979 .Bd -literal -offset indent 2980 -a -b -d -i -t -v 2981 -B -E -I regexp 2982 2983 --expand-tabs 2984 --ignore-blank-lines --ignore-case 2985 --ignore-matching-lines=regexp --ignore-space-change 2986 --ignore-tab-expansion 2987 --left-column --minimal --speed-large-files 2988 --strip-trailing-cr --suppress-common-lines 2989 --tabsize=columns --text --version --width=columns 2990 .Ed 2991 .Pp 2992 For historical reasons, 2993 .Xr sdiff 2994 has alternate names for some options. The 2995 .Op -l 2996 option is equivalent to the 2997 .Op --left-column 2998 option, and similarly 2999 .Op -s 3000 is equivalent to 3001 .Op --suppress-common-lines . 3002 The meaning of the 3003 .Xr sdiff 3004 .Op -w 3005 and 3006 .Op -W 3007 options is interchanged from that of 3008 .Xr diff : 3009 with 3010 .Xr sdiff , 3011 .Op -w Va columns 3012 is equivalent to 3013 .Op --width= Va columns , 3014 and 3015 .Op -W 3016 is equivalent to 3017 .Op --ignore-all-space . 3018 .Xr sdiff 3019 without the 3020 .Op -o 3021 option is equivalent to 3022 .Xr diff 3023 with the 3024 .Op -y 3025 or 3026 .Op --side-by-side 3027 option (see Section 3028 .Dq Side by Side ) . 3029 .Pp 3030 .Ss Merge Commands 3031 Groups of common lines, with a blank gutter, are copied from the first file 3032 to the output. After each group of differing lines, 3033 .Xr sdiff 3034 prompts with 3035 .Li % 3036 and pauses, waiting for one of the following commands. Follow each command 3037 with RET. 3038 .Pp 3039 .Bl -tag -width Ds 3040 .It e 3041 Discard both versions. Invoke a text editor on an empty temporary file, then 3042 copy the resulting file to the output. 3043 .Pp 3044 .It eb 3045 Concatenate the two versions, edit the result in a temporary file, then copy 3046 the edited result to the output. 3047 .Pp 3048 .It ed 3049 Like 3050 .Li eb , 3051 except precede each version with a header that shows what file and lines the 3052 version came from. 3053 .Pp 3054 .It el 3055 .It e1 3056 Edit a copy of the left version, then copy the result to the output. 3057 .Pp 3058 .It er 3059 .It e2 3060 Edit a copy of the right version, then copy the result to the output. 3061 .Pp 3062 .It l 3063 .It 1 3064 Copy the left version to the output. 3065 .Pp 3066 .It q 3067 Quit. 3068 .Pp 3069 .It r 3070 .It 2 3071 Copy the right version to the output. 3072 .Pp 3073 .It s 3074 Silently copy common lines. 3075 .Pp 3076 .It v 3077 Verbosely copy common lines. This is the default. 3078 .El 3079 .Pp 3080 The text editor invoked is specified by the 3081 .Ev EDITOR 3082 environment variable if it is set. The default is system-dependent. 3083 .Pp 3084 .Sh Merging with Xr patch 3085 .Xr patch 3086 takes comparison output produced by 3087 .Xr diff 3088 and applies the differences to a copy of the original file, producing a patched 3089 version. With 3090 .Xr patch , 3091 you can distribute just the changes to a set of files instead of distributing 3092 the entire file set; your correspondents can apply 3093 .Xr patch 3094 to update their copy of the files with your changes. 3095 .Xr patch 3096 automatically determines the diff format, skips any leading or trailing headers, 3097 and uses the headers to determine which file to patch. This lets your correspondents 3098 feed a mail message containing a difference listing directly to 3099 .Xr patch . 3100 .Pp 3101 .Xr patch 3102 detects and warns about common problems like forward patches. It saves any 3103 patches that it could not apply. It can also maintain a 3104 .Li patchlevel.h 3105 file to ensure that your correspondents apply diffs in the proper order. 3106 .Pp 3107 .Xr patch 3108 accepts a series of diffs in its standard input, usually separated by headers 3109 that specify which file to patch. It applies 3110 .Xr diff 3111 hunks (see Section 3112 .Dq Hunks ) 3113 one by one. If a hunk does not exactly match the original file, 3114 .Xr patch 3115 uses heuristics to try to patch the file as well as it can. If no approximate 3116 match can be found, 3117 .Xr patch 3118 rejects the hunk and skips to the next hunk. 3119 .Xr patch 3120 normally replaces each file 3121 .Va f 3122 with its new version, putting reject hunks (if any) into 3123 .Li Va f.rej . 3124 .Pp 3125 See Section.Dq Invoking patch , 3126 for detailed information on the options to 3127 .Xr patch . 3128 .Pp 3129 .Ss Selecting the Xr patch Input Format 3130 .Xr patch 3131 normally determines which 3132 .Xr diff 3133 format the patch file uses by examining its contents. For patch files that 3134 contain particularly confusing leading text, you might need to use one of 3135 the following options to force 3136 .Xr patch 3137 to interpret the patch file as a certain format of diff. The output formats 3138 listed here are the only ones that 3139 .Xr patch 3140 can understand. 3141 .Pp 3142 .Bl -tag -width Ds 3143 .It -c 3144 .It --context 3145 context diff. 3146 .Pp 3147 .It -e 3148 .It --ed 3149 .Xr ed 3150 script. 3151 .Pp 3152 .It -n 3153 .It --normal 3154 normal diff. 3155 .Pp 3156 .It -u 3157 .It --unified 3158 unified diff. 3159 .El 3160 .Pp 3161 .Ss Revision Control 3162 If a nonexistent input file is under a revision control system supported by 3163 .Xr patch , 3164 .Xr patch 3165 normally asks the user whether to get (or check out) the file from the revision 3166 control system. Patch currently supports RCS, ClearCase and SCCS. Under RCS 3167 and SCCS, 3168 .Xr patch 3169 also asks when the input file is read-only and matches the default version 3170 in the revision control system. 3171 .Pp 3172 The 3173 .Op -g Va num 3174 or 3175 .Op --get= Va num 3176 option affects access to files under supported revision control systems. If 3177 .Va num 3178 is positive, 3179 .Xr patch 3180 gets the file without asking the user; if zero, 3181 .Xr patch 3182 neither asks the user nor gets the file; and if negative, 3183 .Xr patch 3184 asks the user before getting the file. The default value of 3185 .Va num 3186 is given by the value of the 3187 .Ev PATCH_GET 3188 environment variable if it is set; if not, the default value is zero if 3189 .Xr patch 3190 is conforming to POSIX, negative otherwise.See Section 3191 .Dq patch and POSIX . 3192 .Pp 3193 The choice of revision control system is unaffected by the 3194 .Ev VERSION_CONTROL 3195 environment variable (see Section 3196 .Dq Backup Names ) . 3197 .Pp 3198 .Ss Applying Imperfect Patches 3199 .Xr patch 3200 tries to skip any leading text in the patch file, apply the diff, and then 3201 skip any trailing text. Thus you can feed a mail message directly to 3202 .Xr patch , 3203 and it should work. If the entire diff is indented by a constant amount of 3204 white space, 3205 .Xr patch 3206 automatically ignores the indentation. If a context diff contains trailing 3207 carriage return on each line, 3208 .Xr patch 3209 automatically ignores the carriage return. If a context diff has been encapsulated 3210 by prepending 3211 .Li - 3212 to lines beginning with 3213 .Li - 3214 as per 3215 .Lk ftp://ftp.isi.edu/in-notes/rfc934.txt , 3216 .Xr patch 3217 automatically unencapsulates the input. 3218 .Pp 3219 However, certain other types of imperfect input require user intervention 3220 or testing. 3221 .Pp 3222 .Em Applying Patches with Changed White Space 3223 .Pp 3224 Sometimes mailers, editors, or other programs change spaces into tabs, or 3225 vice versa. If this happens to a patch file or an input file, the files might 3226 look the same, but 3227 .Xr patch 3228 will not be able to match them properly. If this problem occurs, use the 3229 .Op -l 3230 or 3231 .Op --ignore-white-space 3232 option, which makes 3233 .Xr patch 3234 compare blank characters (i.e. spaces and tabs) loosely so that any nonempty 3235 sequence of blanks in the patch file matches any nonempty sequence of blanks 3236 in the input files. Non-blank characters must still match exactly. Each line 3237 of the context must still match a line in the input file. 3238 .Pp 3239 .Em Applying Reversed Patches 3240 .Pp 3241 Sometimes people run 3242 .Xr diff 3243 with the new file first instead of second. This creates a diff that is \(lqreversed\(rq. 3244 To apply such patches, give 3245 .Xr patch 3246 the 3247 .Op -R 3248 or 3249 .Op --reverse 3250 option. 3251 .Xr patch 3252 then attempts to swap each hunk around before applying it. Rejects come out 3253 in the swapped format. 3254 .Pp 3255 Often 3256 .Xr patch 3257 can guess that the patch is reversed. If the first hunk of a patch fails, 3258 .Xr patch 3259 reverses the hunk to see if it can apply it that way. If it can, 3260 .Xr patch 3261 asks you if you want to have the 3262 .Op -R 3263 option set; if it can't, 3264 .Xr patch 3265 continues to apply the patch normally. This method cannot detect a reversed 3266 patch if it is a normal diff and the first command is an append (which should 3267 have been a delete) since appends always succeed, because a null context matches 3268 anywhere. But most patches add or change lines rather than delete them, so 3269 most reversed normal diffs begin with a delete, which fails, and 3270 .Xr patch 3271 notices. 3272 .Pp 3273 If you apply a patch that you have already applied, 3274 .Xr patch 3275 thinks it is a reversed patch and offers to un-apply the patch. This could 3276 be construed as a feature. If you did this inadvertently and you don't want 3277 to un-apply the patch, just answer 3278 .Li n 3279 to this offer and to the subsequent \(lqapply anyway\(rq question---or type 3280 .Li C-c 3281 to kill the 3282 .Xr patch 3283 process. 3284 .Pp 3285 .Em Helping Xr patch Find Inexact Matches 3286 .Pp 3287 For context diffs, and to a lesser extent normal diffs, 3288 .Xr patch 3289 can detect when the line numbers mentioned in the patch are incorrect, and 3290 it attempts to find the correct place to apply each hunk of the patch. As 3291 a first guess, it takes the line number mentioned in the hunk, plus or minus 3292 any offset used in applying the previous hunk. If that is not the correct 3293 place, 3294 .Xr patch 3295 scans both forward and backward for a set of lines matching the context given 3296 in the hunk. 3297 .Pp 3298 First 3299 .Xr patch 3300 looks for a place where all lines of the context match. If it cannot find 3301 such a place, and it is reading a context or unified diff, and the maximum 3302 fuzz factor is set to 1 or more, then 3303 .Xr patch 3304 makes another scan, ignoring the first and last line of context. If that fails, 3305 and the maximum fuzz factor is set to 2 or more, it makes another scan, ignoring 3306 the first two and last two lines of context are ignored. It continues similarly 3307 if the maximum fuzz factor is larger. 3308 .Pp 3309 The 3310 .Op -F Va lines 3311 or 3312 .Op --fuzz= Va lines 3313 option sets the maximum fuzz factor to 3314 .Va lines . 3315 This option only applies to context and unified diffs; it ignores up to 3316 .Va lines 3317 lines while looking for the place to install a hunk. Note that a larger fuzz 3318 factor increases the odds of making a faulty patch. The default fuzz factor 3319 is 2; there is no point to setting it to more than the number of lines of 3320 context in the diff, ordinarily 3. 3321 .Pp 3322 If 3323 .Xr patch 3324 cannot find a place to install a hunk of the patch, it writes the hunk out 3325 to a reject file (see Section 3326 .Dq Reject Names , 3327 for information on how reject files are named). It writes out rejected hunks 3328 in context format no matter what form the input patch is in. If the input 3329 is a normal or 3330 .Xr ed 3331 diff, many of the contexts are simply null. The line numbers on the hunks 3332 in the reject file may be different from those in the patch file: they show 3333 the approximate location where 3334 .Xr patch 3335 thinks the failed hunks belong in the new file rather than in the old one. 3336 .Pp 3337 If the 3338 .Op --verbose 3339 option is given, then as it completes each hunk 3340 .Xr patch 3341 tells you whether the hunk succeeded or failed, and if it failed, on which 3342 line (in the new file) 3343 .Xr patch 3344 thinks the hunk should go. If this is different from the line number specified 3345 in the diff, it tells you the offset. A single large offset 3346 .Em may 3347 indicate that 3348 .Xr patch 3349 installed a hunk in the wrong place. 3350 .Xr patch 3351 also tells you if it used a fuzz factor to make the match, in which case you 3352 should also be slightly suspicious. 3353 .Pp 3354 .Xr patch 3355 cannot tell if the line numbers are off in an 3356 .Xr ed 3357 script, and can only detect wrong line numbers in a normal diff when it finds 3358 a change or delete command. It may have the same problem with a context diff 3359 using a fuzz factor equal to or greater than the number of lines of context 3360 shown in the diff (typically 3). In these cases, you should probably look 3361 at a context diff between your original and patched input files to see if 3362 the changes make sense. Compiling without errors is a pretty good indication 3363 that the patch worked, but not a guarantee. 3364 .Pp 3365 A patch against an empty file applies to a nonexistent file, and vice versa.See Section 3366 .Dq Creating and Removing . 3367 .Pp 3368 .Xr patch 3369 usually produces the correct results, even when it must make many guesses. 3370 However, the results are guaranteed only when the patch is applied to an exact 3371 copy of the file that the patch was generated from. 3372 .Pp 3373 .Em Predicting what Xr patch will do 3374 .Pp 3375 It may not be obvious in advance what 3376 .Xr patch 3377 will do with a complicated or poorly formatted patch. If you are concerned 3378 that the input might cause 3379 .Xr patch 3380 to modify the wrong files, you can use the 3381 .Op --dry-run 3382 option, which causes 3383 .Xr patch 3384 to print the results of applying patches without actually changing any files. 3385 You can then inspect the diagnostics generated by the dry run to see whether 3386 .Xr patch 3387 will modify the files that you expect. If the patch does not do what you want, 3388 you can modify the patch (or the other options to 3389 .Xr patch ) 3390 and try another dry run. Once you are satisfied with the proposed patch you 3391 can apply it by invoking 3392 .Xr patch 3393 as before, but this time without the 3394 .Op --dry-run 3395 option. 3396 .Pp 3397 .Ss Creating and Removing Files 3398 Sometimes when comparing two directories, a file may exist in one directory 3399 but not the other. If you give 3400 .Xr diff 3401 the 3402 .Op -N 3403 or 3404 .Op --new-file 3405 option, or if you supply an old or new file that is named 3406 .Pa /dev/null 3407 or is empty and is dated the Epoch (1970-01-01 00:00:00 UTC), 3408 .Xr diff 3409 outputs a patch that adds or deletes the contents of this file. When given 3410 such a patch, 3411 .Xr patch 3412 normally creates a new file or removes the old file. However, when conforming 3413 to POSIX (see Section 3414 .Dq patch and POSIX ) , 3415 .Xr patch 3416 does not remove the old file, but leaves it empty. The 3417 .Op -E 3418 or 3419 .Op --remove-empty-files 3420 option causes 3421 .Xr patch 3422 to remove output files that are empty after applying a patch, even if the 3423 patch does not appear to be one that removed the file. 3424 .Pp 3425 If the patch appears to create a file that already exists, 3426 .Xr patch 3427 asks for confirmation before applying the patch. 3428 .Pp 3429 .Ss Updating Time Stamps on Patched Files 3430 When 3431 .Xr patch 3432 updates a file, it normally sets the file's last-modified time stamp to the 3433 current time of day. If you are using 3434 .Xr patch 3435 to track a software distribution, this can cause 3436 .Xr make 3437 to incorrectly conclude that a patched file is out of date. For example, if 3438 .Pa syntax.c 3439 depends on 3440 .Pa syntax.y , 3441 and 3442 .Xr patch 3443 updates 3444 .Pa syntax.c 3445 and then 3446 .Pa syntax.y , 3447 then 3448 .Pa syntax.c 3449 will normally appear to be out of date with respect to 3450 .Pa syntax.y 3451 even though its contents are actually up to date. 3452 .Pp 3453 The 3454 .Op -Z 3455 or 3456 .Op --set-utc 3457 option causes 3458 .Xr patch 3459 to set a patched file's modification and access times to the time stamps given 3460 in context diff headers. If the context diff headers do not specify a time 3461 zone, they are assumed to use Coordinated Universal Time (UTC, often known 3462 as GMT). 3463 .Pp 3464 The 3465 .Op -T 3466 or 3467 .Op --set-time 3468 option acts like 3469 .Op -Z 3470 or 3471 .Op --set-utc , 3472 except that it assumes that the context diff headers' time stamps use local 3473 time instead of UTC. This option is not recommended, because patches using 3474 local time cannot easily be used by people in other time zones, and because 3475 local time stamps are ambiguous when local clocks move backwards during daylight-saving 3476 time adjustments. If the context diff headers specify a time zone, this option 3477 is equivalent to 3478 .Op -Z 3479 or 3480 .Op --set-utc . 3481 .Pp 3482 .Xr patch 3483 normally refrains from setting a file's time stamps if the file's original 3484 last-modified time stamp does not match the time given in the diff header, 3485 of if the file's contents do not exactly match the patch. However, if the 3486 .Op -f 3487 or 3488 .Op --force 3489 option is given, the file's time stamps are set regardless. 3490 .Pp 3491 Due to the limitations of the current 3492 .Xr diff 3493 format, 3494 .Xr patch 3495 cannot update the times of files whose contents have not changed. Also, if 3496 you set file time stamps to values other than the current time of day, you 3497 should also remove (e.g., with 3498 .Li make clean ) 3499 all files that depend on the patched files, so that later invocations of 3500 .Xr make 3501 do not get confused by the patched files' times. 3502 .Pp 3503 .Ss Multiple Patches in a File 3504 If the patch file contains more than one patch, and if you do not specify 3505 an input file on the command line, 3506 .Xr patch 3507 tries to apply each patch as if they came from separate patch files. This 3508 means that it determines the name of the file to patch for each patch, and 3509 that it examines the leading text before each patch for file names and prerequisite 3510 revision level (see Section 3511 .Dq Making Patches , 3512 for more on that topic). 3513 .Pp 3514 .Xr patch 3515 uses the following rules to intuit a file name from the leading text before 3516 a patch. First, 3517 .Xr patch 3518 takes an ordered list of candidate file names as follows: 3519 .Pp 3520 .Bl -bullet 3521 .It 3522 If the header is that of a context diff, 3523 .Xr patch 3524 takes the old and new file names in the header. A name is ignored if it does 3525 not have enough slashes to satisfy the 3526 .Op -p Va num 3527 or 3528 .Op --strip= Va num 3529 option. The name 3530 .Pa /dev/null 3531 is also ignored. 3532 .Pp 3533 .It 3534 If there is an 3535 .Li Index: 3536 line in the leading garbage and if either the old and new names are both absent 3537 or if 3538 .Xr patch 3539 is conforming to POSIX, 3540 .Xr patch 3541 takes the name in the 3542 .Li Index: 3543 line. 3544 .Pp 3545 .It 3546 For the purpose of the following rules, the candidate file names are considered 3547 to be in the order (old, new, index), regardless of the order that they appear 3548 in the header. 3549 .El 3550 .Pp 3551 Then 3552 .Xr patch 3553 selects a file name from the candidate list as follows: 3554 .Pp 3555 .Bl -bullet 3556 .It 3557 If some of the named files exist, 3558 .Xr patch 3559 selects the first name if conforming to POSIX, and the best name otherwise. 3560 .Pp 3561 .It 3562 If 3563 .Xr patch 3564 is not ignoring RCS, ClearCase, and SCCS (see Section 3565 .Dq Revision Control ) , 3566 and no named files exist but an RCS, ClearCase, or SCCS master is found, 3567 .Xr patch 3568 selects the first named file with an RCS, ClearCase, or SCCS master. 3569 .Pp 3570 .It 3571 If no named files exist, no RCS, ClearCase, or SCCS master was found, some 3572 names are given, 3573 .Xr patch 3574 is not conforming to POSIX, and the patch appears to create a file, 3575 .Xr patch 3576 selects the best name requiring the creation of the fewest directories. 3577 .Pp 3578 .It 3579 If no file name results from the above heuristics, you are asked for the name 3580 of the file to patch, and 3581 .Xr patch 3582 selects that name. 3583 .El 3584 .Pp 3585 To determine the 3586 .Em best 3587 of a nonempty list of file names, 3588 .Xr patch 3589 first takes all the names with the fewest path name components; of those, 3590 it then takes all the names with the shortest basename; of those, it then 3591 takes all the shortest names; finally, it takes the first remaining name. 3592 .Pp 3593 See Section.Dq patch and POSIX , 3594 to see whether 3595 .Xr patch 3596 is conforming to POSIX. 3597 .Pp 3598 .Ss Applying Patches in Other Directories 3599 The 3600 .Op -d Va directory 3601 or 3602 .Op --directory= Va directory 3603 option to 3604 .Xr patch 3605 makes directory 3606 .Va directory 3607 the current directory for interpreting both file names in the patch file, 3608 and file names given as arguments to other options (such as 3609 .Op -B 3610 and 3611 .Op -o ) . 3612 For example, while in a mail reading program, you can patch a file in the 3613 .Pa /usr/src/emacs 3614 directory directly from a message containing the patch like this: 3615 .Pp 3616 .Bd -literal -offset indent 3617 | patch -d /usr/src/emacs 3618 .Ed 3619 .Pp 3620 Sometimes the file names given in a patch contain leading directories, but 3621 you keep your files in a directory different from the one given in the patch. 3622 In those cases, you can use the 3623 .Op -p Va number 3624 or 3625 .Op --strip= Va number 3626 option to set the file name strip count to 3627 .Va number . 3628 The strip count tells 3629 .Xr patch 3630 how many slashes, along with the directory names between them, to strip from 3631 the front of file names. A sequence of one or more adjacent slashes is counted 3632 as a single slash. By default, 3633 .Xr patch 3634 strips off all leading directories, leaving just the base file names. 3635 .Pp 3636 For example, suppose the file name in the patch file is 3637 .Pa /gnu/src/emacs/etc/NEWS . 3638 Using 3639 .Op -p0 3640 gives the entire file name unmodified, 3641 .Op -p1 3642 gives 3643 .Pa gnu/src/emacs/etc/NEWS 3644 (no leading slash), 3645 .Op -p4 3646 gives 3647 .Pa etc/NEWS , 3648 and not specifying 3649 .Op -p 3650 at all gives 3651 .Pa NEWS . 3652 .Pp 3653 .Xr patch 3654 looks for each file (after any slashes have been stripped) in the current 3655 directory, or if you used the 3656 .Op -d Va directory 3657 option, in that directory. 3658 .Pp 3659 .Ss Backup Files 3660 Normally, 3661 .Xr patch 3662 creates a backup file if the patch does not exactly match the original input 3663 file, because in that case the original data might not be recovered if you 3664 undo the patch with 3665 .Li patch -R 3666 (see Section 3667 .Dq Reversed Patches ) . 3668 However, when conforming to POSIX, 3669 .Xr patch 3670 does not create backup files by default.See Section 3671 .Dq patch and POSIX . 3672 .Pp 3673 The 3674 .Op -b 3675 or 3676 .Op --backup 3677 option causes 3678 .Xr patch 3679 to make a backup file regardless of whether the patch matches the original 3680 input. The 3681 .Op --backup-if-mismatch 3682 option causes 3683 .Xr patch 3684 to create backup files for mismatches files; this is the default when not 3685 conforming to POSIX. The 3686 .Op --no-backup-if-mismatch 3687 option causes 3688 .Xr patch 3689 to not create backup files, even for mismatched patches; this is the default 3690 when conforming to POSIX. 3691 .Pp 3692 When backing up a file that does not exist, an empty, unreadable backup file 3693 is created as a placeholder to represent the nonexistent file. 3694 .Pp 3695 .Ss Backup File Names 3696 Normally, 3697 .Xr patch 3698 renames an original input file into a backup file by appending to its name 3699 the extension 3700 .Li .orig , 3701 or 3702 .Li ~ 3703 if using 3704 .Li .orig 3705 would make the backup file name too long. The 3706 .Op -z Va backup-suffix 3707 or 3708 .Op --suffix= Va backup-suffix 3709 option causes 3710 .Xr patch 3711 to use 3712 .Va backup-suffix 3713 as the backup extension instead. 3714 .Pp 3715 Alternately, you can specify the extension for backup files with the 3716 .Ev SIMPLE_BACKUP_SUFFIX 3717 environment variable, which the options override. 3718 .Pp 3719 .Xr patch 3720 can also create numbered backup files the way GNU Emacs does. With this method, 3721 instead of having a single backup of each file, 3722 .Xr patch 3723 makes a new backup file name each time it patches a file. For example, the 3724 backups of a file named 3725 .Pa sink 3726 would be called, successively, 3727 .Pa sink.~1~ , 3728 .Pa sink.~2~ , 3729 .Pa sink.~3~ , 3730 etc. 3731 .Pp 3732 The 3733 .Op -V Va backup-style 3734 or 3735 .Op --version-control= Va backup-style 3736 option takes as an argument a method for creating backup file names. You can 3737 alternately control the type of backups that 3738 .Xr patch 3739 makes with the 3740 .Ev PATCH_VERSION_CONTROL 3741 environment variable, which the 3742 .Op -V 3743 option overrides. If 3744 .Ev PATCH_VERSION_CONTROL 3745 is not set, the 3746 .Ev VERSION_CONTROL 3747 environment variable is used instead. Please note that these options and variables 3748 control backup file names; they do not affect the choice of revision control 3749 system (see Section 3750 .Dq Revision Control ) . 3751 .Pp 3752 The values of these environment variables and the argument to the 3753 .Op -V 3754 option are like the GNU Emacs 3755 .Li version-control 3756 variable (see Section 3757 .Dq Backup Names , 3758 for more information on backup versions in Emacs). They also recognize synonyms 3759 that are more descriptive. The valid values are listed below; unique abbreviations 3760 are acceptable. 3761 .Pp 3762 .Bl -tag -width Ds 3763 .It t 3764 .It numbered 3765 Always make numbered backups. 3766 .Pp 3767 .It nil 3768 .It existing 3769 Make numbered backups of files that already have them, simple backups of the 3770 others. This is the default. 3771 .Pp 3772 .It never 3773 .It simple 3774 Always make simple backups. 3775 .El 3776 .Pp 3777 You can also tell 3778 .Xr patch 3779 to prepend a prefix, such as a directory name, to produce backup file names. 3780 The 3781 .Op -B Va prefix 3782 or 3783 .Op --prefix= Va prefix 3784 option makes backup files by prepending 3785 .Va prefix 3786 to them. The 3787 .Op -Y Va prefix 3788 or 3789 .Op --basename-prefix= Va prefix 3790 prepends 3791 .Va prefix 3792 to the last file name component of backup file names instead; for example, 3793 .Op -Y ~ 3794 causes the backup name for 3795 .Pa dir/file.c 3796 to be 3797 .Pa dir/~file.c . 3798 If you use either of these prefix options, the suffix-based options are ignored. 3799 .Pp 3800 If you specify the output file with the 3801 .Op -o 3802 option, that file is the one that is backed up, not the input file. 3803 .Pp 3804 Options that affect the names of backup files do not affect whether backups 3805 are made. For example, if you specify the 3806 .Op --no-backup-if-mismatch 3807 option, none of the options described in this section have any affect, because 3808 no backups are made. 3809 .Pp 3810 .Ss Reject File Names 3811 The names for reject files (files containing patches that 3812 .Xr patch 3813 could not find a place to apply) are normally the name of the output file 3814 with 3815 .Li .rej 3816 appended (or 3817 .Li # 3818 if using 3819 .Li .rej 3820 would make the backup file name too long). 3821 .Pp 3822 Alternatively, you can tell 3823 .Xr patch 3824 to place all of the rejected patches in a single file. The 3825 .Op -r Va reject-file 3826 or 3827 .Op --reject-file= Va reject-file 3828 option uses 3829 .Va reject-file 3830 as the reject file name. 3831 .Pp 3832 .Ss Messages and Questions from Xr patch 3833 .Xr patch 3834 can produce a variety of messages, especially if it has trouble decoding its 3835 input. In a few situations where it's not sure how to proceed, 3836 .Xr patch 3837 normally prompts you for more information from the keyboard. There are options 3838 to produce more or fewer messages, to have it not ask for keyboard input, 3839 and to affect the way that file names are quoted in messages. 3840 .Pp 3841 .Xr patch 3842 exits with status 0 if all hunks are applied successfully, 1 if some hunks 3843 cannot be applied, and 2 if there is more serious trouble. When applying a 3844 set of patches in a loop, you should check the exit status, so you don't apply 3845 a later patch to a partially patched file. 3846 .Pp 3847 .Em Controlling the Verbosity of Xr patch 3848 .Pp 3849 You can cause 3850 .Xr patch 3851 to produce more messages by using the 3852 .Op --verbose 3853 option. For example, when you give this option, the message 3854 .Li Hmm... 3855 indicates that 3856 .Xr patch 3857 is reading text in the patch file, attempting to determine whether there is 3858 a patch in that text, and if so, what kind of patch it is. 3859 .Pp 3860 You can inhibit all terminal output from 3861 .Xr patch , 3862 unless an error occurs, by using the 3863 .Op -s , 3864 .Op --quiet , 3865 or 3866 .Op --silent 3867 option. 3868 .Pp 3869 .Em Inhibiting Keyboard Input 3870 .Pp 3871 There are two ways you can prevent 3872 .Xr patch 3873 from asking you any questions. The 3874 .Op -f 3875 or 3876 .Op --force 3877 option assumes that you know what you are doing. It causes 3878 .Xr patch 3879 to do the following: 3880 .Pp 3881 .Bl -bullet 3882 .It 3883 Skip patches that do not contain file names in their headers. 3884 .Pp 3885 .It 3886 Patch files even though they have the wrong version for the 3887 .Li Prereq: 3888 line in the patch; 3889 .Pp 3890 .It 3891 Assume that patches are not reversed even if they look like they are. 3892 .El 3893 .Pp 3894 The 3895 .Op -t 3896 or 3897 .Op --batch 3898 option is similar to 3899 .Op -f , 3900 in that it suppresses questions, but it makes somewhat different assumptions: 3901 .Pp 3902 .Bl -bullet 3903 .It 3904 Skip patches that do not contain file names in their headers (the same as 3905 .Op -f ) . 3906 .Pp 3907 .It 3908 Skip patches for which the file has the wrong version for the 3909 .Li Prereq: 3910 line in the patch; 3911 .Pp 3912 .It 3913 Assume that patches are reversed if they look like they are. 3914 .El 3915 .Pp 3916 .Em Xr patch Quoting Style 3917 .Pp 3918 When 3919 .Xr patch 3920 outputs a file name in a diagnostic message, it can format the name in any 3921 of several ways. This can be useful to output file names unambiguously, even 3922 if they contain punctuation or special characters like newlines. The 3923 .Op --quoting-style= Va word 3924 option controls how names are output. The 3925 .Va word 3926 should be one of the following: 3927 .Pp 3928 .Bl -tag -width Ds 3929 .It literal 3930 Output names as-is. 3931 .It shell 3932 Quote names for the shell if they contain shell metacharacters or would cause 3933 ambiguous output. 3934 .It shell-always 3935 Quote names for the shell, even if they would normally not require quoting. 3936 .It c 3937 Quote names as for a C language string. 3938 .It escape 3939 Quote as with 3940 .Li c 3941 except omit the surrounding double-quote characters. 3942 .El 3943 .Pp 3944 You can specify the default value of the 3945 .Op --quoting-style 3946 option with the environment variable 3947 .Ev QUOTING_STYLE . 3948 If that environment variable is not set, the default value is 3949 .Li shell , 3950 but this default may change in a future version of 3951 .Xr patch . 3952 .Pp 3953 .Ss Xr patch and the POSIX Standard 3954 If you specify the 3955 .Op --posix 3956 option, or set the 3957 .Ev POSIXLY_CORRECT 3958 environment variable, 3959 .Xr patch 3960 conforms more strictly to the POSIX standard, as follows: 3961 .Pp 3962 .Bl -bullet 3963 .It 3964 Take the first existing file from the list (old, new, index) when intuiting 3965 file names from diff headers.See Section 3966 .Dq Multiple Patches . 3967 .Pp 3968 .It 3969 Do not remove files that are removed by a diff.See Section 3970 .Dq Creating and Removing . 3971 .Pp 3972 .It 3973 Do not ask whether to get files from RCS, ClearCase, or SCCS.See Section 3974 .Dq Revision Control . 3975 .Pp 3976 .It 3977 Require that all options precede the files in the command line. 3978 .Pp 3979 .It 3980 Do not backup files, even when there is a mismatch.See Section 3981 .Dq Backups . 3982 .Pp 3983 .El 3984 .Ss GNU Xr patch and Traditional Xr patch 3985 The current version of GNU 3986 .Xr patch 3987 normally follows the POSIX standard.See Section 3988 .Dq patch and POSIX , 3989 for the few exceptions to this general rule. 3990 .Pp 3991 Unfortunately, POSIX redefined the behavior of 3992 .Xr patch 3993 in several important ways. You should be aware of the following differences 3994 if you must interoperate with traditional 3995 .Xr patch , 3996 or with GNU 3997 .Xr patch 3998 version 2.1 and earlier. 3999 .Pp 4000 .Bl -bullet 4001 .It 4002 In traditional 4003 .Xr patch , 4004 the 4005 .Op -p 4006 option's operand was optional, and a bare 4007 .Op -p 4008 was equivalent to 4009 .Op -p0 . 4010 The 4011 .Op -p 4012 option now requires an operand, and 4013 .Op -p 0 4014 is now equivalent to 4015 .Op -p0 . 4016 For maximum compatibility, use options like 4017 .Op -p0 4018 and 4019 .Op -p1 . 4020 .Pp 4021 Also, traditional 4022 .Xr patch 4023 simply counted slashes when stripping path prefixes; 4024 .Xr patch 4025 now counts pathname components. That is, a sequence of one or more adjacent 4026 slashes now counts as a single slash. For maximum portability, avoid sending 4027 patches containing 4028 .Pa // 4029 in file names. 4030 .Pp 4031 .It 4032 In traditional 4033 .Xr patch , 4034 backups were enabled by default. This behavior is now enabled with the 4035 .Op -b 4036 or 4037 .Op --backup 4038 option. 4039 .Pp 4040 Conversely, in POSIX 4041 .Xr patch , 4042 backups are never made, even when there is a mismatch. In GNU 4043 .Xr patch , 4044 this behavior is enabled with the 4045 .Op --no-backup-if-mismatch 4046 option, or by conforming to POSIX. 4047 .Pp 4048 The 4049 .Op -b Va suffix 4050 option of traditional 4051 .Xr patch 4052 is equivalent to the 4053 .Li -b -z Va suffix 4054 options of GNU 4055 .Xr patch . 4056 .Pp 4057 .It 4058 Traditional 4059 .Xr patch 4060 used a complicated (and incompletely documented) method to intuit the name 4061 of the file to be patched from the patch header. This method did not conform 4062 to POSIX, and had a few gotchas. Now 4063 .Xr patch 4064 uses a different, equally complicated (but better documented) method that 4065 is optionally POSIX-conforming; we hope it has fewer gotchas. The two methods 4066 are compatible if the file names in the context diff header and the 4067 .Li Index: 4068 line are all identical after prefix-stripping. Your patch is normally compatible 4069 if each header's file names all contain the same number of slashes. 4070 .Pp 4071 .It 4072 When traditional 4073 .Xr patch 4074 asked the user a question, it sent the question to standard error and looked 4075 for an answer from the first file in the following list that was a terminal: 4076 standard error, standard output, 4077 .Pa /dev/tty , 4078 and standard input. Now 4079 .Xr patch 4080 sends questions to standard output and gets answers from 4081 .Pa /dev/tty . 4082 Defaults for some answers have been changed so that 4083 .Xr patch 4084 never goes into an infinite loop when using default answers. 4085 .Pp 4086 .It 4087 Traditional 4088 .Xr patch 4089 exited with a status value that counted the number of bad hunks, or with status 4090 1 if there was real trouble. Now 4091 .Xr patch 4092 exits with status 1 if some hunks failed, or with 2 if there was real trouble. 4093 .Pp 4094 .It 4095 Limit yourself to the following options when sending instructions meant to 4096 be executed by anyone running GNU 4097 .Xr patch , 4098 traditional 4099 .Xr patch , 4100 or a 4101 .Xr patch 4102 that conforms to POSIX. Spaces are significant in the following list, and 4103 operands are required. 4104 .Pp 4105 .Bd -literal -offset indent 4106 -c 4107 -d dir 4108 -D define 4109 -e 4110 -l 4111 -n 4112 -N 4113 -o outfile 4114 -pnum 4115 -R 4116 -r rejectfile 4117 .Ed 4118 .Pp 4119 .El 4120 .Sh Tips for Making and Using Patches 4121 Use some common sense when making and using patches. For example, when sending 4122 bug fixes to a program's maintainer, send several small patches, one per independent 4123 subject, instead of one large, harder-to-digest patch that covers all the 4124 subjects. 4125 .Pp 4126 Here are some other things you should keep in mind if you are going to distribute 4127 patches for updating a software package. 4128 .Pp 4129 .Ss Tips for Patch Producers 4130 To create a patch that changes an older version of a package into a newer 4131 version, first make a copy of the older and newer versions in adjacent subdirectories. 4132 It is common to do that by unpacking 4133 .Xr tar 4134 archives of the two versions. 4135 .Pp 4136 To generate the patch, use the command 4137 .Li diff -Naur Va old Va new 4138 where 4139 .Va old 4140 and 4141 .Va new 4142 identify the old and new directories. The names 4143 .Va old 4144 and 4145 .Va new 4146 should not contain any slashes. The 4147 .Op -N 4148 option lets the patch create and remove files; 4149 .Op -a 4150 lets the patch update non-text files; 4151 .Op -u 4152 generates useful time stamps and enough context; and 4153 .Op -r 4154 lets the patch update subdirectories. Here is an example command, using Bourne 4155 shell syntax: 4156 .Pp 4157 .Bd -literal -offset indent 4158 diff -Naur gcc-3.0.3 gcc-3.0.4 4159 .Ed 4160 .Pp 4161 Tell your recipients how to apply the patches. This should include which working 4162 directory to use, and which 4163 .Xr patch 4164 options to use; the option 4165 .Li -p1 4166 is recommended. Test your procedure by pretending to be a recipient and applying 4167 your patches to a copy of the original files. 4168 .Pp 4169 See Section.Dq Avoiding Common Mistakes , 4170 for how to avoid common mistakes when generating a patch. 4171 .Pp 4172 .Ss Tips for Patch Consumers 4173 A patch producer should tell recipients how to apply the patches, so the first 4174 rule of thumb for a patch consumer is to follow the instructions supplied 4175 with the patch. 4176 .Pp 4177 GNU 4178 .Xr diff 4179 can analyze files with arbitrarily long lines and files that end in incomplete 4180 lines. However, older versions of 4181 .Xr patch 4182 cannot patch such files. If you are having trouble applying such patches, 4183 try upgrading to a recent version of GNU 4184 .Xr patch . 4185 .Pp 4186 .Ss Avoiding Common Mistakes 4187 When producing a patch for multiple files, apply 4188 .Xr diff 4189 to directories whose names do not have slashes. This reduces confusion when 4190 the patch consumer specifies the 4191 .Op -p Va number 4192 option, since this option can have surprising results when the old and new 4193 file names have different numbers of slashes. For example, do not send a patch 4194 with a header that looks like this: 4195 .Pp 4196 .Bd -literal -offset indent 4197 diff -Naur v2.0.29/prog/README prog/README 4198 --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 4199 +++ prog/README 2002-03-17 20:49:32.442260588 -0800 4200 .Ed 4201 .Pp 4202 because the two file names have different numbers of slashes, and different 4203 versions of 4204 .Xr patch 4205 interpret the file names differently. To avoid confusion, send output that 4206 looks like this instead: 4207 .Pp 4208 .Bd -literal -offset indent 4209 diff -Naur v2.0.29/prog/README v2.0.30/prog/README 4210 --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 4211 +++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800 4212 .Ed 4213 .Pp 4214 Make sure you have specified the file names correctly, either in a context 4215 diff header or with an 4216 .Li Index: 4217 line. Take care to not send out reversed patches, since these make people 4218 wonder whether they have already applied the patch. 4219 .Pp 4220 Avoid sending patches that compare backup file names like 4221 .Pa README.orig 4222 or 4223 .Pa README~ , 4224 since this might confuse 4225 .Xr patch 4226 into patching a backup file instead of the real file. Instead, send patches 4227 that compare the same base file names in different directories, e.g. 4228 .Pa old/README 4229 and 4230 .Pa new/README . 4231 .Pp 4232 To save people from partially applying a patch before other patches that should 4233 have gone before it, you can make the first patch in the patch file update 4234 a file with a name like 4235 .Pa patchlevel.h 4236 or 4237 .Pa version.c , 4238 which contains a patch level or version number. If the input file contains 4239 the wrong version number, 4240 .Xr patch 4241 will complain immediately. 4242 .Pp 4243 An even clearer way to prevent this problem is to put a 4244 .Li Prereq: 4245 line before the patch. If the leading text in the patch file contains a line 4246 that starts with 4247 .Li Prereq: , 4248 .Xr patch 4249 takes the next word from that line (normally a version number) and checks 4250 whether the next input file contains that word, preceded and followed by either 4251 white space or a newline. If not, 4252 .Xr patch 4253 prompts you for confirmation before proceeding. This makes it difficult to 4254 accidentally apply patches in the wrong order. 4255 .Pp 4256 .Ss Generating Smaller Patches 4257 The simplest way to generate a patch is to use 4258 .Li diff -Naur 4259 (see Section 4260 .Dq Tips for Patch Producers ) , 4261 but you might be able to reduce the size of the patch by renaming or removing 4262 some files before making the patch. If the older version of the package contains 4263 any files that the newer version does not, or if any files have been renamed 4264 between the two versions, make a list of 4265 .Xr rm 4266 and 4267 .Xr mv 4268 commands for the user to execute in the old version directory before applying 4269 the patch. Then run those commands yourself in the scratch directory. 4270 .Pp 4271 If there are any files that you don't need to include in the patch because 4272 they can easily be rebuilt from other files (for example, 4273 .Pa TAGS 4274 and output from 4275 .Xr yacc 4276 and 4277 .Xr makeinfo ) , 4278 exclude them from the patch by giving 4279 .Xr diff 4280 the 4281 .Op -x Va pattern 4282 option (see Section 4283 .Dq Comparing Directories ) . 4284 If you want your patch to modify a derived file because your recipients lack 4285 tools to build it, make sure that the patch for the derived file follows any 4286 patches for files that it depends on, so that the recipients' time stamps 4287 will not confuse 4288 .Xr make . 4289 .Pp 4290 Now you can create the patch using 4291 .Li diff -Naur . 4292 Make sure to specify the scratch directory first and the newer directory second. 4293 .Pp 4294 Add to the top of the patch a note telling the user any 4295 .Xr rm 4296 and 4297 .Xr mv 4298 commands to run before applying the patch. Then you can remove the scratch 4299 directory. 4300 .Pp 4301 You can also shrink the patch size by using fewer lines of context, but bear 4302 in mind that 4303 .Xr patch 4304 typically needs at least two lines for proper operation when patches do not 4305 exactly match the input files. 4306 .Pp 4307 .Sh Invoking Xr cmp 4308 The 4309 .Xr cmp 4310 command compares two files, and if they differ, tells the first byte and line 4311 number where they differ or reports that one file is a prefix of the other. 4312 Bytes and lines are numbered starting with 1. The arguments of 4313 .Xr cmp 4314 are as follows: 4315 .Pp 4316 .Bd -literal -offset indent 4317 cmp options... from-file [to-file [from-skip [to-skip]]] 4318 .Ed 4319 .Pp 4320 The file name 4321 .Pa - 4322 is always the standard input. 4323 .Xr cmp 4324 also uses the standard input if one file name is omitted. The 4325 .Va from-skip 4326 and 4327 .Va to-skip 4328 operands specify how many bytes to ignore at the start of each file; they 4329 are equivalent to the 4330 .Op --ignore-initial= Va from-skip: Va to-skip 4331 option. 4332 .Pp 4333 By default, 4334 .Xr cmp 4335 outputs nothing if the two files have the same contents. If one file is a 4336 prefix of the other, 4337 .Xr cmp 4338 prints to standard error a message of the following form: 4339 .Pp 4340 .Bd -literal -offset indent 4341 cmp: EOF on shorter-file 4342 .Ed 4343 .Pp 4344 Otherwise, 4345 .Xr cmp 4346 prints to standard output a message of the following form: 4347 .Pp 4348 .Bd -literal -offset indent 4349 from-file to-file differ: char byte-number, line line-number 4350 .Ed 4351 .Pp 4352 The message formats can differ outside the POSIX locale. Also, POSIX allows 4353 the EOF message to be followed by a blank and some additional information. 4354 .Pp 4355 An exit status of 0 means no differences were found, 1 means some differences 4356 were found, and 2 means trouble. 4357 .Pp 4358 .Ss Options to Xr cmp 4359 Below is a summary of all of the options that GNU 4360 .Xr cmp 4361 accepts. Most options have two equivalent names, one of which is a single 4362 letter preceded by 4363 .Li - , 4364 and the other of which is a long name preceded by 4365 .Li -- . 4366 Multiple single letter options (unless they take an argument) can be combined 4367 into a single command line word: 4368 .Op -bl 4369 is equivalent to 4370 .Op -b -l . 4371 .Pp 4372 .Bl -tag -width Ds 4373 .It -b 4374 .It --print-bytes 4375 Print the differing bytes. Display control bytes as a 4376 .Li ^ 4377 followed by a letter of the alphabet and precede bytes that have the high 4378 bit set with 4379 .Li M- 4380 (which stands for \(lqmeta\(rq). 4381 .Pp 4382 .It --help 4383 Output a summary of usage and then exit. 4384 .Pp 4385 .It -i Va skip 4386 .It --ignore-initial= Va skip 4387 Ignore any differences in the first 4388 .Va skip 4389 bytes of the input files. Treat files with fewer than 4390 .Va skip 4391 bytes as if they are empty. If 4392 .Va skip 4393 is of the form 4394 .Op Va from-skip: Va to-skip , 4395 skip the first 4396 .Va from-skip 4397 bytes of the first input file and the first 4398 .Va to-skip 4399 bytes of the second. 4400 .Pp 4401 .It -l 4402 .It --verbose 4403 Output the (decimal) byte numbers and (octal) values of all differing bytes, 4404 instead of the default standard output. 4405 .Pp 4406 .It -n Va count 4407 .It --bytes= Va count 4408 Compare at most 4409 .Va count 4410 input bytes. 4411 .Pp 4412 .It -s 4413 .It --quiet 4414 .It --silent 4415 Do not print anything; only return an exit status indicating whether the files 4416 differ. 4417 .Pp 4418 .It -v 4419 .It --version 4420 Output version information and then exit. 4421 .El 4422 .Pp 4423 In the above table, operands that are byte counts are normally decimal, but 4424 may be preceded by 4425 .Li 0 4426 for octal and 4427 .Li 0x 4428 for hexadecimal. 4429 .Pp 4430 A byte count can be followed by a suffix to specify a multiple of that count; 4431 in this case an omitted integer is understood to be 1. A bare size letter, 4432 or one followed by 4433 .Li iB , 4434 specifies a multiple using powers of 1024. A size letter followed by 4435 .Li B 4436 specifies powers of 1000 instead. For example, 4437 .Op -n 4M 4438 and 4439 .Op -n 4MiB 4440 are equivalent to 4441 .Op -n 4194304 , 4442 whereas 4443 .Op -n 4MB 4444 is equivalent to 4445 .Op -n 4000000 . 4446 This notation is upward compatible with the 4447 .Lk http://www.bipm.fr/enus/3_SI/si-prefixes.html 4448 for decimal multiples and with the 4449 .Lk http://physics.nist.gov/cuu/Units/binary.html . 4450 .Pp 4451 The following suffixes are defined. Large sizes like 4452 .Li 1Y 4453 may be rejected by your computer due to limitations of its arithmetic. 4454 .Pp 4455 .Bl -tag -width Ds 4456 .It kB 4457 kilobyte: 10^3 = 1000. 4458 .It k 4459 .It K 4460 .It KiB 4461 kibibyte: 2^10 = 1024. 4462 .Li K 4463 is special: the SI prefix is 4464 .Li k 4465 and the IEC 60027-2 prefix is 4466 .Li Ki , 4467 but tradition and POSIX use 4468 .Li k 4469 to mean 4470 .Li KiB . 4471 .It MB 4472 megabyte: 10^6 = 1,000,000. 4473 .It M 4474 .It MiB 4475 mebibyte: 2^20 = 1,048,576. 4476 .It GB 4477 gigabyte: 10^9 = 1,000,000,000. 4478 .It G 4479 .It GiB 4480 gibibyte: 2^30 = 1,073,741,824. 4481 .It TB 4482 terabyte: 10^12 = 1,000,000,000,000. 4483 .It T 4484 .It TiB 4485 tebibyte: 2^40 = 1,099,511,627,776. 4486 .It PB 4487 petabyte: 10^15 = 1,000,000,000,000,000. 4488 .It P 4489 .It PiB 4490 pebibyte: 2^50 = 1,125,899,906,842,624. 4491 .It EB 4492 exabyte: 10^18 = 1,000,000,000,000,000,000. 4493 .It E 4494 .It EiB 4495 exbibyte: 2^60 = 1,152,921,504,606,846,976. 4496 .It ZB 4497 zettabyte: 10^21 = 1,000,000,000,000,000,000,000 4498 .It Z 4499 .It ZiB 4500 2^70 = 1,180,591,620,717,411,303,424. ( 4501 .Li Zi 4502 is a GNU extension to IEC 60027-2.) 4503 .It YB 4504 yottabyte: 10^24 = 1,000,000,000,000,000,000,000,000. 4505 .It Y 4506 .It YiB 4507 2^80 = 1,208,925,819,614,629,174,706,176. ( 4508 .Li Yi 4509 is a GNU extension to IEC 60027-2.) 4510 .El 4511 .Pp 4512 .Sh Invoking Xr diff 4513 The format for running the 4514 .Xr diff 4515 command is: 4516 .Pp 4517 .Bd -literal -offset indent 4518 diff options... files... 4519 .Ed 4520 .Pp 4521 In the simplest case, two file names 4522 .Va from-file 4523 and 4524 .Va to-file 4525 are given, and 4526 .Xr diff 4527 compares the contents of 4528 .Va from-file 4529 and 4530 .Va to-file . 4531 A file name of 4532 .Pa - 4533 stands for text read from the standard input. As a special case, 4534 .Li diff - - 4535 compares a copy of standard input to itself. 4536 .Pp 4537 If one file is a directory and the other is not, 4538 .Xr diff 4539 compares the file in the directory whose name is that of the non-directory. 4540 The non-directory file must not be 4541 .Pa - . 4542 .Pp 4543 If two file names are given and both are directories, 4544 .Xr diff 4545 compares corresponding files in both directories, in alphabetical order; this 4546 comparison is not recursive unless the 4547 .Op -r 4548 or 4549 .Op --recursive 4550 option is given. 4551 .Xr diff 4552 never compares the actual contents of a directory as if it were a file. The 4553 file that is fully specified may not be standard input, because standard input 4554 is nameless and the notion of \(lqfile with the same name\(rq does not apply. 4555 .Pp 4556 If the 4557 .Op --from-file= Va file 4558 option is given, the number of file names is arbitrary, and 4559 .Va file 4560 is compared to each named file. Similarly, if the 4561 .Op --to-file= Va file 4562 option is given, each named file is compared to 4563 .Va file . 4564 .Pp 4565 .Xr diff 4566 options begin with 4567 .Li - , 4568 so normally file names may not begin with 4569 .Li - . 4570 However, 4571 .Op -- 4572 as an argument by itself treats the remaining arguments as file names even 4573 if they begin with 4574 .Li - . 4575 .Pp 4576 An exit status of 0 means no differences were found, 1 means some differences 4577 were found, and 2 means trouble. Normally, differing binary files count as 4578 trouble, but this can be altered by using the 4579 .Op -a 4580 or 4581 .Op --text 4582 option, or the 4583 .Op -q 4584 or 4585 .Op --brief 4586 option. 4587 .Pp 4588 .Ss Options to Xr diff 4589 Below is a summary of all of the options that GNU 4590 .Xr diff 4591 accepts. Most options have two equivalent names, one of which is a single 4592 letter preceded by 4593 .Li - , 4594 and the other of which is a long name preceded by 4595 .Li -- . 4596 Multiple single letter options (unless they take an argument) can be combined 4597 into a single command line word: 4598 .Op -ac 4599 is equivalent to 4600 .Op -a -c . 4601 Long named options can be abbreviated to any unique prefix of their name. 4602 Brackets ([ and ]) indicate that an option takes an optional argument. 4603 .Pp 4604 .Bl -tag -width Ds 4605 .It -a 4606 .It --text 4607 Treat all files as text and compare them line-by-line, even if they do not 4608 seem to be text.See Section 4609 .Dq Binary . 4610 .Pp 4611 .It -b 4612 .It --ignore-space-change 4613 Ignore changes in amount of white space.See Section 4614 .Dq White Space . 4615 .Pp 4616 .It -B 4617 .It --ignore-blank-lines 4618 Ignore changes that just insert or delete blank lines.See Section 4619 .Dq Blank Lines . 4620 .Pp 4621 .It --binary 4622 Read and write data in binary mode.See Section 4623 .Dq Binary . 4624 .Pp 4625 .It -c 4626 Use the context output format, showing three lines of context.See Section 4627 .Dq Context Format . 4628 .Pp 4629 .It -C Va lines 4630 .It --context[= Va lines] 4631 Use the context output format, showing 4632 .Va lines 4633 (an integer) lines of context, or three if 4634 .Va lines 4635 is not given.See Section 4636 .Dq Context Format . 4637 For proper operation, 4638 .Xr patch 4639 typically needs at least two lines of context. 4640 .Pp 4641 On older systems, 4642 .Xr diff 4643 supports an obsolete option 4644 .Op - Va lines 4645 that has effect when combined with 4646 .Op -c 4647 or 4648 .Op -p . 4649 POSIX 1003.1-2001 (see Section 4650 .Dq Standards conformance ) 4651 does not allow this; use 4652 .Op -C Va lines 4653 instead. 4654 .Pp 4655 .It --changed-group-format= Va format 4656 Use 4657 .Va format 4658 to output a line group containing differing lines from both files in if-then-else 4659 format.See Section 4660 .Dq Line Group Formats . 4661 .Pp 4662 .It -d 4663 .It --minimal 4664 Change the algorithm perhaps find a smaller set of changes. This makes 4665 .Xr diff 4666 slower (sometimes much slower).See Section 4667 .Dq diff Performance . 4668 .Pp 4669 .It -D Va name 4670 .It --ifdef= Va name 4671 Make merged 4672 .Li #ifdef 4673 format output, conditional on the preprocessor macro 4674 .Va name . 4675 See Section.Dq If-then-else . 4676 .Pp 4677 .It -e 4678 .It --ed 4679 Make output that is a valid 4680 .Xr ed 4681 script.See Section 4682 .Dq ed Scripts . 4683 .Pp 4684 .It -E 4685 .It --ignore-tab-expansion 4686 Ignore changes due to tab expansion.See Section 4687 .Dq White Space . 4688 .Pp 4689 .It -f 4690 .It --forward-ed 4691 Make output that looks vaguely like an 4692 .Xr ed 4693 script but has changes in the order they appear in the file.See Section 4694 .Dq Forward ed . 4695 .Pp 4696 .It -F Va regexp 4697 .It --show-function-line= Va regexp 4698 In context and unified format, for each hunk of differences, show some of 4699 the last preceding line that matches 4700 .Va regexp . 4701 See Section.Dq Specified Headings . 4702 .Pp 4703 .It --from-file= Va file 4704 Compare 4705 .Va file 4706 to each operand; 4707 .Va file 4708 may be a directory. 4709 .Pp 4710 .It --help 4711 Output a summary of usage and then exit. 4712 .Pp 4713 .It --horizon-lines= Va lines 4714 Do not discard the last 4715 .Va lines 4716 lines of the common prefix and the first 4717 .Va lines 4718 lines of the common suffix.See Section 4719 .Dq diff Performance . 4720 .Pp 4721 .It -i 4722 .It --ignore-case 4723 Ignore changes in case; consider upper- and lower-case letters equivalent.See Section 4724 .Dq Case Folding . 4725 .Pp 4726 .It -I Va regexp 4727 .It --ignore-matching-lines= Va regexp 4728 Ignore changes that just insert or delete lines that match 4729 .Va regexp . 4730 See Section.Dq Specified Lines . 4731 .Pp 4732 .It --ignore-file-name-case 4733 Ignore case when comparing file names during recursive comparison.See Section 4734 .Dq Comparing Directories . 4735 .Pp 4736 .It -l 4737 .It --paginate 4738 Pass the output through 4739 .Xr pr 4740 to paginate it.See Section 4741 .Dq Pagination . 4742 .Pp 4743 .It --label= Va label 4744 Use 4745 .Va label 4746 instead of the file name in the context format (see Section 4747 .Dq Context Format ) 4748 and unified format (see Section 4749 .Dq Unified Format ) 4750 headers.See Section 4751 .Dq RCS . 4752 .Pp 4753 .It --left-column 4754 Print only the left column of two common lines in side by side format.See Section 4755 .Dq Side by Side Format . 4756 .Pp 4757 .It --line-format= Va format 4758 Use 4759 .Va format 4760 to output all input lines in if-then-else format.See Section 4761 .Dq Line Formats . 4762 .Pp 4763 .It -n 4764 .It --rcs 4765 Output RCS-format diffs; like 4766 .Op -f 4767 except that each command specifies the number of lines affected.See Section 4768 .Dq RCS . 4769 .Pp 4770 .It -N 4771 .It --new-file 4772 In directory comparison, if a file is found in only one directory, treat it 4773 as present but empty in the other directory.See Section 4774 .Dq Comparing Directories . 4775 .Pp 4776 .It --new-group-format= Va format 4777 Use 4778 .Va format 4779 to output a group of lines taken from just the second file in if-then-else 4780 format.See Section 4781 .Dq Line Group Formats . 4782 .Pp 4783 .It --new-line-format= Va format 4784 Use 4785 .Va format 4786 to output a line taken from just the second file in if-then-else format.See Section 4787 .Dq Line Formats . 4788 .Pp 4789 .It --old-group-format= Va format 4790 Use 4791 .Va format 4792 to output a group of lines taken from just the first file in if-then-else 4793 format.See Section 4794 .Dq Line Group Formats . 4795 .Pp 4796 .It --old-line-format= Va format 4797 Use 4798 .Va format 4799 to output a line taken from just the first file in if-then-else format.See Section 4800 .Dq Line Formats . 4801 .Pp 4802 .It -p 4803 .It --show-c-function 4804 Show which C function each change is in.See Section 4805 .Dq C Function Headings . 4806 .Pp 4807 .It -q 4808 .It --brief 4809 Report only whether the files differ, not the details of the differences.See Section 4810 .Dq Brief . 4811 .Pp 4812 .It -r 4813 .It --recursive 4814 When comparing directories, recursively compare any subdirectories found.See Section 4815 .Dq Comparing Directories . 4816 .Pp 4817 .It -s 4818 .It --report-identical-files 4819 Report when two files are the same.See Section 4820 .Dq Comparing Directories . 4821 .Pp 4822 .It -S Va file 4823 .It --starting-file= Va file 4824 When comparing directories, start with the file 4825 .Va file . 4826 This is used for resuming an aborted comparison.See Section 4827 .Dq Comparing Directories . 4828 .Pp 4829 .It --speed-large-files 4830 Use heuristics to speed handling of large files that have numerous scattered 4831 small changes.See Section 4832 .Dq diff Performance . 4833 .Pp 4834 .It --strip-trailing-cr 4835 Strip any trailing carriage return at the end of an input line.See Section 4836 .Dq Binary . 4837 .Pp 4838 .It --suppress-common-lines 4839 Do not print common lines in side by side format.See Section 4840 .Dq Side by Side Format . 4841 .Pp 4842 .It -t 4843 .It --expand-tabs 4844 Expand tabs to spaces in the output, to preserve the alignment of tabs in 4845 the input files.See Section 4846 .Dq Tabs . 4847 .Pp 4848 .It -T 4849 .It --initial-tab 4850 Output a tab rather than a space before the text of a line in normal or context 4851 format. This causes the alignment of tabs in the line to look normal.See Section 4852 .Dq Tabs . 4853 .Pp 4854 .It --tabsize= Va columns 4855 Assume that tab stops are set every 4856 .Va columns 4857 (default 8) print columns.See Section 4858 .Dq Tabs . 4859 .Pp 4860 .It --to-file= Va file 4861 Compare each operand to 4862 .Va file 4863 ; 4864 .Va file 4865 may be a directory. 4866 .Pp 4867 .It -u 4868 Use the unified output format, showing three lines of context.See Section 4869 .Dq Unified Format . 4870 .Pp 4871 .It --unchanged-group-format= Va format 4872 Use 4873 .Va format 4874 to output a group of common lines taken from both files in if-then-else format.See Section 4875 .Dq Line Group Formats . 4876 .Pp 4877 .It --unchanged-line-format= Va format 4878 Use 4879 .Va format 4880 to output a line common to both files in if-then-else format.See Section 4881 .Dq Line Formats . 4882 .Pp 4883 .It --unidirectional-new-file 4884 When comparing directories, if a file appears only in the second directory 4885 of the two, treat it as present but empty in the other.See Section 4886 .Dq Comparing Directories . 4887 .Pp 4888 .It -U Va lines 4889 .It --unified[= Va lines] 4890 Use the unified output format, showing 4891 .Va lines 4892 (an integer) lines of context, or three if 4893 .Va lines 4894 is not given.See Section 4895 .Dq Unified Format . 4896 For proper operation, 4897 .Xr patch 4898 typically needs at least two lines of context. 4899 .Pp 4900 On older systems, 4901 .Xr diff 4902 supports an obsolete option 4903 .Op - Va lines 4904 that has effect when combined with 4905 .Op -u . 4906 POSIX 1003.1-2001 (see Section 4907 .Dq Standards conformance ) 4908 does not allow this; use 4909 .Op -U Va lines 4910 instead. 4911 .Pp 4912 .It -v 4913 .It --version 4914 Output version information and then exit. 4915 .Pp 4916 .It -w 4917 .It --ignore-all-space 4918 Ignore white space when comparing lines.See Section 4919 .Dq White Space . 4920 .Pp 4921 .It -W Va columns 4922 .It --width= Va columns 4923 Output at most 4924 .Va columns 4925 (default 130) print columns per line in side by side format.See Section 4926 .Dq Side by Side Format . 4927 .Pp 4928 .It -x Va pattern 4929 .It --exclude= Va pattern 4930 When comparing directories, ignore files and subdirectories whose basenames 4931 match 4932 .Va pattern . 4933 See Section.Dq Comparing Directories . 4934 .Pp 4935 .It -X Va file 4936 .It --exclude-from= Va file 4937 When comparing directories, ignore files and subdirectories whose basenames 4938 match any pattern contained in 4939 .Va file . 4940 See Section.Dq Comparing Directories . 4941 .Pp 4942 .It -y 4943 .It --side-by-side 4944 Use the side by side output format.See Section 4945 .Dq Side by Side Format . 4946 .El 4947 .Pp 4948 .Sh Invoking Xr diff3 4949 The 4950 .Xr diff3 4951 command compares three files and outputs descriptions of their differences. 4952 Its arguments are as follows: 4953 .Pp 4954 .Bd -literal -offset indent 4955 diff3 options... mine older yours 4956 .Ed 4957 .Pp 4958 The files to compare are 4959 .Va mine , 4960 .Va older , 4961 and 4962 .Va yours . 4963 At most one of these three file names may be 4964 .Pa - , 4965 which tells 4966 .Xr diff3 4967 to read the standard input for that file. 4968 .Pp 4969 An exit status of 0 means 4970 .Xr diff3 4971 was successful, 1 means some conflicts were found, and 2 means trouble. 4972 .Pp 4973 .Ss Options to Xr diff3 4974 Below is a summary of all of the options that GNU 4975 .Xr diff3 4976 accepts. Multiple single letter options (unless they take an argument) can 4977 be combined into a single command line argument. 4978 .Pp 4979 .Bl -tag -width Ds 4980 .It -a 4981 .It --text 4982 Treat all files as text and compare them line-by-line, even if they do not 4983 appear to be text.See Section 4984 .Dq Binary . 4985 .Pp 4986 .It -A 4987 .It --show-all 4988 Incorporate all unmerged changes from 4989 .Va older 4990 to 4991 .Va yours 4992 into 4993 .Va mine , 4994 surrounding conflicts with bracket lines.See Section 4995 .Dq Marking Conflicts . 4996 .Pp 4997 .It --diff-program= Va program 4998 Use the compatible comparison program 4999 .Va program 5000 to compare files instead of 5001 .Xr diff . 5002 .Pp 5003 .It -e 5004 .It --ed 5005 Generate an 5006 .Xr ed 5007 script that incorporates all the changes from 5008 .Va older 5009 to 5010 .Va yours 5011 into 5012 .Va mine . 5013 See Section.Dq Which Changes . 5014 .Pp 5015 .It -E 5016 .It --show-overlap 5017 Like 5018 .Op -e , 5019 except bracket lines from overlapping changes' first and third files.See Section 5020 .Dq Marking Conflicts . 5021 With 5022 .Op -E , 5023 an overlapping change looks like this: 5024 .Pp 5025 .Bd -literal -offset indent 5026 <<<<<<< mine 5027 lines from mine 5028 ======= 5029 lines from yours 5030 >>>>>>> yours 5031 .Ed 5032 .Pp 5033 .It --help 5034 Output a summary of usage and then exit. 5035 .Pp 5036 .It -i 5037 Generate 5038 .Li w 5039 and 5040 .Li q 5041 commands at the end of the 5042 .Xr ed 5043 script for System V compatibility. This option must be combined with one of 5044 the 5045 .Op -AeExX3 5046 options, and may not be combined with 5047 .Op -m . 5048 See Section.Dq Saving the Changed File . 5049 .Pp 5050 .It --label= Va label 5051 Use the label 5052 .Va label 5053 for the brackets output by the 5054 .Op -A , 5055 .Op -E 5056 and 5057 .Op -X 5058 options. This option may be given up to three times, one for each input file. 5059 The default labels are the names of the input files. Thus 5060 .Li diff3 --label X --label Y --label Z -m A B C 5061 acts like 5062 .Li diff3 -m A B C , 5063 except that the output looks like it came from files named 5064 .Li X , 5065 .Li Y 5066 and 5067 .Li Z 5068 rather than from files named 5069 .Li A , 5070 .Li B 5071 and 5072 .Li C . 5073 See Section.Dq Marking Conflicts . 5074 .Pp 5075 .It -m 5076 .It --merge 5077 Apply the edit script to the first file and send the result to standard output. 5078 Unlike piping the output from 5079 .Xr diff3 5080 to 5081 .Xr ed , 5082 this works even for binary files and incomplete lines. 5083 .Op -A 5084 is assumed if no edit script option is specified.See Section 5085 .Dq Bypassing ed . 5086 .Pp 5087 .It --strip-trailing-cr 5088 Strip any trailing carriage return at the end of an input line.See Section 5089 .Dq Binary . 5090 .Pp 5091 .It -T 5092 .It --initial-tab 5093 Output a tab rather than two spaces before the text of a line in normal format. 5094 This causes the alignment of tabs in the line to look normal.See Section 5095 .Dq Tabs . 5096 .Pp 5097 .It -v 5098 .It --version 5099 Output version information and then exit. 5100 .Pp 5101 .It -x 5102 .It --overlap-only 5103 Like 5104 .Op -e , 5105 except output only the overlapping changes.See Section 5106 .Dq Which Changes . 5107 .Pp 5108 .It -X 5109 Like 5110 .Op -E , 5111 except output only the overlapping changes. In other words, like 5112 .Op -x , 5113 except bracket changes as in 5114 .Op -E . 5115 See Section.Dq Marking Conflicts . 5116 .Pp 5117 .It -3 5118 .It --easy-only 5119 Like 5120 .Op -e , 5121 except output only the nonoverlapping changes.See Section 5122 .Dq Which Changes . 5123 .El 5124 .Pp 5125 .Sh Invoking Xr patch 5126 Normally 5127 .Xr patch 5128 is invoked like this: 5129 .Pp 5130 .Bd -literal -offset indent 5131 patch <patchfile 5132 .Ed 5133 .Pp 5134 The full format for invoking 5135 .Xr patch 5136 is: 5137 .Pp 5138 .Bd -literal -offset indent 5139 patch options... [origfile [patchfile]] 5140 .Ed 5141 .Pp 5142 You can also specify where to read the patch from with the 5143 .Op -i Va patchfile 5144 or 5145 .Op --input= Va patchfile 5146 option. If you do not specify 5147 .Va patchfile , 5148 or if 5149 .Va patchfile 5150 is 5151 .Pa - , 5152 .Xr patch 5153 reads the patch (that is, the 5154 .Xr diff 5155 output) from the standard input. 5156 .Pp 5157 If you do not specify an input file on the command line, 5158 .Xr patch 5159 tries to intuit from the 5160 .Em leading text 5161 (any text in the patch that comes before the 5162 .Xr diff 5163 output) which file to edit.See Section 5164 .Dq Multiple Patches . 5165 .Pp 5166 By default, 5167 .Xr patch 5168 replaces the original input file with the patched version, possibly after 5169 renaming the original file into a backup file (see Section 5170 .Dq Backup Names , 5171 for a description of how 5172 .Xr patch 5173 names backup files). You can also specify where to put the output with the 5174 .Op -o Va file 5175 or 5176 .Op --output= Va file 5177 option; however, do not use this option if 5178 .Va file 5179 is one of the input files. 5180 .Pp 5181 .Ss Options to Xr patch 5182 Here is a summary of all of the options that GNU 5183 .Xr patch 5184 accepts.See Section 5185 .Dq patch and Tradition , 5186 for which of these options are safe to use in older versions of 5187 .Xr patch . 5188 .Pp 5189 Multiple single-letter options that do not take an argument can be combined 5190 into a single command line argument with only one dash. 5191 .Pp 5192 .Bl -tag -width Ds 5193 .It -b 5194 .It --backup 5195 Back up the original contents of each file, even if backups would normally 5196 not be made.See Section 5197 .Dq Backups . 5198 .Pp 5199 .It -B Va prefix 5200 .It --prefix= Va prefix 5201 Prepend 5202 .Va prefix 5203 to backup file names.See Section 5204 .Dq Backup Names . 5205 .Pp 5206 .It --backup-if-mismatch 5207 Back up the original contents of each file if the patch does not exactly match 5208 the file. This is the default behavior when not conforming to POSIX.See Section 5209 .Dq Backups . 5210 .Pp 5211 .It --binary 5212 Read and write all files in binary mode, except for standard output and 5213 .Pa /dev/tty . 5214 This option has no effect on POSIX-conforming systems like GNU/Linux. On systems 5215 where this option makes a difference, the patch should be generated by 5216 .Li diff -a --binary . 5217 See Section.Dq Binary . 5218 .Pp 5219 .It -c 5220 .It --context 5221 Interpret the patch file as a context diff.See Section 5222 .Dq patch Input . 5223 .Pp 5224 .It -d Va directory 5225 .It --directory= Va directory 5226 Make directory 5227 .Va directory 5228 the current directory for interpreting both file names in the patch file, 5229 and file names given as arguments to other options.See Section 5230 .Dq patch Directories . 5231 .Pp 5232 .It -D Va name 5233 .It --ifdef= Va name 5234 Make merged if-then-else output using 5235 .Va name . 5236 See Section.Dq If-then-else . 5237 .Pp 5238 .It --dry-run 5239 Print the results of applying the patches without actually changing any files.See Section 5240 .Dq Dry Runs . 5241 .Pp 5242 .It -e 5243 .It --ed 5244 Interpret the patch file as an 5245 .Xr ed 5246 script.See Section 5247 .Dq patch Input . 5248 .Pp 5249 .It -E 5250 .It --remove-empty-files 5251 Remove output files that are empty after the patches have been applied.See Section 5252 .Dq Creating and Removing . 5253 .Pp 5254 .It -f 5255 .It --force 5256 Assume that the user knows exactly what he or she is doing, and do not ask 5257 any questions.See Section 5258 .Dq patch Messages . 5259 .Pp 5260 .It -F Va lines 5261 .It --fuzz= Va lines 5262 Set the maximum fuzz factor to 5263 .Va lines . 5264 See Section.Dq Inexact . 5265 .Pp 5266 .It -g Va num 5267 .It --get= Va num 5268 If 5269 .Va num 5270 is positive, get input files from a revision control system as necessary; 5271 if zero, do not get the files; if negative, ask the user whether to get the 5272 files.See Section 5273 .Dq Revision Control . 5274 .Pp 5275 .It --help 5276 Output a summary of usage and then exit. 5277 .Pp 5278 .It -i Va patchfile 5279 .It --input= Va patchfile 5280 Read the patch from 5281 .Va patchfile 5282 rather than from standard input.See Section 5283 .Dq patch Options . 5284 .Pp 5285 .It -l 5286 .It --ignore-white-space 5287 Let any sequence of blanks (spaces or tabs) in the patch file match any sequence 5288 of blanks in the input file.See Section 5289 .Dq Changed White Space . 5290 .Pp 5291 .It -n 5292 .It --normal 5293 Interpret the patch file as a normal diff.See Section 5294 .Dq patch Input . 5295 .Pp 5296 .It -N 5297 .It --forward 5298 Ignore patches that 5299 .Xr patch 5300 thinks are reversed or already applied. See also 5301 .Op -R . 5302 See Section.Dq Reversed Patches . 5303 .Pp 5304 .It --no-backup-if-mismatch 5305 Do not back up the original contents of files. This is the default behavior 5306 when conforming to POSIX.See Section 5307 .Dq Backups . 5308 .Pp 5309 .It -o Va file 5310 .It --output= Va file 5311 Use 5312 .Va file 5313 as the output file name.See Section 5314 .Dq patch Options . 5315 .Pp 5316 .It -p Va number 5317 .It --strip= Va number 5318 Set the file name strip count to 5319 .Va number . 5320 See Section.Dq patch Directories . 5321 .Pp 5322 .It --posix 5323 Conform to POSIX, as if the 5324 .Ev POSIXLY_CORRECT 5325 environment variable had been set.See Section 5326 .Dq patch and POSIX . 5327 .Pp 5328 .It --quoting-style= Va word 5329 Use style 5330 .Va word 5331 to quote names in diagnostics, as if the 5332 .Ev QUOTING_STYLE 5333 environment variable had been set to 5334 .Va word . 5335 See Section.Dq patch Quoting Style . 5336 .Pp 5337 .It -r Va reject-file 5338 .It --reject-file= Va reject-file 5339 Use 5340 .Va reject-file 5341 as the reject file name.See Section 5342 .Dq Reject Names . 5343 .Pp 5344 .It -R 5345 .It --reverse 5346 Assume that this patch was created with the old and new files swapped.See Section 5347 .Dq Reversed Patches . 5348 .Pp 5349 .It -s 5350 .It --quiet 5351 .It --silent 5352 Work silently unless an error occurs.See Section 5353 .Dq patch Messages . 5354 .Pp 5355 .It -t 5356 .It --batch 5357 Do not ask any questions.See Section 5358 .Dq patch Messages . 5359 .Pp 5360 .It -T 5361 .It --set-time 5362 Set the modification and access times of patched files from time stamps given 5363 in context diff headers, assuming that the context diff headers use local 5364 time.See Section 5365 .Dq Patching Time Stamps . 5366 .Pp 5367 .It -u 5368 .It --unified 5369 Interpret the patch file as a unified diff.See Section 5370 .Dq patch Input . 5371 .Pp 5372 .It -v 5373 .It --version 5374 Output version information and then exit. 5375 .Pp 5376 .It -V Va backup-style 5377 .It --version=control= Va backup-style 5378 Select the naming convention for backup file names.See Section 5379 .Dq Backup Names . 5380 .Pp 5381 .It --verbose 5382 Print more diagnostics than usual.See Section 5383 .Dq patch Messages . 5384 .Pp 5385 .It -x Va number 5386 .It --debug= Va number 5387 Set internal debugging flags. Of interest only to 5388 .Xr patch 5389 patchers. 5390 .Pp 5391 .It -Y Va prefix 5392 .It --basename-prefix= Va prefix 5393 Prepend 5394 .Va prefix 5395 to base names of backup files.See Section 5396 .Dq Backup Names . 5397 .Pp 5398 .It -z Va suffix 5399 .It --suffix= Va suffix 5400 Use 5401 .Va suffix 5402 as the backup extension instead of 5403 .Li .orig 5404 or 5405 .Li ~ . 5406 See Section.Dq Backup Names . 5407 .Pp 5408 .It -Z 5409 .It --set-utc 5410 Set the modification and access times of patched files from time stamps given 5411 in context diff headers, assuming that the context diff headers use UTC.See Section 5412 .Dq Patching Time Stamps . 5413 .Pp 5414 .El 5415 .Sh Invoking Xr sdiff 5416 The 5417 .Xr sdiff 5418 command merges two files and interactively outputs the results. Its arguments 5419 are as follows: 5420 .Pp 5421 .Bd -literal -offset indent 5422 sdiff -o outfile options... from-file to-file 5423 .Ed 5424 .Pp 5425 This merges 5426 .Va from-file 5427 with 5428 .Va to-file , 5429 with output to 5430 .Va outfile . 5431 If 5432 .Va from-file 5433 is a directory and 5434 .Va to-file 5435 is not, 5436 .Xr sdiff 5437 compares the file in 5438 .Va from-file 5439 whose file name is that of 5440 .Va to-file , 5441 and vice versa. 5442 .Va from-file 5443 and 5444 .Va to-file 5445 may not both be directories. 5446 .Pp 5447 .Xr sdiff 5448 options begin with 5449 .Li - , 5450 so normally 5451 .Va from-file 5452 and 5453 .Va to-file 5454 may not begin with 5455 .Li - . 5456 However, 5457 .Op -- 5458 as an argument by itself treats the remaining arguments as file names even 5459 if they begin with 5460 .Li - . 5461 You may not use 5462 .Pa - 5463 as an input file. 5464 .Pp 5465 .Xr sdiff 5466 without 5467 .Op -o 5468 (or 5469 .Op --output ) 5470 produces a side-by-side difference. This usage is obsolete; use the 5471 .Op -y 5472 or 5473 .Op --side-by-side 5474 option of 5475 .Xr diff 5476 instead. 5477 .Pp 5478 An exit status of 0 means no differences were found, 1 means some differences 5479 were found, and 2 means trouble. 5480 .Pp 5481 .Ss Options to Xr sdiff 5482 Below is a summary of all of the options that GNU 5483 .Xr sdiff 5484 accepts. Each option has two equivalent names, one of which is a single letter 5485 preceded by 5486 .Li - , 5487 and the other of which is a long name preceded by 5488 .Li -- . 5489 Multiple single letter options (unless they take an argument) can be combined 5490 into a single command line argument. Long named options can be abbreviated 5491 to any unique prefix of their name. 5492 .Pp 5493 .Bl -tag -width Ds 5494 .It -a 5495 .It --text 5496 Treat all files as text and compare them line-by-line, even if they do not 5497 appear to be text.See Section 5498 .Dq Binary . 5499 .Pp 5500 .It -b 5501 .It --ignore-space-change 5502 Ignore changes in amount of white space.See Section 5503 .Dq White Space . 5504 .Pp 5505 .It -B 5506 .It --ignore-blank-lines 5507 Ignore changes that just insert or delete blank lines.See Section 5508 .Dq Blank Lines . 5509 .Pp 5510 .It -d 5511 .It --minimal 5512 Change the algorithm to perhaps find a smaller set of changes. This makes 5513 .Xr sdiff 5514 slower (sometimes much slower).See Section 5515 .Dq diff Performance . 5516 .Pp 5517 .It --diff-program= Va program 5518 Use the compatible comparison program 5519 .Va program 5520 to compare files instead of 5521 .Xr diff . 5522 .Pp 5523 .It -E 5524 .It --ignore-tab-expansion 5525 Ignore changes due to tab expansion.See Section 5526 .Dq White Space . 5527 .Pp 5528 .It --help 5529 Output a summary of usage and then exit. 5530 .Pp 5531 .It -i 5532 .It --ignore-case 5533 Ignore changes in case; consider upper- and lower-case to be the same.See Section 5534 .Dq Case Folding . 5535 .Pp 5536 .It -I Va regexp 5537 .It --ignore-matching-lines= Va regexp 5538 Ignore changes that just insert or delete lines that match 5539 .Va regexp . 5540 See Section.Dq Specified Lines . 5541 .Pp 5542 .It -l 5543 .It --left-column 5544 Print only the left column of two common lines.See Section 5545 .Dq Side by Side Format . 5546 .Pp 5547 .It -o Va file 5548 .It --output= Va file 5549 Put merged output into 5550 .Va file . 5551 This option is required for merging. 5552 .Pp 5553 .It -s 5554 .It --suppress-common-lines 5555 Do not print common lines.See Section 5556 .Dq Side by Side Format . 5557 .Pp 5558 .It --speed-large-files 5559 Use heuristics to speed handling of large files that have numerous scattered 5560 small changes.See Section 5561 .Dq diff Performance . 5562 .Pp 5563 .It --strip-trailing-cr 5564 Strip any trailing carriage return at the end of an input line.See Section 5565 .Dq Binary . 5566 .Pp 5567 .It -t 5568 .It --expand-tabs 5569 Expand tabs to spaces in the output, to preserve the alignment of tabs in 5570 the input files.See Section 5571 .Dq Tabs . 5572 .Pp 5573 .It --tabsize= Va columns 5574 Assume that tab stops are set every 5575 .Va columns 5576 (default 8) print columns.See Section 5577 .Dq Tabs . 5578 .Pp 5579 .It -v 5580 .It --version 5581 Output version information and then exit. 5582 .Pp 5583 .It -w Va columns 5584 .It --width= Va columns 5585 Output at most 5586 .Va columns 5587 (default 130) print columns per line.See Section 5588 .Dq Side by Side Format . 5589 Note that for historical reasons, this option is 5590 .Op -W 5591 in 5592 .Xr diff , 5593 .Op -w 5594 in 5595 .Xr sdiff . 5596 .Pp 5597 .It -W 5598 .It --ignore-all-space 5599 Ignore white space when comparing lines.See Section 5600 .Dq White Space . 5601 Note that for historical reasons, this option is 5602 .Op -w 5603 in 5604 .Xr diff , 5605 .Op -W 5606 in 5607 .Xr sdiff . 5608 .El 5609 .Pp 5610 .Sh Standards conformance 5611 In a few cases, the GNU utilities' default behavior is incompatible with the 5612 POSIX standard. To suppress these incompatibilities, define the 5613 .Ev POSIXLY_CORRECT 5614 environment variable. Unless you are checking for POSIX conformance, you probably 5615 do not need to define 5616 .Ev POSIXLY_CORRECT . 5617 .Pp 5618 Normally options and operands can appear in any order, and programs act as 5619 if all the options appear before any operands. For example, 5620 .Li diff lao tzu -C 2 5621 acts like 5622 .Li diff -C 2 lao tzu , 5623 since 5624 .Li 2 5625 is an option-argument of 5626 .Op -C . 5627 However, if the 5628 .Ev POSIXLY_CORRECT 5629 environment variable is set, options must appear before operands, unless otherwise 5630 specified for a particular command. 5631 .Pp 5632 Newer versions of POSIX are occasionally incompatible with older versions. 5633 For example, older versions of POSIX allowed the command 5634 .Li diff -c -10 5635 to have the same meaning as 5636 .Li diff -C 10 , 5637 but POSIX 1003.1-2001 5638 .Li diff 5639 no longer allows digit-string options like 5640 .Op -10 . 5641 .Pp 5642 The GNU utilities normally conform to the version of POSIX that is standard 5643 for your system. To cause them to conform to a different version of POSIX, 5644 define the 5645 .Ev _POSIX2_VERSION 5646 environment variable to a value of the form 5647 .Va yyyymm 5648 specifying the year and month the standard was adopted. Two values are currently 5649 supported for 5650 .Ev _POSIX2_VERSION : 5651 .Li 199209 5652 stands for POSIX 1003.2-1992, and 5653 .Li 200112 5654 stands for POSIX 1003.1-2001. For example, if you are running older software 5655 that assumes an older version of POSIX and uses 5656 .Li diff -c -10 , 5657 you can work around the compatibility problems by setting 5658 .Li _POSIX2_VERSION=199209 5659 in your environment. 5660 .Pp 5661 .Sh Future Projects 5662 Here are some ideas for improving GNU 5663 .Xr diff 5664 and 5665 .Xr patch . 5666 The GNU project has identified some improvements as potential programming 5667 projects for volunteers. You can also help by reporting any bugs that you 5668 find. 5669 .Pp 5670 If you are a programmer and would like to contribute something to the GNU 5671 project, please consider volunteering for one of these projects. If you are 5672 seriously contemplating work, please write to 5673 .Mt gvc@gnu.org 5674 to coordinate with other volunteers. 5675 .Pp 5676 .Ss Suggested Projects for Improving GNU Xr diff and Xr patch 5677 One should be able to use GNU 5678 .Xr diff 5679 to generate a patch from any pair of directory trees, and given the patch 5680 and a copy of one such tree, use 5681 .Xr patch 5682 to generate a faithful copy of the other. Unfortunately, some changes to directory 5683 trees cannot be expressed using current patch formats; also, 5684 .Xr patch 5685 does not handle some of the existing formats. These shortcomings motivate 5686 the following suggested projects. 5687 .Pp 5688 .Em Handling Multibyte and Varying-Width Characters 5689 .Pp 5690 .Xr diff , 5691 .Xr diff3 5692 and 5693 .Xr sdiff 5694 treat each line of input as a string of unibyte characters. This can mishandle 5695 multibyte characters in some cases. For example, when asked to ignore spaces, 5696 .Xr diff 5697 does not properly ignore a multibyte space character. 5698 .Pp 5699 Also, 5700 .Xr diff 5701 currently assumes that each byte is one column wide, and this assumption is 5702 incorrect in some locales, e.g., locales that use UTF-8 encoding. This causes 5703 problems with the 5704 .Op -y 5705 or 5706 .Op --side-by-side 5707 option of 5708 .Xr diff . 5709 .Pp 5710 These problems need to be fixed without unduly affecting the performance of 5711 the utilities in unibyte environments. 5712 .Pp 5713 The IBM GNU/Linux Technology Center Internationalization Team has proposed 5714 .Lk http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz . 5715 Unfortunately, these patches are incomplete and are to an older version of 5716 .Xr diff , 5717 so more work needs to be done in this area. 5718 .Pp 5719 .Em Handling Changes to the Directory Structure 5720 .Pp 5721 .Xr diff 5722 and 5723 .Xr patch 5724 do not handle some changes to directory structure. For example, suppose one 5725 directory tree contains a directory named 5726 .Li D 5727 with some subsidiary files, and another contains a file with the same name 5728 .Li D . 5729 .Li diff -r 5730 does not output enough information for 5731 .Xr patch 5732 to transform the directory subtree into the file. 5733 .Pp 5734 There should be a way to specify that a file has been removed without having 5735 to include its entire contents in the patch file. There should also be a way 5736 to tell 5737 .Xr patch 5738 that a file was renamed, even if there is no way for 5739 .Xr diff 5740 to generate such information. There should be a way to tell 5741 .Xr patch 5742 that a file's time stamp has changed, even if its contents have not changed. 5743 .Pp 5744 These problems can be fixed by extending the 5745 .Xr diff 5746 output format to represent changes in directory structure, and extending 5747 .Xr patch 5748 to understand these extensions. 5749 .Pp 5750 .Em Files that are Neither Directories Nor Regular Files 5751 .Pp 5752 Some files are neither directories nor regular files: they are unusual files 5753 like symbolic links, device special files, named pipes, and sockets. Currently, 5754 .Xr diff 5755 treats symbolic links as if they were the pointed-to files, except that a 5756 recursive 5757 .Xr diff 5758 reports an error if it detects infinite loops of symbolic links (e.g., symbolic 5759 links to 5760 .Pa .. ) . 5761 .Xr diff 5762 treats other special files like regular files if they are specified at the 5763 top level, but simply reports their presence when comparing directories. This 5764 means that 5765 .Xr patch 5766 cannot represent changes to such files. For example, if you change which file 5767 a symbolic link points to, 5768 .Xr diff 5769 outputs the difference between the two files, instead of the change to the 5770 symbolic link. 5771 .Pp 5772 .Xr diff 5773 should optionally report changes to special files specially, and 5774 .Xr patch 5775 should be extended to understand these extensions. 5776 .Pp 5777 .Em File Names that Contain Unusual Characters 5778 .Pp 5779 When a file name contains an unusual character like a newline or white space, 5780 .Li diff -r 5781 generates a patch that 5782 .Xr patch 5783 cannot parse. The problem is with format of 5784 .Xr diff 5785 output, not just with 5786 .Xr patch , 5787 because with odd enough file names one can cause 5788 .Xr diff 5789 to generate a patch that is syntactically correct but patches the wrong files. 5790 The format of 5791 .Xr diff 5792 output should be extended to handle all possible file names. 5793 .Pp 5794 .Em Outputting Diffs in Time Stamp Order 5795 .Pp 5796 Applying 5797 .Xr patch 5798 to a multiple-file diff can result in files whose time stamps are out of order. 5799 GNU 5800 .Xr patch 5801 has options to restore the time stamps of the updated files (see Section 5802 .Dq Patching Time Stamps ) , 5803 but sometimes it is useful to generate a patch that works even if the recipient 5804 does not have GNU patch, or does not use these options. One way to do this 5805 would be to implement a 5806 .Xr diff 5807 option to output diffs in time stamp order. 5808 .Pp 5809 .Em Ignoring Certain Changes 5810 .Pp 5811 It would be nice to have a feature for specifying two strings, one in 5812 .Va from-file 5813 and one in 5814 .Va to-file , 5815 which should be considered to match. Thus, if the two strings are 5816 .Li foo 5817 and 5818 .Li bar , 5819 then if two lines differ only in that 5820 .Li foo 5821 in file 1 corresponds to 5822 .Li bar 5823 in file 2, the lines are treated as identical. 5824 .Pp 5825 It is not clear how general this feature can or should be, or what syntax 5826 should be used for it. 5827 .Pp 5828 A partial substitute is to filter one or both files before comparing, e.g.: 5829 .Pp 5830 .Bd -literal -offset indent 5831 sed 's/foo/bar/g' file1 | diff - file2 5832 .Ed 5833 .Pp 5834 However, this outputs the filtered text, not the original. 5835 .Pp 5836 .Em Improving Performance 5837 .Pp 5838 When comparing two large directory structures, one of which was originally 5839 copied from the other with time stamps preserved (e.g., with 5840 .Li cp -pR ) , 5841 it would greatly improve performance if an option told 5842 .Xr diff 5843 to assume that two files with the same size and time stamps have the same 5844 content.See Section 5845 .Dq diff Performance . 5846 .Pp 5847 .Ss Reporting Bugs 5848 If you think you have found a bug in GNU 5849 .Xr cmp , 5850 .Xr diff , 5851 .Xr diff3 , 5852 or 5853 .Xr sdiff , 5854 please report it by electronic mail to the 5855 .Lk http://mail.gnu.org/mailman/listinfo/bug-gnu-utils 5856 .Mt bug-gnu-utils@gnu.org . 5857 Please send bug reports for GNU 5858 .Xr patch 5859 to 5860 .Mt bug-patch@gnu.org . 5861 Send as precise a description of the problem as you can, including the output 5862 of the 5863 .Op --version 5864 option and sample input files that produce the bug, if applicable. If you 5865 have a nontrivial fix for the bug, please send it as well. If you have a patch, 5866 please send it too. It may simplify the maintainer's job if the patch is relative 5867 to a recent test release, which you can find in the directory 5868 .Lk ftp://alpha.gnu.org/gnu/diffutils/ . 5869 .Pp 5870 .Sh Copying This Manual 5871 .Ss GNU Free Documentation License 5872 .Bd -filled -offset indent 5873 Copyright \(co 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, 5874 Suite 330, Boston, MA 02111-1307, USA 5875 .Pp 5876 Everyone is permitted to copy and distribute verbatim copies of this license 5877 document, but changing it is not allowed. 5878 .Ed 5879 .Pp 5880 .Bl -enum 5881 .It 5882 PREAMBLE 5883 .Pp 5884 The purpose of this License is to make a manual, textbook, or other functional 5885 and useful document 5886 .Em free 5887 in the sense of freedom: to assure everyone the effective freedom to copy 5888 and redistribute it, with or without modifying it, either commercially or 5889 noncommercially. Secondarily, this License preserves for the author and publisher 5890 a way to get credit for their work, while not being considered responsible 5891 for modifications made by others. 5892 .Pp 5893 This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the 5894 document must themselves be free in the same sense. It complements the GNU 5895 General Public License, which is a copyleft license designed for free software. 5896 .Pp 5897 We have designed this License in order to use it for manuals for free software, 5898 because free software needs free documentation: a free program should come 5899 with manuals providing the same freedoms that the software does. But this 5900 License is not limited to software manuals; it can be used for any textual 5901 work, regardless of subject matter or whether it is published as a printed 5902 book. We recommend this License principally for works whose purpose is instruction 5903 or reference. 5904 .Pp 5905 .It 5906 APPLICABILITY AND DEFINITIONS 5907 .Pp 5908 This License applies to any manual or other work, in any medium, that contains 5909 a notice placed by the copyright holder saying it can be distributed under 5910 the terms of this License. Such a notice grants a world-wide, royalty-free 5911 license, unlimited in duration, to use that work under the conditions stated 5912 herein. The \(lqDocument\(rq, below, refers to any such manual or work. Any member 5913 of the public is a licensee, and is addressed as \(lqyou\(rq. You accept the license 5914 if you copy, modify or distribute the work in a way requiring permission under 5915 copyright law. 5916 .Pp 5917 A \(lqModified Version\(rq of the Document means any work containing the Document 5918 or a portion of it, either copied verbatim, or with modifications and/or translated 5919 into another language. 5920 .Pp 5921 A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document 5922 that deals exclusively with the relationship of the publishers or authors 5923 of the Document to the Document's overall subject (or to related matters) 5924 and contains nothing that could fall directly within that overall subject. 5925 (Thus, if the Document is in part a textbook of mathematics, a Secondary Section 5926 may not explain any mathematics.) The relationship could be a matter of historical 5927 connection with the subject or with related matters, or of legal, commercial, 5928 philosophical, ethical or political position regarding them. 5929 .Pp 5930 The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, 5931 as being those of Invariant Sections, in the notice that says that the Document 5932 is released under this License. If a section does not fit the above definition 5933 of Secondary then it is not allowed to be designated as Invariant. The Document 5934 may contain zero Invariant Sections. If the Document does not identify any 5935 Invariant Sections then there are none. 5936 .Pp 5937 The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover 5938 Texts or Back-Cover Texts, in the notice that says that the Document is released 5939 under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover 5940 Text may be at most 25 words. 5941 .Pp 5942 A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented 5943 in a format whose specification is available to the general public, that is 5944 suitable for revising the document straightforwardly with generic text editors 5945 or (for images composed of pixels) generic paint programs or (for drawings) 5946 some widely available drawing editor, and that is suitable for input to text 5947 formatters or for automatic translation to a variety of formats suitable for 5948 input to text formatters. A copy made in an otherwise Transparent file format 5949 whose markup, or absence of markup, has been arranged to thwart or discourage 5950 subsequent modification by readers is not Transparent. An image format is 5951 not Transparent if used for any substantial amount of text. A copy that is 5952 not \(lqTransparent\(rq is called \(lqOpaque\(rq. 5953 .Pp 5954 Examples of suitable formats for Transparent copies include plain ascii without 5955 markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly 5956 available DTD, and standard-conforming simple HTML, PostScript or PDF designed 5957 for human modification. Examples of transparent image formats include PNG, 5958 XCF and JPG. Opaque formats include proprietary formats that can be read and 5959 edited only by proprietary word processors, SGML or XML for which the DTD 5960 and/or processing tools are not generally available, and the machine-generated 5961 HTML, PostScript or PDF produced by some word processors for output purposes 5962 only. 5963 .Pp 5964 The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such 5965 following pages as are needed to hold, legibly, the material this License 5966 requires to appear in the title page. For works in formats which do not have 5967 any title page as such, \(lqTitle Page\(rq means the text near the most prominent 5968 appearance of the work's title, preceding the beginning of the body of the 5969 text. 5970 .Pp 5971 A section \(lqEntitled XYZ\(rq means a named subunit of the Document whose title either 5972 is precisely XYZ or contains XYZ in parentheses following text that translates 5973 XYZ in another language. (Here XYZ stands for a specific section name mentioned 5974 below, such as \(lqAcknowledgements\(rq, \(lqDedications\(rq, \(lqEndorsements\(rq, or \(lqHistory\(rq.) To 5975 \(lqPreserve the Title\(rq of such a section when you modify the Document means that 5976 it remains a section \(lqEntitled XYZ\(rq according to this definition. 5977 .Pp 5978 The Document may include Warranty Disclaimers next to the notice which states 5979 that this License applies to the Document. These Warranty Disclaimers are 5980 considered to be included by reference in this License, but only as regards 5981 disclaiming warranties: any other implication that these Warranty Disclaimers 5982 may have is void and has no effect on the meaning of this License. 5983 .Pp 5984 .It 5985 VERBATIM COPYING 5986 .Pp 5987 You may copy and distribute the Document in any medium, either commercially 5988 or noncommercially, provided that this License, the copyright notices, and 5989 the license notice saying this License applies to the Document are reproduced 5990 in all copies, and that you add no other conditions whatsoever to those of 5991 this License. You may not use technical measures to obstruct or control the 5992 reading or further copying of the copies you make or distribute. However, 5993 you may accept compensation in exchange for copies. If you distribute a large 5994 enough number of copies you must also follow the conditions in section 3. 5995 .Pp 5996 You may also lend copies, under the same conditions stated above, and you 5997 may publicly display copies. 5998 .Pp 5999 .It 6000 COPYING IN QUANTITY 6001 .Pp 6002 If you publish printed copies (or copies in media that commonly have printed 6003 covers) of the Document, numbering more than 100, and the Document's license 6004 notice requires Cover Texts, you must enclose the copies in covers that carry, 6005 clearly and legibly, all these Cover Texts: Front-Cover Texts on the front 6006 cover, and Back-Cover Texts on the back cover. Both covers must also clearly 6007 and legibly identify you as the publisher of these copies. The front cover 6008 must present the full title with all words of the title equally prominent 6009 and visible. You may add other material on the covers in addition. Copying 6010 with changes limited to the covers, as long as they preserve the title of 6011 the Document and satisfy these conditions, can be treated as verbatim copying 6012 in other respects. 6013 .Pp 6014 If the required texts for either cover are too voluminous to fit legibly, 6015 you should put the first ones listed (as many as fit reasonably) on the actual 6016 cover, and continue the rest onto adjacent pages. 6017 .Pp 6018 If you publish or distribute Opaque copies of the Document numbering more 6019 than 100, you must either include a machine-readable Transparent copy along 6020 with each Opaque copy, or state in or with each Opaque copy a computer-network 6021 location from which the general network-using public has access to download 6022 using public-standard network protocols a complete Transparent copy of the 6023 Document, free of added material. If you use the latter option, you must take 6024 reasonably prudent steps, when you begin distribution of Opaque copies in 6025 quantity, to ensure that this Transparent copy will remain thus accessible 6026 at the stated location until at least one year after the last time you distribute 6027 an Opaque copy (directly or through your agents or retailers) of that edition 6028 to the public. 6029 .Pp 6030 It is requested, but not required, that you contact the authors of the Document 6031 well before redistributing any large number of copies, to give them a chance 6032 to provide you with an updated version of the Document. 6033 .Pp 6034 .It 6035 MODIFICATIONS 6036 .Pp 6037 You may copy and distribute a Modified Version of the Document under the conditions 6038 of sections 2 and 3 above, provided that you release the Modified Version 6039 under precisely this License, with the Modified Version filling the role of 6040 the Document, thus licensing distribution and modification of the Modified 6041 Version to whoever possesses a copy of it. In addition, you must do these 6042 things in the Modified Version: 6043 .Pp 6044 .Bl -enum 6045 .It 6046 Use in the Title Page (and on the covers, if any) a title distinct from that 6047 of the Document, and from those of previous versions (which should, if there 6048 were any, be listed in the History section of the Document). You may use the 6049 same title as a previous version if the original publisher of that version 6050 gives permission. 6051 .Pp 6052 .It 6053 List on the Title Page, as authors, one or more persons or entities responsible 6054 for authorship of the modifications in the Modified Version, together with 6055 at least five of the principal authors of the Document (all of its principal 6056 authors, if it has fewer than five), unless they release you from this requirement. 6057 .Pp 6058 .It 6059 State on the Title page the name of the publisher of the Modified Version, 6060 as the publisher. 6061 .Pp 6062 .It 6063 Preserve all the copyright notices of the Document. 6064 .Pp 6065 .It 6066 Add an appropriate copyright notice for your modifications adjacent to the 6067 other copyright notices. 6068 .Pp 6069 .It 6070 Include, immediately after the copyright notices, a license notice giving 6071 the public permission to use the Modified Version under the terms of this 6072 License, in the form shown in the Addendum below. 6073 .Pp 6074 .It 6075 Preserve in that license notice the full lists of Invariant Sections and required 6076 Cover Texts given in the Document's license notice. 6077 .Pp 6078 .It 6079 Include an unaltered copy of this License. 6080 .Pp 6081 .It 6082 Preserve the section Entitled \(lqHistory\(rq, Preserve its Title, and add to it an 6083 item stating at least the title, year, new authors, and publisher of the Modified 6084 Version as given on the Title Page. If there is no section Entitled \(lqHistory\(rq 6085 in the Document, create one stating the title, year, authors, and publisher 6086 of the Document as given on its Title Page, then add an item describing the 6087 Modified Version as stated in the previous sentence. 6088 .Pp 6089 .It 6090 Preserve the network location, if any, given in the Document for public access 6091 to a Transparent copy of the Document, and likewise the network locations 6092 given in the Document for previous versions it was based on. These may be 6093 placed in the \(lqHistory\(rq section. You may omit a network location for a work 6094 that was published at least four years before the Document itself, or if the 6095 original publisher of the version it refers to gives permission. 6096 .Pp 6097 .It 6098 For any section Entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, Preserve the Title 6099 of the section, and preserve in the section all the substance and tone of 6100 each of the contributor acknowledgements and/or dedications given therein. 6101 .Pp 6102 .It 6103 Preserve all the Invariant Sections of the Document, unaltered in their text 6104 and in their titles. Section numbers or the equivalent are not considered 6105 part of the section titles. 6106 .Pp 6107 .It 6108 Delete any section Entitled \(lqEndorsements\(rq. Such a section may not be included 6109 in the Modified Version. 6110 .Pp 6111 .It 6112 Do not retitle any existing section to be Entitled \(lqEndorsements\(rq or to conflict 6113 in title with any Invariant Section. 6114 .Pp 6115 .It 6116 Preserve any Warranty Disclaimers. 6117 .El 6118 .Pp 6119 If the Modified Version includes new front-matter sections or appendices that 6120 qualify as Secondary Sections and contain no material copied from the Document, 6121 you may at your option designate some or all of these sections as invariant. 6122 To do this, add their titles to the list of Invariant Sections in the Modified 6123 Version's license notice. These titles must be distinct from any other section 6124 titles. 6125 .Pp 6126 You may add a section Entitled \(lqEndorsements\(rq, provided it contains nothing 6127 but endorsements of your Modified Version by various parties---for example, 6128 statements of peer review or that the text has been approved by an organization 6129 as the authoritative definition of a standard. 6130 .Pp 6131 You may add a passage of up to five words as a Front-Cover Text, and a passage 6132 of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts 6133 in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover 6134 Text may be added by (or through arrangements made by) any one entity. If 6135 the Document already includes a cover text for the same cover, previously 6136 added by you or by arrangement made by the same entity you are acting on behalf 6137 of, you may not add another; but you may replace the old one, on explicit 6138 permission from the previous publisher that added the old one. 6139 .Pp 6140 The author(s) and publisher(s) of the Document do not by this License give 6141 permission to use their names for publicity for or to assert or imply endorsement 6142 of any Modified Version. 6143 .Pp 6144 .It 6145 COMBINING DOCUMENTS 6146 .Pp 6147 You may combine the Document with other documents released under this License, 6148 under the terms defined in section 4 above for modified versions, provided 6149 that you include in the combination all of the Invariant Sections of all of 6150 the original documents, unmodified, and list them all as Invariant Sections 6151 of your combined work in its license notice, and that you preserve all their 6152 Warranty Disclaimers. 6153 .Pp 6154 The combined work need only contain one copy of this License, and multiple 6155 identical Invariant Sections may be replaced with a single copy. If there 6156 are multiple Invariant Sections with the same name but different contents, 6157 make the title of each such section unique by adding at the end of it, in 6158 parentheses, the name of the original author or publisher of that section 6159 if known, or else a unique number. Make the same adjustment to the section 6160 titles in the list of Invariant Sections in the license notice of the combined 6161 work. 6162 .Pp 6163 In the combination, you must combine any sections Entitled \(lqHistory\(rq in the 6164 various original documents, forming one section Entitled \(lqHistory\(rq; likewise 6165 combine any sections Entitled \(lqAcknowledgements\(rq, and any sections Entitled 6166 \(lqDedications\(rq. You must delete all sections Entitled \(lqEndorsements.\(rq 6167 .Pp 6168 .It 6169 COLLECTIONS OF DOCUMENTS 6170 .Pp 6171 You may make a collection consisting of the Document and other documents released 6172 under this License, and replace the individual copies of this License in the 6173 various documents with a single copy that is included in the collection, provided 6174 that you follow the rules of this License for verbatim copying of each of 6175 the documents in all other respects. 6176 .Pp 6177 You may extract a single document from such a collection, and distribute it 6178 individually under this License, provided you insert a copy of this License 6179 into the extracted document, and follow this License in all other respects 6180 regarding verbatim copying of that document. 6181 .Pp 6182 .It 6183 AGGREGATION WITH INDEPENDENT WORKS 6184 .Pp 6185 A compilation of the Document or its derivatives with other separate and independent 6186 documents or works, in or on a volume of a storage or distribution medium, 6187 is called an \(lqaggregate\(rq if the copyright resulting from the compilation is 6188 not used to limit the legal rights of the compilation's users beyond what 6189 the individual works permit. When the Document is included in an aggregate, 6190 this License does not apply to the other works in the aggregate which are 6191 not themselves derivative works of the Document. 6192 .Pp 6193 If the Cover Text requirement of section 3 is applicable to these copies of 6194 the Document, then if the Document is less than one half of the entire aggregate, 6195 the Document's Cover Texts may be placed on covers that bracket the Document 6196 within the aggregate, or the electronic equivalent of covers if the Document 6197 is in electronic form. Otherwise they must appear on printed covers that bracket 6198 the whole aggregate. 6199 .Pp 6200 .It 6201 TRANSLATION 6202 .Pp 6203 Translation is considered a kind of modification, so you may distribute translations 6204 of the Document under the terms of section 4. Replacing Invariant Sections 6205 with translations requires special permission from their copyright holders, 6206 but you may include translations of some or all Invariant Sections in addition 6207 to the original versions of these Invariant Sections. You may include a translation 6208 of this License, and all the license notices in the Document, and any Warranty 6209 Disclaimers, provided that you also include the original English version of 6210 this License and the original versions of those notices and disclaimers. In 6211 case of a disagreement between the translation and the original version of 6212 this License or a notice or disclaimer, the original version will prevail. 6213 .Pp 6214 If a section in the Document is Entitled \(lqAcknowledgements\(rq, \(lqDedications\(rq, or 6215 \(lqHistory\(rq, the requirement (section 4) to Preserve its Title (section 1) will 6216 typically require changing the actual title. 6217 .Pp 6218 .It 6219 TERMINATION 6220 .Pp 6221 You may not copy, modify, sublicense, or distribute the Document except as 6222 expressly provided for under this License. Any other attempt to copy, modify, 6223 sublicense or distribute the Document is void, and will automatically terminate 6224 your rights under this License. However, parties who have received copies, 6225 or rights, from you under this License will not have their licenses terminated 6226 so long as such parties remain in full compliance. 6227 .Pp 6228 .It 6229 FUTURE REVISIONS OF THIS LICENSE 6230 .Pp 6231 The Free Software Foundation may publish new, revised versions of the GNU 6232 Free Documentation License from time to time. Such new versions will be similar 6233 in spirit to the present version, but may differ in detail to address new 6234 problems or concerns. See 6235 .Lk http://www.gnu.org/copyleft/ . 6236 .Pp 6237 Each version of the License is given a distinguishing version number. If the 6238 Document specifies that a particular numbered version of this License \(lqor any 6239 later version\(rq applies to it, you have the option of following the terms and 6240 conditions either of that specified version or of any later version that has 6241 been published (not as a draft) by the Free Software Foundation. If the Document 6242 does not specify a version number of this License, you may choose any version 6243 ever published (not as a draft) by the Free Software Foundation. 6244 .El 6245 .Pp 6246 .Em ADDENDUM: How to use this License for your documents 6247 .Pp 6248 To use this License in a document you have written, include a copy of the 6249 License in the document and put the following copyright and license notices 6250 just after the title page: 6251 .Pp 6252 .Bd -literal -offset indent 6253 6254 Copyright (C) year your name. 6255 Permission is granted to copy, distribute and/or modify this document 6256 under the terms of the GNU Free Documentation License, Version 1.2 6257 or any later version published by the Free Software Foundation; 6258 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 6259 Texts. A copy of the license is included in the section entitled \(lqGNU 6260 Free Documentation License\(rq. 6261 6262 .Ed 6263 .Pp 6264 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace 6265 the \(lqwith...Texts.\(rq line with this: 6266 .Pp 6267 .Bd -literal -offset indent 6268 6269 with the Invariant Sections being list their titles, with 6270 the Front-Cover Texts being list, and with the Back-Cover Texts 6271 being list. 6272 6273 .Ed 6274 .Pp 6275 If you have Invariant Sections without Cover Texts, or some other combination 6276 of the three, merge those two alternatives to suit the situation. 6277 .Pp 6278 If your document contains nontrivial examples of program code, we recommend 6279 releasing these examples in parallel under your choice of free software license, 6280 such as the GNU General Public License, to permit their use in free software. 6281 .Pp 6282 .Sh Translations of This Manual 6283 Nishio Futoshi of the GNUjdoc project has prepared a Japanese translation 6284 of this manual. Its most recent version can be found at 6285 .Lk http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/ . 6286 .Pp 6287 .Sh Index 6288