1This is Info file diff.info, produced by Makeinfo-1.55 from the input 2file ./diff.texi. 3 4 This file documents the the GNU `diff', `diff3', `sdiff', and `cmp' 5commands for showing the differences between text files and the `patch' 6command for using their output to update files. 7 8 Copyright (C) 1992, 1993 Free Software Foundation, Inc. 9 10 Permission is granted to make and distribute verbatim copies of this 11manual provided the copyright notice and this permission notice are 12preserved on all copies. 13 14 Permission is granted to copy and distribute modified versions of 15this manual under the conditions for verbatim copying, provided that 16the entire resulting derived work is distributed under the terms of a 17permission notice identical to this one. 18 19 Permission is granted to copy and distribute translations of this 20manual into another language, under the above conditions for modified 21versions, except that this permission notice may be stated in a 22translation approved by the Foundation. 23 24 25File: diff.info, Node: Line Group Formats, Next: Line Formats, Up: If-then-else 26 27Line Group Formats 28------------------ 29 30 Line group formats let you specify formats suitable for many 31applications that allow if-then-else input, including programming 32languages and text formatting languages. A line group format specifies 33the output format for a contiguous group of similar lines. 34 35 For example, the following command compares the TeX files `old' and 36`new', and outputs a merged file in which old regions are surrounded by 37`\begin{em}'-`\end{em}' lines, and new regions are surrounded by 38`\begin{bf}'-`\end{bf}' lines. 39 40 diff \ 41 --old-group-format='\begin{em} 42 %<\end{em} 43 ' \ 44 --new-group-format='\begin{bf} 45 %>\end{bf} 46 ' \ 47 old new 48 49 The following command is equivalent to the above example, but it is a 50little more verbose, because it spells out the default line group 51formats. 52 53 diff \ 54 --old-group-format='\begin{em} 55 %<\end{em} 56 ' \ 57 --new-group-format='\begin{bf} 58 %>\end{bf} 59 ' \ 60 --unchanged-group-format='%=' \ 61 --changed-group-format='\begin{em} 62 %<\end{em} 63 \begin{bf} 64 %>\end{bf} 65 ' \ 66 old new 67 68 Here is a more advanced example, which outputs a diff listing with 69headers containing line numbers in a "plain English" style. 70 71 diff \ 72 --unchanged-group-format='' \ 73 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 74 %<' \ 75 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 76 %>' \ 77 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 78 %<-------- to: 79 %>' \ 80 old new 81 82 To specify a line group format, use `diff' with one of the options 83listed below. You can specify up to four line group formats, one for 84each kind of line group. You should quote FORMAT, because it typically 85contains shell metacharacters. 86 87`--old-group-format=FORMAT' 88 These line groups are hunks containing only lines from the first 89 file. The default old group format is the same as the changed 90 group format if it is specified; otherwise it is a format that 91 outputs the line group as-is. 92 93`--new-group-format=FORMAT' 94 These line groups are hunks containing only lines from the second 95 file. The default new group format is same as the the changed 96 group format if it is specified; otherwise it is a format that 97 outputs the line group as-is. 98 99`--changed-group-format=FORMAT' 100 These line groups are hunks containing lines from both files. The 101 default changed group format is the concatenation of the old and 102 new group formats. 103 104`--unchanged-group-format=FORMAT' 105 These line groups contain lines common to both files. The default 106 unchanged group format is a format that outputs the line group 107 as-is. 108 109 In a line group format, ordinary characters represent themselves; 110conversion specifications start with `%' and have one of the following 111forms. 112 113`%<' 114 stands for the lines from the first file, including the trailing 115 newline. Each line is formatted according to the old line format 116 (*note Line Formats::.). 117 118`%>' 119 stands for the lines from the second file, including the trailing 120 newline. Each line is formatted according to the new line format. 121 122`%=' 123 stands for the lines common to both files, including the trailing 124 newline. Each line is formatted according to the unchanged line 125 format. 126 127`%%' 128 stands for `%'. 129 130`%c'C'' 131 where C is a single character, stands for C. C may not be a 132 backslash or an apostrophe. For example, `%c':'' stands for a 133 colon, even inside the then-part of an if-then-else format, which 134 a colon would normally terminate. 135 136`%c'\O'' 137 where O is a string of 1, 2, or 3 octal digits, stands for the 138 character with octal code O. For example, `%c'\0'' stands for a 139 null character. 140 141`FN' 142 where F is a `printf' conversion specification and N is one of the 143 following letters, stands for N's value formatted with F. 144 145 `e' 146 The line number of the line just before the group in the old 147 file. 148 149 `f' 150 The line number of the first line in the group in the old 151 file; equals E + 1. 152 153 `l' 154 The line number of the last line in the group in the old file. 155 156 `m' 157 The line number of the line just after the group in the old 158 file; equals L + 1. 159 160 `n' 161 The number of lines in the group in the old file; equals L - 162 F + 1. 163 164 `E, F, L, M, N' 165 Likewise, for lines in the new file. 166 167 The `printf' conversion specification can be `%d', `%o', `%x', or 168 `%X', specifying decimal, octal, lower case hexadecimal, or upper 169 case hexadecimal output respectively. After the `%' the following 170 options can appear in sequence: a `-' specifying 171 left-justification; an integer specifying the minimum field width; 172 and a period followed by an optional integer specifying the 173 minimum number of digits. For example, `%5dN' prints the number 174 of new lines in the group in a field of width 5 characters, using 175 the `printf' format `"%5d"'. 176 177`(A=B?T:E)' 178 If A equals B then T else E. A and B are each either a decimal 179 constant or a single letter interpreted as above. This format 180 spec is equivalent to T if A's value equals B's; otherwise it is 181 equivalent to E. 182 183 For example, `%(N=0?no:%dN) line%(N=1?:s)' is equivalent to `no 184 lines' if N (the number of lines in the group in the the new file) 185 is 0, to `1 line' if N is 1, and to `%dN lines' otherwise. 186 187 188File: diff.info, Node: Line Formats, Next: Detailed If-then-else, Prev: Line Group Formats, Up: If-then-else 189 190Line Formats 191------------ 192 193 Line formats control how each line taken from an input file is 194output as part of a line group in if-then-else format. 195 196 For example, the following command outputs text with a one-column 197change indicator to the left of the text. The first column of output 198is `-' for deleted lines, `|' for added lines, and a space for 199unchanged lines. The formats contain newline characters where newlines 200are desired on output. 201 202 diff \ 203 --old-line-format='-%l 204 ' \ 205 --new-line-format='|%l 206 ' \ 207 --unchanged-line-format=' %l 208 ' \ 209 old new 210 211 To specify a line format, use one of the following options. You 212should quote FORMAT, since it often contains shell metacharacters. 213 214`--old-line-format=FORMAT' 215 formats lines just from the first file. 216 217`--new-line-format=FORMAT' 218 formats lines just from the second file. 219 220`--unchanged-line-format=FORMAT' 221 formats lines common to both files. 222 223`--line-format=FORMAT' 224 formats all lines; in effect, it sets all three above options 225 simultaneously. 226 227 In a line format, ordinary characters represent themselves; 228conversion specifications start with `%' and have one of the following 229forms. 230 231`%l' 232 stands for the the contents of the line, not counting its trailing 233 newline (if any). This format ignores whether the line is 234 incomplete; *Note Incomplete Lines::. 235 236`%L' 237 stands for the the contents of the line, including its trailing 238 newline (if any). If a line is incomplete, this format preserves 239 its incompleteness. 240 241`%%' 242 stands for `%'. 243 244`%c'C'' 245 where C is a single character, stands for C. C may not be a 246 backslash or an apostrophe. For example, `%c':'' stands for a 247 colon. 248 249`%c'\O'' 250 where O is a string of 1, 2, or 3 octal digits, stands for the 251 character with octal code O. For example, `%c'\0'' stands for a 252 null character. 253 254`Fn' 255 where F is a `printf' conversion specification, stands for the 256 line number formatted with F. For example, `%.5dn' prints the 257 line number using the `printf' format `"%.5d"'. *Note Line Group 258 Formats::, for more about printf conversion specifications. 259 260 The default line format is `%l' followed by a newline character. 261 262 If the input contains tab characters and it is important that they 263line up on output, you should ensure that `%l' or `%L' in a line format 264is just after a tab stop (e.g. by preceding `%l' or `%L' with a tab 265character), or you should use the `-t' or `--expand-tabs' option. 266 267 Taken together, the line and line group formats let you specify many 268different formats. For example, the following command uses a format 269similar to `diff''s normal format. You can tailor this command to get 270fine control over `diff''s output. 271 272 diff \ 273 --old-line-format='< %l 274 ' \ 275 --new-line-format='> %l 276 ' \ 277 --old-group-format='%df%(f=l?:,%dl)d%dE 278 %<' \ 279 --new-group-format='%dea%dF%(F=L?:,%dL) 280 %>' \ 281 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 282 %<--- 283 %>' \ 284 --unchanged-group-format='' \ 285 old new 286 287 288File: diff.info, Node: Detailed If-then-else, Next: Example If-then-else, Prev: Line Formats, Up: If-then-else 289 290Detailed Description of If-then-else Format 291------------------------------------------- 292 293 For lines common to both files, `diff' uses the unchanged line group 294format. For each hunk of differences in the merged output format, if 295the hunk contains only lines from the first file, `diff' uses the old 296line group format; if the hunk contains only lines from the second 297file, `diff' uses the new group format; otherwise, `diff' uses the 298changed group format. 299 300 The old, new, and unchanged line formats specify the output format of 301lines from the first file, lines from the second file, and lines common 302to both files, respectively. 303 304 The option `--ifdef=NAME' is equivalent to the following sequence of 305options using shell syntax: 306 307 --old-group-format='#ifndef NAME 308 %<#endif /* not NAME */ 309 ' \ 310 --new-group-format='#ifdef NAME 311 %>#endif /* NAME */ 312 ' \ 313 --unchanged-group-format='%=' \ 314 --changed-group-format='#ifndef NAME 315 %<#else /* NAME */ 316 %>#endif /* NAME */ 317 ' 318 319 You should carefully check the `diff' output for proper nesting. 320For example, when using the the `-D NAME' or `--ifdef=NAME' option, you 321should check that if the differing lines contain any of the C 322preprocessor directives `#ifdef', `#ifndef', `#else', `#elif', or 323`#endif', they are nested properly and match. If they don't, you must 324make corrections manually. It is a good idea to carefully check the 325resulting code anyway to make sure that it really does what you want it 326to; depending on how the input files were produced, the output might 327contain duplicate or otherwise incorrect code. 328 329 The `patch' `-D NAME' option behaves just like the `diff' `-D NAME' 330option, except it operates on a file and a diff to produce a merged 331file; *Note patch Options::. 332 333 334File: diff.info, Node: Example If-then-else, Prev: Detailed If-then-else, Up: If-then-else 335 336An Example of If-then-else Format 337--------------------------------- 338 339 Here is the output of `diff -DTWO lao tzu' (*note Sample diff 340Input::., for the complete contents of the two files): 341 342 #ifndef TWO 343 The Way that can be told of is not the eternal Way; 344 The name that can be named is not the eternal name. 345 #endif /* not TWO */ 346 The Nameless is the origin of Heaven and Earth; 347 #ifndef TWO 348 The Named is the mother of all things. 349 #else /* TWO */ 350 The named is the mother of all things. 351 352 #endif /* TWO */ 353 Therefore let there always be non-being, 354 so we may see their subtlety, 355 And let there always be being, 356 so we may see their outcome. 357 The two are the same, 358 But after they are produced, 359 they have different names. 360 #ifdef TWO 361 They both may be called deep and profound. 362 Deeper and more profound, 363 The door of all subtleties! 364 #endif /* TWO */ 365 366 367File: diff.info, Node: Comparing Directories, Next: Adjusting Output, Prev: Output Formats, Up: Top 368 369Comparing Directories 370********************* 371 372 You can use `diff' to compare some or all of the files in two 373directory trees. When both file name arguments to `diff' are 374directories, it compares each file that is contained in both 375directories, examining file names in alphabetical order. Normally 376`diff' is silent about pairs of files that contain no differences, but 377if you use the `-s' or `--report-identical-files' option, it reports 378pairs of identical files. Normally `diff' reports subdirectories 379common to both directories without comparing subdirectories' files, but 380if you use the `-r' or `--recursive' option, it compares every 381corresponding pair of files in the directory trees, as many levels deep 382as they go. 383 384 For file names that are in only one of the directories, `diff' 385normally does not show the contents of the file that exists; it reports 386only that the file exists in that directory and not in the other. You 387can make `diff' act as though the file existed but was empty in the 388other directory, so that it outputs the entire contents of the file that 389actually exists. (It is output as either an insertion or a deletion, 390depending on whether it is in the first or the second directory given.) 391To do this, use the `-N' or `--new-file' option. 392 393 If the older directory contains one or more large files that are not 394in the newer directory, you can make the patch smaller by using the 395`-P' or `--unidirectional-new-file' option instead of `-N'. This 396option is like `-N' except that it only inserts the contents of files 397that appear in the second directory but not the first (that is, files 398that were added). At the top of the patch, write instructions for the 399user applying the patch to remove the files that were deleted before 400applying the patch. *Note Making Patches::, for more discussion of 401making patches for distribution. 402 403 To ignore some files while comparing directories, use the `-x 404PATTERN' or `--exclude=PATTERN' option. This option ignores any files 405or subdirectories whose base names match the shell pattern PATTERN. 406Unlike in the shell, a period at the start of the base of a file name 407matches a wildcard at the start of a pattern. You should enclose 408PATTERN in quotes so that the shell does not expand it. For example, 409the option `-x '*.[ao]'' ignores any file whose name ends with `.a' or 410`.o'. 411 412 This option accumulates if you specify it more than once. For 413example, using the options `-x 'RCS' -x '*,v'' ignores any file or 414subdirectory whose base name is `RCS' or ends with `,v'. 415 416 If you need to give this option many times, you can instead put the 417patterns in a file, one pattern per line, and use the `-X FILE' or 418`--exclude-from=FILE' option. 419 420 If you have been comparing two directories and stopped partway 421through, later you might want to continue where you left off. You can 422do this by using the `-S FILE' or `--starting-file=FILE' option. This 423compares only the file FILE and all alphabetically later files in the 424topmost directory level. 425 426 427File: diff.info, Node: Adjusting Output, Next: diff Performance, Prev: Comparing Directories, Up: Top 428 429Making `diff' Output Prettier 430***************************** 431 432 `diff' provides several ways to adjust the appearance of its output. 433These adjustments can be applied to any output format. 434 435* Menu: 436 437* Tabs:: Preserving the alignment of tabstops. 438* Pagination:: Page numbering and timestamping `diff' output. 439 440 441File: diff.info, Node: Tabs, Next: Pagination, Up: Adjusting Output 442 443Preserving Tabstop Alignment 444============================ 445 446 The lines of text in some of the `diff' output formats are preceded 447by one or two characters that indicate whether the text is inserted, 448deleted, or changed. The addition of those characters can cause tabs to 449move to the next tabstop, throwing off the alignment of columns in the 450line. GNU `diff' provides two ways to make tab-aligned columns line up 451correctly. 452 453 The first way is to have `diff' convert all tabs into the correct 454number of spaces before outputting them; select this method with the 455`-t' or `--expand-tabs' option. `diff' assumes that tabstops are set 456every 8 columns. To use this form of output with `patch', you must 457give `patch' the `-l' or `--ignore-white-space' option (*note Changed 458White Space::., for more information). 459 460 The other method for making tabs line up correctly is to add a tab 461character instead of a space after the indicator character at the 462beginning of the line. This ensures that all following tab characters 463are in the same position relative to tabstops that they were in the 464original files, so that the output is aligned correctly. Its 465disadvantage is that it can make long lines too long to fit on one line 466of the screen or the paper. It also does not work with the unified 467output format, which does not have a space character after the change 468type indicator character. Select this method with the `-T' or 469`--initial-tab' option. 470 471 472File: diff.info, Node: Pagination, Prev: Tabs, Up: Adjusting Output 473 474Paginating `diff' Output 475======================== 476 477 It can be convenient to have long output page-numbered and 478time-stamped. The `-l' and `--paginate' options do this by sending the 479`diff' output through the `pr' program. Here is what the page header 480might look like for `diff -lc lao tzu': 481 482 Mar 11 13:37 1991 diff -lc lao tzu Page 1 483 484 485File: diff.info, Node: diff Performance, Next: Comparing Three Files, Prev: Adjusting Output, Up: Top 486 487`diff' Performance Tradeoffs 488**************************** 489 490 GNU `diff' runs quite efficiently; however, in some circumstances 491you can cause it to run faster or produce a more compact set of changes. 492There are two ways that you can affect the performance of GNU `diff' by 493changing the way it compares files. 494 495 Performance has more than one dimension. These options improve one 496aspect of performance at the cost of another, or they improve 497performance in some cases while hurting it in others. 498 499 The way that GNU `diff' determines which lines have changed always 500comes up with a near-minimal set of differences. Usually it is good 501enough for practical purposes. If the `diff' output is large, you 502might want `diff' to use a modified algorithm that sometimes produces a 503smaller set of differences. The `-d' or `--minimal' option does this; 504however, it can also cause `diff' to run more slowly than usual, so it 505is not the default behavior. 506 507 When the files you are comparing are large and have small groups of 508changes scattered throughout them, you can use the `-H' or 509`--speed-large-files' option to make a different modification to the 510algorithm that `diff' uses. If the input files have a constant small 511density of changes, this option speeds up the comparisons without 512changing the output. If not, `diff' might produce a larger set of 513differences; however, the output will still be correct. 514 515 Normally `diff' discards the prefix and suffix that is common to 516both files before it attempts to find a minimal set of differences. 517This makes `diff' run faster, but occasionally it may produce 518non-minimal output. The `--horizon-lines=LINES' option prevents `diff' 519from discarding the last LINES lines of the prefix and the first LINES 520lines of the suffix. This gives `diff' further opportunities to find a 521minimal output. 522 523 524File: diff.info, Node: Comparing Three Files, Next: diff3 Merging, Prev: diff Performance, Up: Top 525 526Comparing Three Files 527********************* 528 529 Use the program `diff3' to compare three files and show any 530differences among them. (`diff3' can also merge files; see *Note diff3 531Merging::). 532 533 The "normal" `diff3' output format shows each hunk of differences 534without surrounding context. Hunks are labeled depending on whether 535they are two-way or three-way, and lines are annotated by their 536location in the input files. 537 538 *Note Invoking diff3::, for more information on how to run `diff3'. 539 540* Menu: 541 542* Sample diff3 Input:: Sample `diff3' input for examples. 543* Detailed diff3 Normal:: A detailed description of normal output format. 544* diff3 Hunks:: The format of normal output format. 545* Example diff3 Normal:: Sample output in the normal format. 546 547 548File: diff.info, Node: Sample diff3 Input, Next: Detailed diff3 Normal, Up: Comparing Three Files 549 550A Third Sample Input File 551========================= 552 553 Here is a third sample file that will be used in examples to 554illustrate the output of `diff3' and how various options can change it. 555The first two files are the same that we used for `diff' (*note Sample 556diff Input::.). This is the third sample file, called `tao': 557 558 The Way that can be told of is not the eternal Way; 559 The name that can be named is not the eternal name. 560 The Nameless is the origin of Heaven and Earth; 561 The named is the mother of all things. 562 563 Therefore let there always be non-being, 564 so we may see their subtlety, 565 And let there always be being, 566 so we may see their result. 567 The two are the same, 568 But after they are produced, 569 they have different names. 570 571 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 572 573 574File: diff.info, Node: Detailed diff3 Normal, Next: diff3 Hunks, Prev: Sample diff3 Input, Up: Comparing Three Files 575 576Detailed Description of `diff3' Normal Format 577============================================= 578 579 Each hunk begins with a line marked `===='. Three-way hunks have 580plain `====' lines, and two-way hunks have `1', `2', or `3' appended to 581specify which of the three input files differ in that hunk. The hunks 582contain copies of two or three sets of input lines each preceded by one 583or two commands identifying where the lines came from. 584 585 Normally, two spaces precede each copy of an input line to 586distinguish it from the commands. But with the `-T' or `--initial-tab' 587option, `diff3' uses a tab instead of two spaces; this lines up tabs 588correctly. *Note Tabs::, for more information. 589 590 Commands take the following forms: 591 592`FILE:La' 593 This hunk appears after line L of file FILE, and contains no lines 594 in that file. To edit this file to yield the other files, one 595 must append hunk lines taken from the other files. For example, 596 `1:11a' means that the hunk follows line 11 in the first file and 597 contains no lines from that file. 598 599`FILE:Rc' 600 This hunk contains the lines in the range R of file FILE. The 601 range R is a comma-separated pair of line numbers, or just one 602 number if the range is a singleton. To edit this file to yield the 603 other files, one must change the specified lines to be the lines 604 taken from the other files. For example, `2:11,13c' means that 605 the hunk contains lines 11 through 13 from the second file. 606 607 If the last line in a set of input lines is incomplete (*note 608Incomplete Lines::.), it is distinguished on output from a full line by 609a following line that starts with `\'. 610 611 612File: diff.info, Node: diff3 Hunks, Next: Example diff3 Normal, Prev: Detailed diff3 Normal, Up: Comparing Three Files 613 614`diff3' Hunks 615============= 616 617 Groups of lines that differ in two or three of the input files are 618called "diff3 hunks", by analogy with `diff' hunks (*note Hunks::.). 619If all three input files differ in a `diff3' hunk, the hunk is called a 620"three-way hunk"; if just two input files differ, it is a "two-way 621hunk". 622 623 As with `diff', several solutions are possible. When comparing the 624files `A', `B', and `C', `diff3' normally finds `diff3' hunks by 625merging the two-way hunks output by the two commands `diff A B' and 626`diff A C'. This does not necessarily minimize the size of the output, 627but exceptions should be rare. 628 629 For example, suppose `F' contains the three lines `a', `b', `f', `G' 630contains the lines `g', `b', `g', and `H' contains the lines `a', `b', 631`h'. `diff3 F G H' might output the following: 632 633 ====2 634 1:1c 635 3:1c 636 a 637 2:1c 638 g 639 ==== 640 1:3c 641 f 642 2:3c 643 g 644 3:3c 645 h 646 647because it found a two-way hunk containing `a' in the first and third 648files and `g' in the second file, then the single line `b' common to 649all three files, then a three-way hunk containing the last line of each 650file. 651 652 653File: diff.info, Node: Example diff3 Normal, Prev: diff3 Hunks, Up: Comparing Three Files 654 655An Example of `diff3' Normal Format 656=================================== 657 658 Here is the output of the command `diff3 lao tzu tao' (*note Sample 659diff3 Input::., for the complete contents of the files). Notice that 660it shows only the lines that are different among the three files. 661 662 ====2 663 1:1,2c 664 3:1,2c 665 The Way that can be told of is not the eternal Way; 666 The name that can be named is not the eternal name. 667 2:0a 668 ====1 669 1:4c 670 The Named is the mother of all things. 671 2:2,3c 672 3:4,5c 673 The named is the mother of all things. 674 675 ====3 676 1:8c 677 2:7c 678 so we may see their outcome. 679 3:9c 680 so we may see their result. 681 ==== 682 1:11a 683 2:11,13c 684 They both may be called deep and profound. 685 Deeper and more profound, 686 The door of all subtleties! 687 3:13,14c 688 689 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 690 691 692File: diff.info, Node: diff3 Merging, Next: Interactive Merging, Prev: Comparing Three Files, Up: Top 693 694Merging From a Common Ancestor 695****************************** 696 697 When two people have made changes to copies of the same file, 698`diff3' can produce a merged output that contains both sets of changes 699together with warnings about conflicts. 700 701 One might imagine programs with names like `diff4' and `diff5' to 702compare more than three files simultaneously, but in practice the need 703rarely arises. You can use `diff3' to merge three or more sets of 704changes to a file by merging two change sets at a time. 705 706 `diff3' can incorporate changes from two modified versions into a 707common preceding version. This lets you merge the sets of changes 708represented by the two newer files. Specify the common ancestor version 709as the second argument and the two newer versions as the first and third 710arguments, like this: 711 712 diff3 MINE OLDER YOURS 713 714You can remember the order of the arguments by noting that they are in 715alphabetical order. 716 717 You can think of this as subtracting OLDER from YOURS and adding the 718result to MINE, or as merging into MINE the changes that would turn 719OLDER into YOURS. This merging is well-defined as long as MINE and 720OLDER match in the neighborhood of each such change. This fails to be 721true when all three input files differ or when only OLDER differs; we 722call this a "conflict". When all three input files differ, we call the 723conflict an "overlap". 724 725 `diff3' gives you several ways to handle overlaps and conflicts. 726You can omit overlaps or conflicts, or select only overlaps, or mark 727conflicts with special `<<<<<<<' and `>>>>>>>' lines. 728 729 `diff3' can output the merge results as an `ed' script that that can 730be applied to the first file to yield the merged output. However, it 731is usually better to have `diff3' generate the merged output directly; 732this bypasses some problems with `ed'. 733 734* Menu: 735 736* Which Changes:: Selecting changes to incorporate. 737* Marking Conflicts:: Marking conflicts. 738* Bypassing ed:: Generating merged output directly. 739* Merging Incomplete Lines:: How `diff3' merges incomplete lines. 740* Saving the Changed File:: Emulating System V behavior. 741 742 743File: diff.info, Node: Which Changes, Next: Marking Conflicts, Up: diff3 Merging 744 745Selecting Which Changes to Incorporate 746====================================== 747 748 You can select all unmerged changes from OLDER to YOURS for merging 749into MINE with the `-e' or `--ed' option. You can select only the 750nonoverlapping unmerged changes with `-3' or `--easy-only', and you can 751select only the overlapping changes with `-x' or `--overlap-only'. 752 753 The `-e', `-3' and `-x' options select only "unmerged changes", i.e. 754changes where MINE and YOURS differ; they ignore changes from OLDER to 755YOURS where MINE and YOURS are identical, because they assume that such 756changes have already been merged. If this assumption is not a safe 757one, you can use the `-A' or `--show-all' option (*note Marking 758Conflicts::.). 759 760 Here is the output of the command `diff3' with each of these three 761options (*note Sample diff3 Input::., for the complete contents of the 762files). Notice that `-e' outputs the union of the disjoint sets of 763changes output by `-3' and `-x'. 764 765 Output of `diff3 -e lao tzu tao': 766 11a 767 768 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 769 . 770 8c 771 so we may see their result. 772 . 773 774 Output of `diff3 -3 lao tzu tao': 775 8c 776 so we may see their result. 777 . 778 779 Output of `diff3 -x lao tzu tao': 780 11a 781 782 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 783 . 784 785 786File: diff.info, Node: Marking Conflicts, Next: Bypassing ed, Prev: Which Changes, Up: diff3 Merging 787 788Marking Conflicts 789================= 790 791 `diff3' can mark conflicts in the merged output by bracketing them 792with special marker lines. A conflict that comes from two files A and 793B is marked as follows: 794 795 <<<<<<< A 796 lines from A 797 ======= 798 lines from B 799 >>>>>>> B 800 801 A conflict that comes from three files A, B and C is marked as 802follows: 803 804 <<<<<<< A 805 lines from A 806 ||||||| B 807 lines from B 808 ======= 809 lines from C 810 >>>>>>> C 811 812 The `-A' or `--show-all' option acts like the `-e' option, except 813that it brackets conflicts, and it outputs all changes from OLDER to 814YOURS, not just the unmerged changes. Thus, given the sample input 815files (*note Sample diff3 Input::.), `diff3 -A lao tzu tao' puts 816brackets around the conflict where only `tzu' differs: 817 818 <<<<<<< tzu 819 ======= 820 The Way that can be told of is not the eternal Way; 821 The name that can be named is not the eternal name. 822 >>>>>>> tao 823 824 And it outputs the three-way conflict as follows: 825 826 <<<<<<< lao 827 ||||||| tzu 828 They both may be called deep and profound. 829 Deeper and more profound, 830 The door of all subtleties! 831 ======= 832 833 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 834 >>>>>>> tao 835 836 The `-E' or `--show-overlap' option outputs less information than 837the `-A' or `--show-all' option, because it outputs only unmerged 838changes, and it never outputs the contents of the second file. Thus 839the `-E' option acts like the `-e' option, except that it brackets the 840first and third files from three-way overlapping changes. Similarly, 841`-X' acts like `-x', except it brackets all its (necessarily 842overlapping) changes. For example, for the three-way overlapping 843change above, the `-E' and `-X' options output the following: 844 845 <<<<<<< lao 846 ======= 847 848 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 849 >>>>>>> tao 850 851 If you are comparing files that have meaningless or uninformative 852names, you can use the `-L LABEL' or `--label=LABEL' option to show 853alternate names in the `<<<<<<<', `|||||||' and `>>>>>>>' brackets. 854This option can be given up to three times, once for each input file. 855Thus `diff3 -A -L X -L Y -L Z A B C' acts like `diff3 -A A B C', except 856that the output looks like it came from files named `X', `Y' and `Z' 857rather than from files named `A', `B' and `C'. 858 859 860File: diff.info, Node: Bypassing ed, Next: Merging Incomplete Lines, Prev: Marking Conflicts, Up: diff3 Merging 861 862Generating the Merged Output Directly 863===================================== 864 865 With the `-m' or `--merge' option, `diff3' outputs the merged file 866directly. This is more efficient than using `ed' to generate it, and 867works even with non-text files that `ed' would reject. If you specify 868`-m' without an `ed' script option, `-A' (`--show-all') is assumed. 869 870 For example, the command `diff3 -m lao tzu tao' (*note Sample diff3 871Input::. for a copy of the input files) would output the following: 872 873 <<<<<<< tzu 874 ======= 875 The Way that can be told of is not the eternal Way; 876 The name that can be named is not the eternal name. 877 >>>>>>> tao 878 The Nameless is the origin of Heaven and Earth; 879 The Named is the mother of all things. 880 Therefore let there always be non-being, 881 so we may see their subtlety, 882 And let there always be being, 883 so we may see their result. 884 The two are the same, 885 But after they are produced, 886 they have different names. 887 <<<<<<< lao 888 ||||||| tzu 889 They both may be called deep and profound. 890 Deeper and more profound, 891 The door of all subtleties! 892 ======= 893 894 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 895 >>>>>>> tao 896 897 898File: diff.info, Node: Merging Incomplete Lines, Next: Saving the Changed File, Prev: Bypassing ed, Up: diff3 Merging 899 900How `diff3' Merges Incomplete Lines 901=================================== 902 903 With `-m', incomplete lines (*note Incomplete Lines::.) are simply 904copied to the output as they are found; if the merged output ends in an 905conflict and one of the input files ends in an incomplete line, 906succeeding `|||||||', `=======' or `>>>>>>>' brackets appear somewhere 907other than the start of a line because they are appended to the 908incomplete line. 909 910 Without `-m', if an `ed' script option is specified and an 911incomplete line is found, `diff3' generates a warning and acts as if a 912newline had been present. 913 914 915File: diff.info, Node: Saving the Changed File, Prev: Merging Incomplete Lines, Up: diff3 Merging 916 917Saving the Changed File 918======================= 919 920 Traditional Unix `diff3' generates an `ed' script without the 921trailing `w' and and `q' commands that save the changes. System V 922`diff3' generates these extra commands. GNU `diff3' normally behaves 923like traditional Unix `diff3', but with the `-i' option it behaves like 924System V `diff3' and appends the `w' and `q' commands. 925 926 The `-i' option requires one of the `ed' script options `-AeExX3', 927and is incompatible with the merged output option `-m'. 928 929 930File: diff.info, Node: Interactive Merging, Next: Merging with patch, Prev: diff3 Merging, Up: Top 931 932Interactive Merging with `sdiff' 933******************************** 934 935 With `sdiff', you can merge two files interactively based on a 936side-by-side `-y' format comparison (*note Side by Side::.). Use `-o 937FILE' or `--output=FILE' to specify where to put the merged text. 938*Note Invoking sdiff::, for more details on the options to `sdiff'. 939 940 Another way to merge files interactively is to use the Emacs Lisp 941package `emerge'. *Note emerge: (emacs)emerge, for more information. 942 943* Menu: 944 945* sdiff Option Summary::Summary of `sdiff' options. 946* Merge Commands:: Merging two files interactively. 947 948 949File: diff.info, Node: sdiff Option Summary, Next: Merge Commands, Up: Interactive Merging 950 951Specifying `diff' Options to `sdiff' 952==================================== 953 954 The following `sdiff' options have the same meaning as for `diff'. 955*Note diff Options::, for the use of these options. 956 957 -a -b -d -i -t -v 958 -B -H -I REGEXP 959 960 --ignore-blank-lines --ignore-case 961 --ignore-matching-lines=REGEXP --ignore-space-change 962 --left-column --minimal --speed-large-files 963 --suppress-common-lines --expand-tabs 964 --text --version --width=COLUMNS 965 966 For historical reasons, `sdiff' has alternate names for some 967options. The `-l' option is equivalent to the `--left-column' option, 968and similarly `-s' is equivalent to `--suppress-common-lines'. The 969meaning of the `sdiff' `-w' and `-W' options is interchanged from that 970of `diff': with `sdiff', `-w COLUMNS' is equivalent to 971`--width=COLUMNS', and `-W' is equivalent to `--ignore-all-space'. 972`sdiff' without the `-o' option is equivalent to `diff' with the `-y' 973or `--side-by-side' option (*note Side by Side::.). 974 975 976File: diff.info, Node: Merge Commands, Prev: sdiff Option Summary, Up: Interactive Merging 977 978Merge Commands 979============== 980 981 Groups of common lines, with a blank gutter, are copied from the 982first file to the output. After each group of differing lines, `sdiff' 983prompts with `%' and pauses, waiting for one of the following commands. 984Follow each command with RET. 985 986`e' 987 Discard both versions. Invoke a text editor on an empty temporary 988 file, then copy the resulting file to the output. 989 990`eb' 991 Concatenate the two versions, edit the result in a temporary file, 992 then copy the edited result to the output. 993 994`el' 995 Edit a copy of the left version, then copy the result to the 996 output. 997 998`er' 999 Edit a copy of the right version, then copy the result to the 1000 output. 1001 1002`l' 1003 Copy the left version to the output. 1004 1005`q' 1006 Quit. 1007 1008`r' 1009 Copy the right version to the output. 1010 1011`s' 1012 Silently copy common lines. 1013 1014`v' 1015 Verbosely copy common lines. This is the default. 1016 1017 The text editor invoked is specified by the `EDITOR' environment 1018variable if it is set. The default is system-dependent. 1019 1020 1021File: diff.info, Node: Merging with patch, Next: Making Patches, Prev: Interactive Merging, Up: Top 1022 1023Merging with `patch' 1024******************** 1025 1026 `patch' takes comparison output produced by `diff' and applies the 1027differences to a copy of the original file, producing a patched 1028version. With `patch', you can distribute just the changes to a set of 1029files instead of distributing the entire file set; your correspondents 1030can apply `patch' to update their copy of the files with your changes. 1031`patch' automatically determines the diff format, skips any leading or 1032trailing headers, and uses the headers to determine which file to 1033patch. This lets your correspondents feed an article or message 1034containing a difference listing directly to `patch'. 1035 1036 `patch' detects and warns about common problems like forward 1037patches. It saves the original version of the files it patches, and 1038saves any patches that it could not apply. It can also maintain a 1039`patchlevel.h' file to ensures that your correspondents apply diffs in 1040the proper order. 1041 1042 `patch' accepts a series of diffs in its standard input, usually 1043separated by headers that specify which file to patch. It applies 1044`diff' hunks (*note Hunks::.) one by one. If a hunk does not exactly 1045match the original file, `patch' uses heuristics to try to patch the 1046file as well as it can. If no approximate match can be found, `patch' 1047rejects the hunk and skips to the next hunk. `patch' normally replaces 1048each file F with its new version, saving the original file in `F.orig', 1049and putting reject hunks (if any) into `F.rej'. 1050 1051 *Note Invoking patch::, for detailed information on the options to 1052`patch'. *Note Backups::, for more information on how `patch' names 1053backup files. *Note Rejects::, for more information on where `patch' 1054puts reject hunks. 1055 1056* Menu: 1057 1058* patch Input:: Selecting the type of `patch' input. 1059* Imperfect:: Dealing with imperfect patches. 1060* Empty Files:: Removing empty files after patching. 1061* Multiple Patches:: Handling multiple patches in a file specially. 1062* patch Messages:: Messages and questions `patch' can produce. 1063 1064 1065File: diff.info, Node: patch Input, Next: Imperfect, Up: Merging with patch 1066 1067Selecting the `patch' Input Format 1068================================== 1069 1070 `patch' normally determines which `diff' format the patch file uses 1071by examining its contents. For patch files that contain particularly 1072confusing leading text, you might need to use one of the following 1073options to force `patch' to interpret the patch file as a certain 1074format of diff. The output formats listed here are the only ones that 1075`patch' can understand. 1076 1077`-c' 1078`--context' 1079 context diff. 1080 1081`-e' 1082`--ed' 1083 `ed' script. 1084 1085`-n' 1086`--normal' 1087 normal diff. 1088 1089`-u' 1090`--unified' 1091 unified diff. 1092 1093 1094File: diff.info, Node: Imperfect, Next: Empty Files, Prev: patch Input, Up: Merging with patch 1095 1096Applying Imperfect Patches 1097========================== 1098 1099 `patch' tries to skip any leading text in the patch file, apply the 1100diff, and then skip any trailing text. Thus you can feed a news article 1101or mail message directly to `patch', and it should work. If the entire 1102diff is indented by a constant amount of white space, `patch' 1103automatically ignores the indentation. 1104 1105 However, certain other types of imperfect input require user 1106intervention. 1107 1108* Menu: 1109 1110* Changed White Space:: When tabs and spaces don't match exactly. 1111* Reversed Patches:: Applying reversed patches correctly. 1112* Inexact:: Helping `patch' find close matches. 1113 1114 1115File: diff.info, Node: Changed White Space, Next: Reversed Patches, Up: Imperfect 1116 1117Applying Patches with Changed White Space 1118----------------------------------------- 1119 1120 Sometimes mailers, editors, or other programs change spaces into 1121tabs, or vice versa. If this happens to a patch file or an input file, 1122the files might look the same, but `patch' will not be able to match 1123them properly. If this problem occurs, use the `-l' or 1124`--ignore-white-space' option, which makes `patch' compare white space 1125loosely so that any sequence of white space in the patch file matches 1126any sequence of white space in the input files. Non-white-space 1127characters must still match exactly. Each line of the context must 1128still match a line in the input file. 1129 1130 1131File: diff.info, Node: Reversed Patches, Next: Inexact, Prev: Changed White Space, Up: Imperfect 1132 1133Applying Reversed Patches 1134------------------------- 1135 1136 Sometimes people run `diff' with the new file first instead of 1137second. This creates a diff that is "reversed". To apply such 1138patches, give `patch' the `-R' or `--reverse' option. `patch' then 1139attempts to swap each hunk around before applying it. Rejects come out 1140in the swapped format. The `-R' option does not work with `ed' scripts 1141because there is too little information in them to reconstruct the 1142reverse operation. 1143 1144 Often `patch' can guess that the patch is reversed. If the first 1145hunk of a patch fails, `patch' reverses the hunk to see if it can apply 1146it that way. If it can, `patch' asks you if you want to have the `-R' 1147option set; if it can't, `patch' continues to apply the patch normally. 1148This method cannot detect a reversed patch if it is a normal diff and 1149the first command is an append (which should have been a delete) since 1150appends always succeed, because a null context matches anywhere. But 1151most patches add or change lines rather than delete them, so most 1152reversed normal diffs begin with a delete, which fails, and `patch' 1153notices. 1154 1155 If you apply a patch that you have already applied, `patch' thinks 1156it is a reversed patch and offers to un-apply the patch. This could be 1157construed as a feature. If you did this inadvertently and you don't 1158want to un-apply the patch, just answer `n' to this offer and to the 1159subsequent "apply anyway" question--or type `C-c' to kill the `patch' 1160process. 1161 1162 1163File: diff.info, Node: Inexact, Prev: Reversed Patches, Up: Imperfect 1164 1165Helping `patch' Find Inexact Matches 1166------------------------------------ 1167 1168 For context diffs, and to a lesser extent normal diffs, `patch' can 1169detect when the line numbers mentioned in the patch are incorrect, and 1170it attempts to find the correct place to apply each hunk of the patch. 1171As a first guess, it takes the line number mentioned in the hunk, plus 1172or minus any offset used in applying the previous hunk. If that is not 1173the correct place, `patch' scans both forward and backward for a set of 1174lines matching the context given in the hunk. 1175 1176 First `patch' looks for a place where all lines of the context 1177match. If it cannot find such a place, and it is reading a context or 1178unified diff, and the maximum fuzz factor is set to 1 or more, then 1179`patch' makes another scan, ignoring the first and last line of 1180context. If that fails, and the maximum fuzz factor is set to 2 or 1181more, it makes another scan, ignoring the first two and last two lines 1182of context are ignored. It continues similarly if the maximum fuzz 1183factor is larger. 1184 1185 The `-F LINES' or `--fuzz=LINES' option sets the maximum fuzz factor 1186to LINES. This option only applies to context and unified diffs; it 1187ignores up to LINES lines while looking for the place to install a 1188hunk. Note that a larger fuzz factor increases the odds of making a 1189faulty patch. The default fuzz factor is 2; it may not be set to more 1190than the number of lines of context in the diff, ordinarily 3. 1191 1192 If `patch' cannot find a place to install a hunk of the patch, it 1193writes the hunk out to a reject file (*note Rejects::., for information 1194on how reject files are named). It writes out rejected hunks in context 1195format no matter what form the input patch is in. If the input is a 1196normal or `ed' diff, many of the contexts are simply null. The line 1197numbers on the hunks in the reject file may be different from those in 1198the patch file: they show the approximate location where `patch' thinks 1199the failed hunks belong in the new file rather than in the old one. 1200 1201 As it completes each hunk, `patch' tells you whether the hunk 1202succeeded or failed, and if it failed, on which line (in the new file) 1203`patch' thinks the hunk should go. If this is different from the line 1204number specified in the diff, it tells you the offset. A single large 1205offset *may* indicate that `patch' installed a hunk in the wrong place. 1206`patch' also tells you if it used a fuzz factor to make the match, in 1207which case you should also be slightly suspicious. 1208 1209 `patch' cannot tell if the line numbers are off in an `ed' script, 1210and can only detect wrong line numbers in a normal diff when it finds a 1211change or delete command. It may have the same problem with a context 1212diff using a fuzz factor equal to or greater than the number of lines 1213of context shown in the diff (typically 3). In these cases, you should 1214probably look at a context diff between your original and patched input 1215files to see if the changes make sense. Compiling without errors is a 1216pretty good indication that the patch worked, but not a guarantee. 1217 1218 `patch' usually produces the correct results, even when it must make 1219many guesses. However, the results are guaranteed only when the patch 1220is applied to an exact copy of the file that the patch was generated 1221from. 1222 1223 1224File: diff.info, Node: Empty Files, Next: Multiple Patches, Prev: Imperfect, Up: Merging with patch 1225 1226Removing Empty Files 1227==================== 1228 1229 Sometimes when comparing two directories, the first directory 1230contains a file that the second directory does not. If you give `diff' 1231the `-N' or `--new-file' option, it outputs a diff that deletes the 1232contents of this file. By default, `patch' leaves an empty file after 1233applying such a diff. The `-E' or `--remove-empty-files' option to 1234`patch' deletes output files that are empty after applying the diff. 1235 1236 1237File: diff.info, Node: Multiple Patches, Next: patch Messages, Prev: Empty Files, Up: Merging with patch 1238 1239Multiple Patches in a File 1240========================== 1241 1242 If the patch file contains more than one patch, `patch' tries to 1243apply each of them as if they came from separate patch files. This 1244means that it determines the name of the file to patch for each patch, 1245and that it examines the leading text before each patch for file names 1246and prerequisite revision level (*note Making Patches::., for more on 1247that topic). 1248 1249 For the second and subsequent patches in the patch file, you can give 1250options and another original file name by separating their argument 1251lists with a `+'. However, the argument list for a second or 1252subsequent patch may not specify a new patch file, since that does not 1253make sense. 1254 1255 For example, to tell `patch' to strip the first three slashes from 1256the name of the first patch in the patch file and none from subsequent 1257patches, and to use `code.c' as the first input file, you can use: 1258 1259 patch -p3 code.c + -p0 < patchfile 1260 1261 The `-S' or `--skip' option ignores the current patch from the patch 1262file, but continue looking for the next patch in the file. Thus, to 1263ignore the first and third patches in the patch file, you can use: 1264 1265 patch -S + + -S + < patch file 1266 1267 1268File: diff.info, Node: patch Messages, Prev: Multiple Patches, Up: Merging with patch 1269 1270Messages and Questions from `patch' 1271=================================== 1272 1273 `patch' can produce a variety of messages, especially if it has 1274trouble decoding its input. In a few situations where it's not sure how 1275to proceed, `patch' normally prompts you for more information from the 1276keyboard. There are options to suppress printing non-fatal messages 1277and stopping for keyboard input. 1278 1279 The message `Hmm...' indicates that `patch' is reading text in the 1280patch file, attempting to determine whether there is a patch in that 1281text, and if so, what kind of patch it is. 1282 1283 You can inhibit all terminal output from `patch', unless an error 1284occurs, by using the `-s', `--quiet', or `--silent' option. 1285 1286 There are two ways you can prevent `patch' from asking you any 1287questions. The `-f' or `--force' option assumes that you know what you 1288are doing. It assumes the following: 1289 1290 * skip patches that do not contain file names in their headers; 1291 1292 * patch files even though they have the wrong version for the 1293 `Prereq:' line in the patch; 1294 1295 * assume that patches are not reversed even if they look like they 1296 are. 1297 1298 The `-t' or `--batch' option is similar to `-f', in that it 1299suppresses questions, but it makes somewhat different assumptions: 1300 1301 * skip patches that do not contain file names in their headers (the 1302 same as `-f'); 1303 1304 * skip patches for which the file has the wrong version for the 1305 `Prereq:' line in the patch; 1306 1307 * assume that patches are reversed if they look like they are. 1308 1309 `patch' exits with a non-zero status if it creates any reject files. 1310When applying a set of patches in a loop, you should check the exit 1311status, so you don't apply a later patch to a partially patched file. 1312 1313