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