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