1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename diff.info 4@settitle Comparing and Merging Files 5@setchapternewpage odd 6@c %**end of header 7 8@ifinfo 9This file documents the the GNU @code{diff}, @code{diff3}, @code{sdiff}, 10and @code{cmp} commands for showing the differences between text files 11and the @code{patch} command for using their output to update files. 12 13Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. 14 15Permission is granted to make and distribute verbatim copies of 16this manual provided the copyright notice and this permission notice 17are preserved on all copies. 18 19@ignore 20Permission is granted to process this file through TeX and print the 21results, provided the printed document carries copying permission 22notice identical to this one except for the removal of this paragraph 23(this paragraph not being relevant to the printed manual). 24 25@end ignore 26Permission is granted to copy and distribute modified versions of this 27manual under the conditions for verbatim copying, provided that the entire 28resulting derived work is distributed under the terms of a permission 29notice identical to this one. 30 31Permission is granted to copy and distribute translations of this manual 32into another language, under the above conditions for modified versions, 33except that this permission notice may be stated in a translation approved 34by the Foundation. 35@end ifinfo 36 37@titlepage 38@title Comparing and Merging Files 39@subtitle @code{diff}, @code{diff3}, @code{sdiff}, @code{cmp}, and @code{patch} 40@subtitle Edition 1.3, for @code{diff} 2.5 and @code{patch} 2.1 41@subtitle September 1993 42@author by David MacKenzie, Paul Eggert, and Richard Stallman 43 44@page 45@vskip 0pt plus 1filll 46Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. 47 48Permission is granted to make and distribute verbatim copies of 49this manual provided the copyright notice and this permission notice 50are preserved on all copies. 51 52Permission is granted to copy and distribute modified versions of this 53manual under the conditions for verbatim copying, provided that the entire 54resulting derived work is distributed under the terms of a permission 55notice identical to this one. 56 57Permission is granted to copy and distribute translations of this manual 58into another language, under the above conditions for modified versions, 59except that this permission notice may be stated in a translation approved 60by the Foundation. 61@end titlepage 62 63@node Top, , , (dir) 64 65@ifinfo 66This file documents the the GNU @code{diff}, @code{diff3}, @code{sdiff}, 67and @code{cmp} commands for showing the differences between text files 68and the @code{patch} command for using their output to update files. 69 70This is Edition 1.2, for @code{diff} 2.4 and @code{patch} 2.1. 71@end ifinfo 72 73@menu 74* Overview:: Preliminary information. 75 76* Comparison:: What file comparison means. 77* Output Formats:: Formats for difference reports. 78* Comparing Directories:: Comparing files and directories. 79* Adjusting Output:: Making @code{diff} output prettier. 80* diff Performance:: Making @code{diff} smarter or faster. 81* Comparing Three Files:: Formats for three-way difference reports. 82 83* diff3 Merging:: Merging from a common ancestor. 84* Interactive Merging:: Interactive merging with @code{sdiff}. 85* Merging with patch:: Using @code{patch} to change old files into new ones. 86* Making Patches:: Tips for making patch distributions. 87 88* Invoking cmp:: How to run @code{cmp} and a summary of its options. 89* Invoking diff:: How to run @code{diff} and a summary of its options. 90* Invoking diff3:: How to run @code{diff3} and a summary of its options. 91* Invoking patch:: How to run @code{patch} and a summary of its options. 92* Invoking sdiff:: How to run @code{sdiff} and a summary of its options. 93 94* Incomplete Lines:: Lines that lack trailing newlines. 95* Projects:: If you think you've found a bug or other shortcoming. 96 97* Concept Index:: Index of concepts. 98@end menu 99 100@node Overview, Comparison, , Top 101@unnumbered Overview 102@cindex overview of @code{diff} and @code{patch} 103 104Computer users often find occasion to ask how two files differ. Perhaps 105one file is a newer version of the other file. Or maybe the two files 106started out as identical copies but were changed by different people. 107 108You can use the @code{diff} command to show differences between two 109files, or each corresponding file in two directories. @code{diff} 110outputs differences between files line by line in any of several 111formats, selectable by command line options. This set of differences is 112often called a @dfn{diff} or @dfn{patch}. For files that are identical, 113@code{diff} normally produces no output; for binary (non-text) files, 114@code{diff} normally reports only that they are different. 115 116You can use the @code{cmp} command to show the offsets and line numbers 117where two files differ. @code{cmp} can also show all the characters 118that differ between the two files, side by side. Another way to compare 119two files character by character is the Emacs command @kbd{M-x 120compare-windows}. @xref{Other Window, , Other Window, emacs, The GNU 121Emacs Manual}, for more information on that command. 122 123You can use the @code{diff3} command to show differences among three 124files. When two people have made independent changes to a common 125original, @code{diff3} can report the differences between the original 126and the two changed versions, and can produce a merged file that 127contains both persons' changes together with warnings about conflicts. 128 129You can use the @code{sdiff} command to merge two files interactively. 130 131You can use the set of differences produced by @code{diff} to distribute 132updates to text files (such as program source code) to other people. 133This method is especially useful when the differences are small compared 134to the complete files. Given @code{diff} output, you can use the 135@code{patch} program to update, or @dfn{patch}, a copy of the file. If you 136think of @code{diff} as subtracting one file from another to produce 137their difference, you can think of @code{patch} as adding the difference 138to one file to reproduce the other. 139 140This manual first concentrates on making diffs, and later shows how to 141use diffs to update files. 142 143GNU @code{diff} was written by Mike Haertel, David Hayes, Richard 144Stallman, Len Tower, and Paul Eggert. Wayne Davison designed and 145implemented the unified output format. The basic algorithm is described 146in ``An O(ND) Difference Algorithm and its Variations'', Eugene W. Myers, 147@cite{Algorithmica} Vol.@: 1 No.@: 2, 1986, pp.@: 251--266; and in ``A File 148Comparison Program'', Webb Miller and Eugene W. Myers, 149@cite{Software---Practice and Experience} Vol.@: 15 No.@: 11, 1985, 150pp.@: 1025--1040. 151@c From: "Gene Myers" <gene@cs.arizona.edu> 152@c They are about the same basic algorithm; the Algorithmica 153@c paper gives a rigorous treatment and the sub-algorithm for 154@c delivering scripts and should be the primary reference, but 155@c both should be mentioned. 156The algorithm was independently discovered as described in 157``Algorithms for Approximate String Matching'', 158E. Ukkonen, @cite{Information and Control} Vol.@: 64, 1985, pp.@: 100--118. 159@c From: "Gene Myers" <gene@cs.arizona.edu> 160@c Date: Wed, 29 Sep 1993 08:27:55 MST 161@c Ukkonen should be given credit for also discovering the algorithm used 162@c in GNU diff. 163 164GNU @code{diff3} was written by Randy Smith. GNU @code{sdiff} was 165written by Thomas Lord. GNU @code{cmp} was written by Torbjorn Granlund 166and David MacKenzie. 167 168@code{patch} was written mainly by Larry Wall; the GNU enhancements were 169written mainly by Wayne Davison and David MacKenzie. Parts of this 170manual are adapted from a manual page written by Larry Wall, with his 171permission. 172 173@node Comparison, Output Formats, Overview, Top 174@chapter What Comparison Means 175@cindex introduction 176 177There are several ways to think about the differences between two files. 178One way to think of the differences is as a series of lines that were 179deleted from, inserted in, or changed in one file to produce the other 180file. @code{diff} compares two files line by line, finds groups of 181lines that differ, and reports each group of differing lines. It can 182report the differing lines in several formats, which have different 183purposes. 184 185GNU @code{diff} can show whether files are different without detailing 186the differences. It also provides ways to suppress certain kinds of 187differences that are not important to you. Most commonly, such 188differences are changes in the amount of white space between words or 189lines. @code{diff} also provides ways to suppress differences in 190alphabetic case or in lines that match a regular expression that you 191provide. These options can accumulate; for example, you can ignore 192changes in both white space and alphabetic case. 193 194Another way to think of the differences between two files is as a 195sequence of pairs of characters that can be either identical or 196different. @code{cmp} reports the differences between two files 197character by character, instead of line by line. As a result, it is 198more useful than @code{diff} for comparing binary files. For text 199files, @code{cmp} is useful mainly when you want to know only whether 200two files are identical. 201 202To illustrate the effect that considering changes character by character 203can have compared with considering them line by line, think of what 204happens if a single newline character is added to the beginning of a 205file. If that file is then compared with an otherwise identical file 206that lacks the newline at the beginning, @code{diff} will report that a 207blank line has been added to the file, while @code{cmp} will report that 208almost every character of the two files differs. 209 210@code{diff3} normally compares three input files line by line, finds 211groups of lines that differ, and reports each group of differing lines. 212Its output is designed to make it easy to inspect two different sets of 213changes to the same file. 214 215@menu 216* Hunks:: Groups of differing lines. 217* White Space:: Suppressing differences in white space. 218* Blank Lines:: Suppressing differences in blank lines. 219* Case Folding:: Suppressing differences in alphabetic case. 220* Specified Folding:: Suppressing differences that match regular expressions. 221* Brief:: Summarizing which files are different. 222* Binary:: Comparing binary files or forcing text comparisons. 223@end menu 224 225@node Hunks, White Space, , Comparison 226@section Hunks 227@cindex hunks 228 229When comparing two files, @code{diff} finds sequences of lines common to 230both files, interspersed with groups of differing lines called 231@dfn{hunks}. Comparing two identical files yields one sequence of 232common lines and no hunks, because no lines differ. Comparing two 233entirely different files yields no common lines and one large hunk that 234contains all lines of both files. In general, there are many ways to 235match up lines between two given files. @code{diff} tries to minimize 236the total hunk size by finding large sequences of common lines 237interspersed with small hunks of differing lines. 238 239For example, suppose the file @file{F} contains the three lines 240@samp{a}, @samp{b}, @samp{c}, and the file @file{G} contains the same 241three lines in reverse order @samp{c}, @samp{b}, @samp{a}. If 242@code{diff} finds the line @samp{c} as common, then the command 243@samp{diff F G} produces this output: 244 245@example 2461,2d0 247< a 248< b 2493a2,3 250> b 251> a 252@end example 253 254@noindent 255But if @code{diff} notices the common line @samp{b} instead, it produces 256this output: 257 258@example 2591c1 260< a 261--- 262> c 2633c3 264< c 265--- 266> a 267@end example 268 269@noindent 270It is also possible to find @samp{a} as the common line. @code{diff} 271does not always find an optimal matching between the files; it takes 272shortcuts to run faster. But its output is usually close to the 273shortest possible. You can adjust this tradeoff with the 274@samp{--minimal} option (@pxref{diff Performance}). 275 276@node White Space, Blank Lines, Hunks, Comparison 277@section Suppressing Differences in Blank and Tab Spacing 278@cindex blank and tab difference suppression 279@cindex tab and blank difference suppression 280 281The @samp{-b} and @samp{--ignore-space-change} options ignore white space 282at line end, and considers all other sequences of one or more 283white space characters to be equivalent. With these options, 284@code{diff} considers the following two lines to be equivalent, where 285@samp{$} denotes the line end: 286 287@example 288Here lyeth muche rychnesse in lytell space. -- John Heywood$ 289Here lyeth muche rychnesse in lytell space. -- John Heywood $ 290@end example 291 292The @samp{-w} and @samp{--ignore-all-space} options are stronger than 293@samp{-b}. They ignore difference even if one file has white space where 294the other file has none. @dfn{White space} characters include 295tab, newline, vertical tab, form feed, carriage return, and space; 296some locales may define additional characters to be white space. 297With these options, @code{diff} considers the 298following two lines to be equivalent, where @samp{$} denotes the line 299end and @samp{^M} denotes a carriage return: 300 301@example 302Here lyeth muche rychnesse in lytell space.-- John Heywood$ 303 He relyeth much erychnes seinly tells pace. --John Heywood ^M$ 304@end example 305 306@node Blank Lines, Case Folding, White Space, Comparison 307@section Suppressing Differences in Blank Lines 308@cindex blank line difference suppression 309 310The @samp{-B} and @samp{--ignore-blank-lines} options ignore insertions 311or deletions of blank lines. These options normally affect only lines 312that are completely empty; they do not affect lines that look empty but 313contain space or tab characters. With these options, for example, a 314file containing 315@example 3161. A point is that which has no part. 317 3182. A line is breadthless length. 319-- Euclid, The Elements, I 320@end example 321@noindent 322is considered identical to a file containing 323@example 3241. A point is that which has no part. 3252. A line is breadthless length. 326 327 328-- Euclid, The Elements, I 329@end example 330 331@node Case Folding, Specified Folding, Blank Lines, Comparison 332@section Suppressing Case Differences 333@cindex case difference suppression 334 335GNU @code{diff} can treat lowercase letters as equivalent to their 336uppercase counterparts, so that, for example, it considers @samp{Funky 337Stuff}, @samp{funky STUFF}, and @samp{fUNKy stuFf} to all be the same. 338To request this, use the @samp{-i} or @samp{--ignore-case} option. 339 340@node Specified Folding, Brief, Case Folding, Comparison 341@section Suppressing Lines Matching a Regular Expression 342@cindex regular expression suppression 343 344To ignore insertions and deletions of lines that match a regular 345expression, use the @samp{-I @var{regexp}} or 346@samp{--ignore-matching-lines=@var{regexp}} option. You should escape 347regular expressions that contain shell metacharacters to prevent the 348shell from expanding them. For example, @samp{diff -I '^[0-9]'} ignores 349all changes to lines beginning with a digit. 350 351However, @samp{-I} only ignores the insertion or deletion of lines that 352contain the regular expression if every changed line in the hunk---every 353insertion and every deletion---matches the regular expression. In other 354words, for each nonignorable change, @code{diff} prints the complete set 355of changes in its vicinity, including the ignorable ones. 356 357You can specify more than one regular expression for lines to ignore by 358using more than one @samp{-I} option. @code{diff} tries to match each 359line against each regular expression, starting with the last one given. 360 361@node Brief, Binary, Specified Folding, Comparison 362@section Summarizing Which Files Differ 363@cindex summarizing which files differ 364@cindex brief difference reports 365 366When you only want to find out whether files are different, and you 367don't care what the differences are, you can use the summary output 368format. In this format, instead of showing the differences between the 369files, @code{diff} simply reports whether files differ. The @samp{-q} 370and @samp{--brief} options select this output format. 371 372This format is especially useful when comparing the contents of two 373directories. It is also much faster than doing the normal line by line 374comparisons, because @code{diff} can stop analyzing the files as soon as 375it knows that there are any differences. 376 377You can also get a brief indication of whether two files differ by using 378@code{cmp}. For files that are identical, @code{cmp} produces no 379output. When the files differ, by default, @code{cmp} outputs the byte 380offset and line number where the first difference occurs. You can use 381the @samp{-s} option to suppress that information, so that @code{cmp} 382produces no output and reports whether the files differ using only its 383exit status (@pxref{Invoking cmp}). 384 385@c Fix this. 386Unlike @code{diff}, @code{cmp} cannot compare directories; it can only 387compare two files. 388 389@node Binary, , Brief, Comparison 390@section Binary Files and Forcing Text Comparisons 391@cindex binary file diff 392@cindex text versus binary diff 393 394If @code{diff} thinks that either of the two files it is comparing is 395binary (a non-text file), it normally treats that pair of files much as 396if the summary output format had been selected (@pxref{Brief}), and 397reports only that the binary files are different. This is because line 398by line comparisons are usually not meaningful for binary files. 399 400@code{diff} determines whether a file is text or binary by checking the 401first few bytes in the file; the exact number of bytes is system 402dependent, but it is typically several thousand. If every character in 403that part of the file is non-null, @code{diff} considers the file to be 404text; otherwise it considers the file to be binary. 405 406Sometimes you might want to force @code{diff} to consider files to be 407text. For example, you might be comparing text files that contain 408null characters; @code{diff} would erroneously decide that those are 409non-text files. Or you might be comparing documents that are in a 410format used by a word processing system that uses null characters to 411indicate special formatting. You can force @code{diff} to consider all 412files to be text files, and compare them line by line, by using the 413@samp{-a} or @samp{--text} option. If the files you compare using this 414option do not in fact contain text, they will probably contain few 415newline characters, and the @code{diff} output will consist of hunks 416showing differences between long lines of whatever characters the files 417contain. 418 419You can also force @code{diff} to consider all files to be binary files, 420and report only whether they differ (but not how). Use the 421@samp{--brief} option for this. 422 423In operating systems that distinguish between text and binary files, 424@code{diff} normally reads and writes all data as text. Use the 425@samp{--binary} option to force @code{diff} to read and write binary 426data instead. This option has no effect on a Posix-compliant system 427like GNU or traditional Unix. However, many personal computer 428operating systems represent the end of a line with a carriage return 429followed by a newline. On such systems, @code{diff} normally ignores 430these carriage returns on input and generates them at the end of each 431output line, but with the @samp{--binary} option @code{diff} treats 432each carriage return as just another input character, and does not 433generate a carriage return at the end of each output line. This can be 434useful when dealing with non-text files that are meant to be 435interchanged with Posix-compliant systems. 436 437If you want to compare two files byte by byte, you can use the 438@code{cmp} program with the @samp{-l} option to show the values of each 439differing byte in the two files. With GNU @code{cmp}, you can also use 440the @samp{-c} option to show the ASCII representation of those bytes. 441@xref{Invoking cmp}, for more information. 442 443If @code{diff3} thinks that any of the files it is comparing is binary 444(a non-text file), it normally reports an error, because such 445comparisons are usually not useful. @code{diff3} uses the same test as 446@code{diff} to decide whether a file is binary. As with @code{diff}, if 447the input files contain a few non-text characters but otherwise are like 448text files, you can force @code{diff3} to consider all files to be text 449files and compare them line by line by using the @samp{-a} or 450@samp{--text} options. 451 452@node Output Formats, Comparing Directories, Comparison, Top 453@chapter @code{diff} Output Formats 454@cindex output formats 455@cindex format of @code{diff} output 456 457@code{diff} has several mutually exclusive options for output format. 458The following sections describe each format, illustrating how 459@code{diff} reports the differences between two sample input files. 460 461@menu 462* Sample diff Input:: Sample @code{diff} input files for examples. 463* Normal:: Showing differences without surrounding text. 464* Context:: Showing differences with the surrounding text. 465* Side by Side:: Showing differences in two columns. 466* Scripts:: Generating scripts for other programs. 467* If-then-else:: Merging files with if-then-else. 468@end menu 469 470@node Sample diff Input, Normal, , Output Formats 471@section Two Sample Input Files 472@cindex @code{diff} sample input 473@cindex sample input for @code{diff} 474 475Here are two sample files that we will use in numerous examples to 476illustrate the output of @code{diff} and how various options can change 477it. 478 479This is the file @file{lao}: 480 481@example 482The Way that can be told of is not the eternal Way; 483The name that can be named is not the eternal name. 484The Nameless is the origin of Heaven and Earth; 485The Named is the mother of all things. 486Therefore let there always be non-being, 487 so we may see their subtlety, 488And let there always be being, 489 so we may see their outcome. 490The two are the same, 491But after they are produced, 492 they have different names. 493@end example 494 495This is the file @file{tzu}: 496 497@example 498The Nameless is the origin of Heaven and Earth; 499The named is the mother of all things. 500 501Therefore let there always be non-being, 502 so we may see their subtlety, 503And let there always be being, 504 so we may see their outcome. 505The two are the same, 506But after they are produced, 507 they have different names. 508They both may be called deep and profound. 509Deeper and more profound, 510The door of all subtleties! 511@end example 512 513In this example, the first hunk contains just the first two lines of 514@file{lao}, the second hunk contains the fourth line of @file{lao} 515opposing the second and third lines of @file{tzu}, and the last hunk 516contains just the last three lines of @file{tzu}. 517 518@node Normal, Context, Sample diff Input, Output Formats 519@section Showing Differences Without Context 520@cindex normal output format 521@cindex @samp{<} output format 522 523The ``normal'' @code{diff} output format shows each hunk of differences 524without any surrounding context. Sometimes such output is the clearest 525way to see how lines have changed, without the clutter of nearby 526unchanged lines (although you can get similar results with the context 527or unified formats by using 0 lines of context). However, this format 528is no longer widely used for sending out patches; for that purpose, the 529context format (@pxref{Context Format}) and the unified format 530(@pxref{Unified Format}) are superior. Normal format is the default for 531compatibility with older versions of @code{diff} and the Posix standard. 532 533@menu 534* Detailed Normal:: A detailed description of normal output format. 535* Example Normal:: Sample output in the normal format. 536@end menu 537 538@node Detailed Normal, Example Normal, , Normal 539@subsection Detailed Description of Normal Format 540 541The normal output format consists of one or more hunks of differences; 542each hunk shows one area where the files differ. Normal format hunks 543look like this: 544 545@example 546@var{change-command} 547< @var{from-file-line} 548< @var{from-file-line}@dots{} 549--- 550> @var{to-file-line} 551> @var{to-file-line}@dots{} 552@end example 553 554There are three types of change commands. Each consists of a line 555number or comma-separated range of lines in the first file, a single 556character indicating the kind of change to make, and a line number or 557comma-separated range of lines in the second file. All line numbers are 558the original line numbers in each file. The types of change commands 559are: 560 561@table @samp 562@item @var{l}a@var{r} 563Add the lines in range @var{r} of the second file after line @var{l} of 564the first file. For example, @samp{8a12,15} means append lines 12--15 565of file 2 after line 8 of file 1; or, if changing file 2 into file 1, 566delete lines 12--15 of file 2. 567 568@item @var{f}c@var{t} 569Replace the lines in range @var{f} of the first file with lines in range 570@var{t} of the second file. This is like a combined add and delete, but 571more compact. For example, @samp{5,7c8,10} means change lines 5--7 of 572file 1 to read as lines 8--10 of file 2; or, if changing file 2 into 573file 1, change lines 8--10 of file 2 to read as lines 5--7 of file 1. 574 575@item @var{r}d@var{l} 576Delete the lines in range @var{r} from the first file; line @var{l} is where 577they would have appeared in the second file had they not been deleted. 578For example, @samp{5,7d3} means delete lines 5--7 of file 1; or, if 579changing file 2 into file 1, append lines 5--7 of file 1 after line 3 of 580file 2. 581@end table 582 583@node Example Normal, , Detailed Normal, Normal 584@subsection An Example of Normal Format 585 586Here is the output of the command @samp{diff lao tzu} 587(@pxref{Sample diff Input}, for the complete contents of the two files). 588Notice that it shows only the lines that are different between the two 589files. 590 591@example 5921,2d0 593< The Way that can be told of is not the eternal Way; 594< The name that can be named is not the eternal name. 5954c2,3 596< The Named is the mother of all things. 597--- 598> The named is the mother of all things. 599> 60011a11,13 601> They both may be called deep and profound. 602> Deeper and more profound, 603> The door of all subtleties! 604@end example 605 606@node Context, Side by Side, Normal, Output Formats 607@section Showing Differences in Their Context 608@cindex context output format 609@cindex @samp{!} output format 610 611Usually, when you are looking at the differences between files, you will 612also want to see the parts of the files near the lines that differ, to 613help you understand exactly what has changed. These nearby parts of the 614files are called the @dfn{context}. 615 616GNU @code{diff} provides two output formats that show context around the 617differing lines: @dfn{context format} and @dfn{unified format}. It can 618optionally show in which function or section of the file the differing 619lines are found. 620 621If you are distributing new versions of files to other people in the 622form of @code{diff} output, you should use one of the output formats 623that show context so that they can apply the diffs even if they have 624made small changes of their own to the files. @code{patch} can apply 625the diffs in this case by searching in the files for the lines of 626context around the differing lines; if those lines are actually a few 627lines away from where the diff says they are, @code{patch} can adjust 628the line numbers accordingly and still apply the diff correctly. 629@xref{Imperfect}, for more information on using @code{patch} to apply 630imperfect diffs. 631 632@menu 633* Context Format:: An output format that shows surrounding lines. 634* Unified Format:: A more compact output format that shows context. 635* Sections:: Showing which sections of the files differences are in. 636* Alternate Names:: Showing alternate file names in context headers. 637@end menu 638 639@node Context Format, Unified Format, , Context 640@subsection Context Format 641 642The 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 646To select this output format, use the @samp{-C @var{lines}}, 647@samp{--context@r{[}=@var{lines}@r{]}}, or @samp{-c} option. The 648argument @var{lines} that some of these options take is the number of 649lines of context to show. If you do not specify @var{lines}, it 650defaults to three. For proper operation, @code{patch} typically needs 651at least two lines of context. 652 653@menu 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@end menu 658 659@node Detailed Context, Example Context, , Context Format 660@subsubsection Detailed Description of Context Format 661 662The context output format starts with a two-line header, which looks 663like this: 664 665@example 666*** @var{from-file} @var{from-file-modification-time} 667--- @var{to-file} @var{to-file-modification time} 668@end example 669 670@noindent 671You can change the header's content with the @samp{-L @var{label}} or 672@samp{--label=@var{label}} option; see @ref{Alternate Names}. 673 674Next come one or more hunks of differences; each hunk shows one area 675where the files differ. Context format hunks look like this: 676 677@example 678*************** 679*** @var{from-file-line-range} **** 680 @var{from-file-line} 681 @var{from-file-line}@dots{} 682--- @var{to-file-line-range} ---- 683 @var{to-file-line} 684 @var{to-file-line}@dots{} 685@end example 686 687The lines of context around the lines that differ start with two space 688characters. The lines that differ between the two files start with one 689of the following indicator characters, followed by a space character: 690 691@table @samp 692@item ! 693A line that is part of a group of one or more lines that changed between 694the two files. There is a corresponding group of lines marked with 695@samp{!} in the part of this hunk for the other file. 696 697@item + 698An ``inserted'' line in the second file that corresponds to nothing in 699the first file. 700 701@item - 702A ``deleted'' line in the first file that corresponds to nothing in the 703second file. 704@end table 705 706If all of the changes in a hunk are insertions, the lines of 707@var{from-file} are omitted. If all of the changes are deletions, the 708lines of @var{to-file} are omitted. 709 710@node Example Context, Less Context, Detailed Context, Context Format 711@subsubsection An Example of Context Format 712 713Here is the output of @samp{diff -c lao tzu} (@pxref{Sample diff Input}, 714for the complete contents of the two files). Notice that up to three 715lines that are not different are shown around each line that is 716different; they are the context lines. Also notice that the first two 717hunks have run together, because their contents overlap. 718 719@example 720*** lao Sat Jan 26 23:30:39 1991 721--- tzu Sat Jan 26 23:30:50 1991 722*************** 723*** 1,7 **** 724- The Way that can be told of is not the eternal Way; 725- The name that can be named is not the eternal name. 726 The Nameless is the origin of Heaven and Earth; 727! The Named is the mother of all things. 728 Therefore let there always be non-being, 729 so we may see their subtlety, 730 And let there always be being, 731--- 1,6 ---- 732 The Nameless is the origin of Heaven and Earth; 733! The named is the mother of all things. 734! 735 Therefore let there always be non-being, 736 so we may see their subtlety, 737 And let there always be being, 738*************** 739*** 9,11 **** 740--- 8,13 ---- 741 The two are the same, 742 But after they are produced, 743 they have different names. 744+ They both may be called deep and profound. 745+ Deeper and more profound, 746+ The door of all subtleties! 747@end example 748 749@node Less Context, , Example Context, Context Format 750@subsubsection An Example of Context Format with Less Context 751 752Here is the output of @samp{diff --context=1 lao tzu} (@pxref{Sample 753diff Input}, for the complete contents of the two files). Notice that 754at most one context line is reported here. 755 756@example 757*** lao Sat Jan 26 23:30:39 1991 758--- tzu Sat Jan 26 23:30:50 1991 759*************** 760*** 1,5 **** 761- The Way that can be told of is not the eternal Way; 762- The name that can be named is not the eternal name. 763 The Nameless is the origin of Heaven and Earth; 764! The Named is the mother of all things. 765 Therefore let there always be non-being, 766--- 1,4 ---- 767 The Nameless is the origin of Heaven and Earth; 768! The named is the mother of all things. 769! 770 Therefore let there always be non-being, 771*************** 772*** 11 **** 773--- 10,13 ---- 774 they have different names. 775+ They both may be called deep and profound. 776+ Deeper and more profound, 777+ The door of all subtleties! 778@end example 779 780@node Unified Format, Sections, Context Format, Context 781@subsection Unified Format 782@cindex unified output format 783@cindex @samp{+-} output format 784 785The unified output format is a variation on the context format that is 786more compact because it omits redundant context lines. To select this 787output format, use the @samp{-U @var{lines}}, 788@samp{--unified@r{[}=@var{lines}@r{]}}, or @samp{-u} 789option. The argument @var{lines} is the number of lines of context to 790show. When it is not given, it defaults to three. 791 792At present, only GNU @code{diff} can produce this format and only GNU 793@code{patch} can automatically apply diffs in this format. For proper 794operation, @code{patch} typically needs at least two lines of context. 795 796@menu 797* Detailed Unified:: A detailed description of unified format. 798* Example Unified:: Sample output in unified format. 799@end menu 800 801@node Detailed Unified, Example Unified, , Unified Format 802@subsubsection Detailed Description of Unified Format 803 804The unified output format starts with a two-line header, which looks 805like this: 806 807@example 808--- @var{from-file} @var{from-file-modification-time} 809+++ @var{to-file} @var{to-file-modification-time} 810@end example 811 812@noindent 813You can change the header's content with the @samp{-L @var{label}} or 814@samp{--label=@var{label}} option; see @xref{Alternate Names}. 815 816Next come one or more hunks of differences; each hunk shows one area 817where the files differ. Unified format hunks look like this: 818 819@example 820@@@@ @var{from-file-range} @var{to-file-range} @@@@ 821 @var{line-from-either-file} 822 @var{line-from-either-file}@dots{} 823@end example 824 825The lines common to both files begin with a space character. The lines 826that actually differ between the two files have one of the following 827indicator characters in the left column: 828 829@table @samp 830@item + 831A line was added here to the first file. 832 833@item - 834A line was removed here from the first file. 835@end table 836 837@node Example Unified, , Detailed Unified, Unified Format 838@subsubsection An Example of Unified Format 839 840Here is the output of the command @samp{diff -u lao tzu} 841(@pxref{Sample diff Input}, for the complete contents of the two files): 842 843@example 844--- lao Sat Jan 26 23:30:39 1991 845+++ tzu Sat Jan 26 23:30:50 1991 846@@@@ -1,7 +1,6 @@@@ 847-The Way that can be told of is not the eternal Way; 848-The name that can be named is not the eternal name. 849 The Nameless is the origin of Heaven and Earth; 850-The Named is the mother of all things. 851+The named is the mother of all things. 852+ 853 Therefore let there always be non-being, 854 so we may see their subtlety, 855 And let there always be being, 856@@@@ -9,3 +8,6 @@@@ 857 The two are the same, 858 But after they are produced, 859 they have different names. 860+They both may be called deep and profound. 861+Deeper and more profound, 862+The door of all subtleties! 863@end example 864 865@node Sections, Alternate Names, Unified Format, Context 866@subsection Showing Which Sections Differences Are in 867@cindex headings 868@cindex section headings 869 870Sometimes you might want to know which part of the files each change 871falls in. If the files are source code, this could mean which function 872was changed. If the files are documents, it could mean which chapter or 873appendix was changed. GNU @code{diff} can show this by displaying the 874nearest section heading line that precedes the differing lines. Which 875lines are ``section headings'' is determined by a regular expression. 876 877@menu 878* Specified Headings:: Showing headings that match regular expressions. 879* C Function Headings:: Showing headings of C functions. 880@end menu 881 882@node Specified Headings, C Function Headings, , Sections 883@subsubsection Showing Lines That Match Regular Expressions 884@cindex specified headings 885@cindex regular expression matching headings 886 887To show in which sections differences occur for files that are not 888source code for C or similar languages, use the @samp{-F @var{regexp}} 889or @samp{--show-function-line=@var{regexp}} option. @code{diff} 890considers lines that match the argument @var{regexp} to be the beginning 891of a section of the file. Here are suggested regular expressions for 892some common languages: 893 894@c Please add to this list, e.g. Fortran, Pascal. 895@table @samp 896@item ^[A-Za-z_] 897C, C++, Prolog 898@item ^( 899Lisp 900@item ^@@\(chapter\|appendix\|unnumbered\|chapheading\) 901Texinfo 902@end table 903 904This option does not automatically select an output format; in order to 905use it, you must select the context format (@pxref{Context Format}) or 906unified format (@pxref{Unified Format}). In other output formats it 907has no effect. 908 909The @samp{-F} and @samp{--show-function-line} options find the nearest 910unchanged line that precedes each hunk of differences and matches the 911given regular expression. Then they add that line to the end of the 912line of asterisks in the context format, or to the @samp{@@@@} line in 913unified format. If no matching line exists, they leave the output for 914that hunk unchanged. If that line is more than 40 characters long, they 915output only the first 40 characters. You can specify more than one 916regular expression for such lines; @code{diff} tries to match each line 917against each regular expression, starting with the last one given. This 918means that you can use @samp{-p} and @samp{-F} together, if you wish. 919 920@node C Function Headings, , Specified Headings, Sections 921@subsubsection Showing C Function Headings 922@cindex C function headings 923@cindex function headings, C 924 925To show in which functions differences occur for C and similar 926languages, you can use the @samp{-p} or @samp{--show-c-function} option. 927This option automatically defaults to the context output format 928(@pxref{Context Format}), with the default number of lines of context. 929You can override that number with @samp{-C @var{lines}} elsewhere in the 930command line. You can override both the format and the number with 931@samp{-U @var{lines}} elsewhere in the command line. 932 933The @samp{-p} and @samp{--show-c-function} options are equivalent to 934@samp{-F'^[_a-zA-Z$]'} if the unified format is specified, otherwise 935@samp{-c -F'^[_a-zA-Z$]'} (@pxref{Specified Headings}). GNU @code{diff} 936provides them for the sake of convenience. 937 938@node Alternate Names, , Sections, Context 939@subsection Showing Alternate File Names 940@cindex alternate file names 941@cindex file name alternates 942 943If you are comparing two files that have meaningless or uninformative 944names, you might want @code{diff} to show alternate names in the header 945of the context and unified output formats. To do this, use the @samp{-L 946@var{label}} or @samp{--label=@var{label}} option. The first time 947you give this option, its argument replaces the name and date of the 948first file in the header; the second time, its argument replaces the 949name and date of the second file. If you give this option more than 950twice, @code{diff} reports an error. The @samp{-L} option does not 951affect the file names in the @code{pr} header when the @samp{-l} or 952@samp{--paginate} option is used (@pxref{Pagination}). 953 954Here are the first two lines of the output from @samp{diff -C2 955-Loriginal -Lmodified lao tzu}: 956 957@example 958*** original 959--- modified 960@end example 961 962@node Side by Side, Scripts, Context, Output Formats 963@section Showing Differences Side by Side 964@cindex side by side 965@cindex two-column output 966@cindex columnar output 967 968@code{diff} can produce a side by side difference listing of two files. 969The files are listed in two columns with a gutter between them. The 970gutter contains one of the following markers: 971 972@table @asis 973@item white space 974The corresponding lines are in common. That is, either the lines are 975identical, or the difference is ignored because of one of the 976@samp{--ignore} options (@pxref{White Space}). 977 978@item @samp{|} 979The corresponding lines differ, and they are either both complete 980or both incomplete. 981 982@item @samp{<} 983The files differ and only the first file contains the line. 984 985@item @samp{>} 986The files differ and only the second file contains the line. 987 988@item @samp{(} 989Only the first file contains the line, but the difference is ignored. 990 991@item @samp{)} 992Only the second file contains the line, but the difference is ignored. 993 994@item @samp{\} 995The corresponding lines differ, and only the first line is incomplete. 996 997@item @samp{/} 998The corresponding lines differ, and only the second line is incomplete. 999@end table 1000 1001Normally, an output line is incomplete if and only if the lines that it 1002contains are incomplete; @xref{Incomplete Lines}. However, when an 1003output line represents two differing lines, one might be incomplete 1004while the other is not. In this case, the output line is complete, 1005but its the gutter is marked @samp{\} if the first line is incomplete, 1006@samp{/} if the second line is. 1007 1008Side by side format is sometimes easiest to read, but it has limitations. 1009It generates much wider output than usual, and truncates lines that are 1010too long to fit. Also, it relies on lining up output more heavily than 1011usual, so its output looks particularly bad if you use varying 1012width fonts, nonstandard tab stops, or nonprinting characters. 1013 1014You can use the @code{sdiff} command to interactively merge side by side 1015differences. @xref{Interactive Merging}, for more information on merging files. 1016 1017@menu 1018* Side by Side Format:: Controlling side by side output format. 1019* Example Side by Side:: Sample side by side output. 1020@end menu 1021 1022@node Side by Side Format, Example Side by Side, , Side by Side 1023@section Controlling Side by Side Format 1024@cindex side by side format 1025 1026The @samp{-y} or @samp{--side-by-side} option selects side by side 1027format. Because side by side output lines contain two input lines, they 1028are wider than usual. They are normally 130 columns, which can fit onto 1029a traditional printer line. You can set the length of output lines with 1030the @samp{-W @var{columns}} or @samp{--width=@var{columns}} option. The 1031output line is split into two halves of equal length, separated by a 1032small gutter to mark differences; the right half is aligned to a tab 1033stop so that tabs line up. Input lines that are too long to fit in half 1034of an output line are truncated for output. 1035 1036The @samp{--left-column} option prints only the left column of two 1037common lines. The @samp{--suppress-common-lines} option suppresses 1038common lines entirely. 1039 1040@node Example Side by Side, , Side by Side Format, Side by Side 1041@subsection An Example of Side by Side Format 1042 1043Here is the output of the command @samp{diff -y -W 72 lao tzu} 1044(@pxref{Sample diff Input}, for the complete contents of the two files). 1045 1046@example 1047The Way that can be told of is n < 1048The name that can be named is no < 1049The Nameless is the origin of He The Nameless is the origin of He 1050The Named is the mother of all t | The named is the mother of all t 1051 > 1052Therefore let there always be no Therefore let there always be no 1053 so we may see their subtlety, so we may see their subtlety, 1054And let there always be being, And let there always be being, 1055 so we may see their outcome. so we may see their outcome. 1056The two are the same, The two are the same, 1057But after they are produced, But after they are produced, 1058 they have different names. they have different names. 1059 > They both may be called deep and 1060 > Deeper and more profound, 1061 > The door of all subtleties! 1062@end example 1063 1064@node Scripts, If-then-else, Side by Side, Output Formats 1065@section Making Edit Scripts 1066@cindex script output formats 1067 1068Several output modes produce command scripts for editing @var{from-file} 1069to produce @var{to-file}. 1070 1071@menu 1072* ed Scripts:: Using @code{diff} to produce commands for @code{ed}. 1073* Forward ed:: Making forward @code{ed} scripts. 1074* RCS:: A special @code{diff} output format used by RCS. 1075@end menu 1076 1077@node ed Scripts, Forward ed, , Scripts 1078@subsection @code{ed} Scripts 1079@cindex @code{ed} script output format 1080 1081@code{diff} can produce commands that direct the @code{ed} text editor 1082to change the first file into the second file. Long ago, this was the 1083only output mode that was suitable for editing one file into another 1084automatically; today, with @code{patch}, it is almost obsolete. Use the 1085@samp{-e} or @samp{--ed} option to select this output format. 1086 1087Like the normal format (@pxref{Normal}), this output format does not 1088show any context; unlike the normal format, it does not include the 1089information necessary to apply the diff in reverse (to produce the first 1090file if all you have is the second file and the diff). 1091 1092If the file @file{d} contains the output of @samp{diff -e old new}, then 1093the command @samp{(cat d && echo w) | ed - old} edits @file{old} to make 1094it a copy of @file{new}. More generally, if @file{d1}, @file{d2}, 1095@dots{}, @file{dN} contain the outputs of @samp{diff -e old new1}, 1096@samp{diff -e new1 new2}, @dots{}, @samp{diff -e newN-1 newN}, 1097respectively, then the command @samp{(cat d1 d2 @dots{} dN && echo w) | 1098ed - old} edits @file{old} to make it a copy of @file{newN}. 1099 1100@menu 1101* Detailed ed:: A detailed description of @code{ed} format. 1102* Example ed:: A sample @code{ed} script. 1103@end menu 1104 1105@node Detailed ed, Example ed, , ed Scripts 1106@subsubsection Detailed Description of @code{ed} Format 1107 1108The @code{ed} output format consists of one or more hunks of 1109differences. The changes closest to the ends of the files come first so 1110that commands that change the number of lines do not affect how 1111@code{ed} interprets line numbers in succeeding commands. @code{ed} 1112format hunks look like this: 1113 1114@example 1115@var{change-command} 1116@var{to-file-line} 1117@var{to-file-line}@dots{} 1118. 1119@end example 1120 1121Because @code{ed} uses a single period on a line to indicate the end of 1122input, GNU @code{diff} protects lines of changes that contain a single 1123period on a line by writing two periods instead, then writing a 1124subsequent @code{ed} command to change the two periods into one. The 1125@code{ed} format cannot represent an incomplete line, so if the second 1126file ends in a changed incomplete line, @code{diff} reports an error and 1127then pretends that a newline was appended. 1128 1129There are three types of change commands. Each consists of a line 1130number or comma-separated range of lines in the first file and a single 1131character indicating the kind of change to make. All line numbers are 1132the original line numbers in the file. The types of change commands 1133are: 1134 1135@table @samp 1136@item @var{l}a 1137Add text from the second file after line @var{l} in the first file. For 1138example, @samp{8a} means to add the following lines after line 8 of file 11391. 1140 1141@item @var{r}c 1142Replace the lines in range @var{r} in the first file with the following 1143lines. Like a combined add and delete, but more compact. For example, 1144@samp{5,7c} means change lines 5--7 of file 1 to read as the text file 11452. 1146 1147@item @var{r}d 1148Delete the lines in range @var{r} from the first file. For example, 1149@samp{5,7d} means delete lines 5--7 of file 1. 1150@end table 1151 1152@node Example ed, , Detailed ed, ed Scripts 1153@subsubsection Example @code{ed} Script 1154 1155Here is the output of @samp{diff -e lao tzu} (@pxref{Sample 1156diff Input}, for the complete contents of the two files): 1157 1158@example 115911a 1160They both may be called deep and profound. 1161Deeper and more profound, 1162The door of all subtleties! 1163. 11644c 1165The named is the mother of all things. 1166 1167. 11681,2d 1169@end example 1170 1171@node Forward ed, RCS, ed Scripts, Scripts 1172@subsection Forward @code{ed} Scripts 1173@cindex forward @code{ed} script output format 1174 1175@code{diff} can produce output that is like an @code{ed} script, but 1176with hunks in forward (front to back) order. The format of the commands 1177is also changed slightly: command characters precede the lines they 1178modify, spaces separate line numbers in ranges, and no attempt is made 1179to disambiguate hunk lines consisting of a single period. Like 1180@code{ed} format, forward @code{ed} format cannot represent incomplete 1181lines. 1182 1183Forward @code{ed} format is not very useful, because neither @code{ed} 1184nor @code{patch} can apply diffs in this format. It exists mainly for 1185compatibility with older versions of @code{diff}. Use the @samp{-f} or 1186@samp{--forward-ed} option to select it. 1187 1188@node RCS, , Forward ed, Scripts 1189@subsection RCS Scripts 1190@cindex RCS script output format 1191 1192The RCS output format is designed specifically for use by the Revision 1193Control System, which is a set of free programs used for organizing 1194different versions and systems of files. Use the @samp{-n} or 1195@samp{--rcs} option to select this output format. It is like the 1196forward @code{ed} format (@pxref{Forward ed}), but it can represent 1197arbitrary changes to the contents of a file because it avoids the 1198forward @code{ed} format's problems with lines consisting of a single 1199period and with incomplete lines. Instead of ending text sections with 1200a line consisting of a single period, each command specifies the number 1201of lines it affects; a combination of the @samp{a} and @samp{d} 1202commands are used instead of @samp{c}. Also, if the second file ends 1203in a changed incomplete line, then the output also ends in an 1204incomplete line. 1205 1206Here is the output of @samp{diff -n lao tzu} (@pxref{Sample 1207diff Input}, for the complete contents of the two files): 1208 1209@example 1210d1 2 1211d4 1 1212a4 2 1213The named is the mother of all things. 1214 1215a11 3 1216They both may be called deep and profound. 1217Deeper and more profound, 1218The door of all subtleties! 1219@end example 1220 1221@node If-then-else, , Scripts, Output Formats 1222@section Merging Files with If-then-else 1223@cindex merged output format 1224@cindex if-then-else output format 1225@cindex C if-then-else output format 1226@cindex @code{ifdef} output format 1227 1228You can use @code{diff} to merge two files of C source code. The output 1229of @code{diff} in this format contains all the lines of both files. 1230Lines common to both files are output just once; the differing parts are 1231separated by the C preprocessor directives @code{#ifdef @var{name}} or 1232@code{#ifndef @var{name}}, @code{#else}, and @code{#endif}. When 1233compiling the output, you select which version to use by either defining 1234or leaving undefined the macro @var{name}. 1235 1236To merge two files, use @code{diff} with the @samp{-D @var{name}} or 1237@samp{--ifdef=@var{name}} option. The argument @var{name} is the C 1238preprocessor identifier to use in the @code{#ifdef} and @code{#ifndef} 1239directives. 1240 1241For example, if you change an instance of @code{wait (&s)} to 1242@code{waitpid (-1, &s, 0)} and then merge the old and new files with 1243the @samp{--ifdef=HAVE_WAITPID} option, then the affected part of your code 1244might look like this: 1245 1246@example 1247 do @{ 1248#ifndef HAVE_WAITPID 1249 if ((w = wait (&s)) < 0 && errno != EINTR) 1250#else /* HAVE_WAITPID */ 1251 if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR) 1252#endif /* HAVE_WAITPID */ 1253 return w; 1254 @} while (w != child); 1255@end example 1256 1257You can specify formats for languages other than C by using line group 1258formats and line formats, as described in the next sections. 1259 1260@menu 1261* Line Group Formats:: Formats for general if-then-else line groups. 1262* Line Formats:: Formats for each line in a line group. 1263* Detailed If-then-else:: A detailed description of if-then-else format. 1264* Example If-then-else:: Sample if-then-else format output. 1265@end menu 1266 1267@node Line Group Formats, Line Formats, , If-then-else 1268@subsection Line Group Formats 1269@cindex line group formats 1270@cindex formats for if-then-else line groups 1271 1272Line group formats let you specify formats suitable for many 1273applications that allow if-then-else input, including programming 1274languages and text formatting languages. A line group format specifies 1275the output format for a contiguous group of similar lines. 1276 1277For example, the following command compares the TeX files @file{old} 1278and @file{new}, and outputs a merged file in which old regions are 1279surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 1280regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 1281 1282@example 1283diff \ 1284 --old-group-format='\begin@{em@} 1285%<\end@{em@} 1286' \ 1287 --new-group-format='\begin@{bf@} 1288%>\end@{bf@} 1289' \ 1290 old new 1291@end example 1292 1293The following command is equivalent to the above example, but it is a 1294little more verbose, because it spells out the default line group formats. 1295 1296@example 1297diff \ 1298 --old-group-format='\begin@{em@} 1299%<\end@{em@} 1300' \ 1301 --new-group-format='\begin@{bf@} 1302%>\end@{bf@} 1303' \ 1304 --unchanged-group-format='%=' \ 1305 --changed-group-format='\begin@{em@} 1306%<\end@{em@} 1307\begin@{bf@} 1308%>\end@{bf@} 1309' \ 1310 old new 1311@end example 1312 1313Here is a more advanced example, which outputs a diff listing with 1314headers containing line numbers in a ``plain English'' style. 1315 1316@example 1317diff \ 1318 --unchanged-group-format='' \ 1319 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 1320%<' \ 1321 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 1322%>' \ 1323 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 1324%<-------- to: 1325%>' \ 1326 old new 1327@end example 1328 1329To specify a line group format, use @code{diff} with one of the options 1330listed below. You can specify up to four line group formats, one for 1331each kind of line group. You should quote @var{format}, because it 1332typically contains shell metacharacters. 1333 1334@table @samp 1335@item --old-group-format=@var{format} 1336These line groups are hunks containing only lines from the first file. 1337The default old group format is the same as the changed group format if 1338it is specified; otherwise it is a format that outputs the line group as-is. 1339 1340@item --new-group-format=@var{format} 1341These line groups are hunks containing only lines from the second 1342file. The default new group format is same as the the changed group 1343format if it is specified; otherwise it is a format that outputs the 1344line group as-is. 1345 1346@item --changed-group-format=@var{format} 1347These line groups are hunks containing lines from both files. The 1348default changed group format is the concatenation of the old and new 1349group formats. 1350 1351@item --unchanged-group-format=@var{format} 1352These line groups contain lines common to both files. The default 1353unchanged group format is a format that outputs the line group as-is. 1354@end table 1355 1356In a line group format, ordinary characters represent themselves; 1357conversion specifications start with @samp{%} and have one of the 1358following forms. 1359 1360@table @samp 1361@item %< 1362stands for the lines from the first file, including the trailing newline. 1363Each line is formatted according to the old line format (@pxref{Line Formats}). 1364 1365@item %> 1366stands for the lines from the second file, including the trailing newline. 1367Each line is formatted according to the new line format. 1368 1369@item %= 1370stands for the lines common to both files, including the trailing newline. 1371Each line is formatted according to the unchanged line format. 1372 1373@item %% 1374stands for @samp{%}. 1375 1376@item %c'@var{C}' 1377where @var{C} is a single character, stands for @var{C}. 1378@var{C} may not be a backslash or an apostrophe. 1379For example, @samp{%c':'} stands for a colon, even inside 1380the then-part of an if-then-else format, which a colon would 1381normally terminate. 1382 1383@item %c'\@var{O}' 1384where @var{O} is a string of 1, 2, or 3 octal digits, 1385stands for the character with octal code @var{O}. 1386For example, @samp{%c'\0'} stands for a null character. 1387 1388@item @var{F}@var{n} 1389where @var{F} is a @code{printf} conversion specification and @var{n} is one 1390of the following letters, stands for @var{n}'s value formatted with @var{F}. 1391 1392@table @samp 1393@item e 1394The line number of the line just before the group in the old file. 1395 1396@item f 1397The line number of the first line in the group in the old file; 1398equals @var{e} + 1. 1399 1400@item l 1401The line number of the last line in the group in the old file. 1402 1403@item m 1404The line number of the line just after the group in the old file; 1405equals @var{l} + 1. 1406 1407@item n 1408The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 1409 1410@item E, F, L, M, N 1411Likewise, for lines in the new file. 1412 1413@end table 1414 1415The @code{printf} conversion specification can be @samp{%d}, 1416@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 1417lower case hexadecimal, or upper case hexadecimal output 1418respectively. After the @samp{%} the following options can appear in 1419sequence: a @samp{-} specifying left-justification; an integer 1420specifying the minimum field width; and a period followed by an 1421optional integer specifying the minimum number of digits. 1422For example, @samp{%5dN} prints the number of new lines in the group 1423in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 1424 1425@item (@var{A}=@var{B}?@var{T}:@var{E}) 1426If @var{A} equals @var{B} then @var{T} else @var{E}. 1427@var{A} and @var{B} are each either a decimal constant 1428or a single letter interpreted as above. 1429This format spec is equivalent to @var{T} if 1430@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 1431 1432For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 1433@samp{no lines} if @var{N} (the number of lines in the group in the the 1434new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 1435otherwise. 1436@end table 1437 1438@node Line Formats, Detailed If-then-else, Line Group Formats, If-then-else 1439@subsection Line Formats 1440@cindex line formats 1441 1442Line formats control how each line taken from an input file is 1443output as part of a line group in if-then-else format. 1444 1445For example, the following command outputs text with a one-column 1446change indicator to the left of the text. The first column of output 1447is @samp{-} for deleted lines, @samp{|} for added lines, and a space 1448for unchanged lines. The formats contain newline characters where 1449newlines are desired on output. 1450 1451@example 1452diff \ 1453 --old-line-format='-%l 1454' \ 1455 --new-line-format='|%l 1456' \ 1457 --unchanged-line-format=' %l 1458' \ 1459 old new 1460@end example 1461 1462To specify a line format, use one of the following options. You should 1463quote @var{format}, since it often contains shell metacharacters. 1464 1465@table @samp 1466@item --old-line-format=@var{format} 1467formats lines just from the first file. 1468 1469@item --new-line-format=@var{format} 1470formats lines just from the second file. 1471 1472@item --unchanged-line-format=@var{format} 1473formats lines common to both files. 1474 1475@item --line-format=@var{format} 1476formats all lines; in effect, it sets all three above options simultaneously. 1477@end table 1478 1479In a line format, ordinary characters represent themselves; 1480conversion specifications start with @samp{%} and have one of the 1481following forms. 1482 1483@table @samp 1484@item %l 1485stands for the the contents of the line, not counting its trailing 1486newline (if any). This format ignores whether the line is incomplete; 1487@xref{Incomplete Lines}. 1488 1489@item %L 1490stands for the the contents of the line, including its trailing newline 1491(if any). If a line is incomplete, this format preserves its 1492incompleteness. 1493 1494@item %% 1495stands for @samp{%}. 1496 1497@item %c'@var{C}' 1498where @var{C} is a single character, stands for @var{C}. 1499@var{C} may not be a backslash or an apostrophe. 1500For example, @samp{%c':'} stands for a colon. 1501 1502@item %c'\@var{O}' 1503where @var{O} is a string of 1, 2, or 3 octal digits, 1504stands for the character with octal code @var{O}. 1505For example, @samp{%c'\0'} stands for a null character. 1506 1507@item @var{F}n 1508where @var{F} is a @code{printf} conversion specification, 1509stands for the line number formatted with @var{F}. 1510For example, @samp{%.5dn} prints the line number using the 1511@code{printf} format @code{"%.5d"}. @xref{Line Group Formats}, for 1512more about printf conversion specifications. 1513 1514@end table 1515 1516The default line format is @samp{%l} followed by a newline character. 1517 1518If the input contains tab characters and it is important that they line 1519up on output, you should ensure that @samp{%l} or @samp{%L} in a line 1520format is just after a tab stop (e.g.@: by preceding @samp{%l} or 1521@samp{%L} with a tab character), or you should use the @samp{-t} or 1522@samp{--expand-tabs} option. 1523 1524Taken together, the line and line group formats let you specify many 1525different formats. For example, the following command uses a format 1526similar to @code{diff}'s normal format. You can tailor this command 1527to get fine control over @code{diff}'s output. 1528 1529@example 1530diff \ 1531 --old-line-format='< %l 1532' \ 1533 --new-line-format='> %l 1534' \ 1535 --old-group-format='%df%(f=l?:,%dl)d%dE 1536%<' \ 1537 --new-group-format='%dea%dF%(F=L?:,%dL) 1538%>' \ 1539 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 1540%<--- 1541%>' \ 1542 --unchanged-group-format='' \ 1543 old new 1544@end example 1545 1546@node Detailed If-then-else, Example If-then-else, Line Formats, If-then-else 1547@subsection Detailed Description of If-then-else Format 1548 1549For lines common to both files, @code{diff} uses the unchanged line 1550group format. For each hunk of differences in the merged output 1551format, if the hunk contains only lines from the first file, 1552@code{diff} uses the old line group format; if the hunk contains only 1553lines from the second file, @code{diff} uses the new group format; 1554otherwise, @code{diff} uses the changed group format. 1555 1556The old, new, and unchanged line formats specify the output format of 1557lines from the first file, lines from the second file, and lines common 1558to both files, respectively. 1559 1560The option @samp{--ifdef=@var{name}} is equivalent to 1561the following sequence of options using shell syntax: 1562 1563@example 1564--old-group-format='#ifndef @var{name} 1565%<#endif /* not @var{name} */ 1566' \ 1567--new-group-format='#ifdef @var{name} 1568%>#endif /* @var{name} */ 1569' \ 1570--unchanged-group-format='%=' \ 1571--changed-group-format='#ifndef @var{name} 1572%<#else /* @var{name} */ 1573%>#endif /* @var{name} */ 1574' 1575@end example 1576 1577You should carefully check the @code{diff} output for proper nesting. 1578For example, when using the the @samp{-D @var{name}} or 1579@samp{--ifdef=@var{name}} option, you should check that if the 1580differing lines contain any of the C preprocessor directives 1581@samp{#ifdef}, @samp{#ifndef}, @samp{#else}, @samp{#elif}, or 1582@samp{#endif}, they are nested properly and match. If they don't, you 1583must make corrections manually. It is a good idea to carefully check 1584the resulting code anyway to make sure that it really does what you 1585want it to; depending on how the input files were produced, the output 1586might contain duplicate or otherwise incorrect code. 1587 1588The @code{patch} @samp{-D @var{name}} option behaves just like 1589the @code{diff} @samp{-D @var{name}} option, except it operates on 1590a file and a diff to produce a merged file; @xref{patch Options}. 1591 1592@node Example If-then-else, , Detailed If-then-else, If-then-else 1593@subsection An Example of If-then-else Format 1594 1595Here is the output of @samp{diff -DTWO lao tzu} (@pxref{Sample 1596diff Input}, for the complete contents of the two files): 1597 1598@example 1599#ifndef TWO 1600The Way that can be told of is not the eternal Way; 1601The name that can be named is not the eternal name. 1602#endif /* not TWO */ 1603The Nameless is the origin of Heaven and Earth; 1604#ifndef TWO 1605The Named is the mother of all things. 1606#else /* TWO */ 1607The named is the mother of all things. 1608 1609#endif /* TWO */ 1610Therefore let there always be non-being, 1611 so we may see their subtlety, 1612And let there always be being, 1613 so we may see their outcome. 1614The two are the same, 1615But after they are produced, 1616 they have different names. 1617#ifdef TWO 1618They both may be called deep and profound. 1619Deeper and more profound, 1620The door of all subtleties! 1621#endif /* TWO */ 1622@end example 1623 1624@node Comparing Directories, Adjusting Output, Output Formats, Top 1625@chapter Comparing Directories 1626 1627You can use @code{diff} to compare some or all of the files in two 1628directory trees. When both file name arguments to @code{diff} are 1629directories, it compares each file that is contained in both 1630directories, examining file names in alphabetical order. Normally 1631@code{diff} is silent about pairs of files that contain no differences, 1632but if you use the @samp{-s} or @samp{--report-identical-files} option, 1633it reports pairs of identical files. Normally @code{diff} reports 1634subdirectories common to both directories without comparing 1635subdirectories' files, but if you use the @samp{-r} or 1636@samp{--recursive} option, it compares every corresponding pair of files 1637in the directory trees, as many levels deep as they go. 1638 1639For file names that are in only one of the directories, @code{diff} 1640normally does not show the contents of the file that exists; it reports 1641only that the file exists in that directory and not in the other. You 1642can make @code{diff} act as though the file existed but was empty in the 1643other directory, so that it outputs the entire contents of the file that 1644actually exists. (It is output as either an insertion or a 1645deletion, depending on whether it is in the first or the second 1646directory given.) To do this, use the @samp{-N} or @samp{--new-file} 1647option. 1648 1649If the older directory contains one or more large files that are not in 1650the newer directory, you can make the patch smaller by using the 1651@samp{-P} or @samp{--unidirectional-new-file} option instead of @samp{-N}. 1652This option is like @samp{-N} except that it only inserts the contents 1653of files that appear in the second directory but not the first (that is, 1654files that were added). At the top of the patch, write instructions for 1655the user applying the patch to remove the files that were deleted before 1656applying the patch. @xref{Making Patches}, for more discussion of 1657making patches for distribution. 1658 1659To ignore some files while comparing directories, use the @samp{-x 1660@var{pattern}} or @samp{--exclude=@var{pattern}} option. This option 1661ignores any files or subdirectories whose base names match the shell 1662pattern @var{pattern}. Unlike in the shell, a period at the start of 1663the base of a file name matches a wildcard at the start of a pattern. 1664You should enclose @var{pattern} in quotes so that the shell does not 1665expand it. For example, the option @samp{-x '*.[ao]'} ignores any file 1666whose name ends with @samp{.a} or @samp{.o}. 1667 1668This option accumulates if you specify it more than once. For example, 1669using the options @samp{-x 'RCS' -x '*,v'} ignores any file or 1670subdirectory whose base name is @samp{RCS} or ends with @samp{,v}. 1671 1672If you need to give this option many times, you can instead put the 1673patterns in a file, one pattern per line, and use the @samp{-X 1674@var{file}} or @samp{--exclude-from=@var{file}} option. 1675 1676If you have been comparing two directories and stopped partway through, 1677later you might want to continue where you left off. You can do this by 1678using the @samp{-S @var{file}} or @samp{--starting-file=@var{file}} 1679option. This compares only the file @var{file} and all alphabetically 1680later files in the topmost directory level. 1681 1682@node Adjusting Output, diff Performance, Comparing Directories, Top 1683@chapter Making @code{diff} Output Prettier 1684 1685@code{diff} provides several ways to adjust the appearance of its output. 1686These adjustments can be applied to any output format. 1687 1688@menu 1689* Tabs:: Preserving the alignment of tabstops. 1690* Pagination:: Page numbering and timestamping @code{diff} output. 1691@end menu 1692 1693@node Tabs, Pagination, , Adjusting Output 1694@section Preserving Tabstop Alignment 1695@cindex tabstop alignment 1696@cindex aligning tabstops 1697 1698The lines of text in some of the @code{diff} output formats are preceded 1699by one or two characters that indicate whether the text is inserted, 1700deleted, or changed. The addition of those characters can cause tabs to 1701move to the next tabstop, throwing off the alignment of columns in the 1702line. GNU @code{diff} provides two ways to make tab-aligned columns 1703line up correctly. 1704 1705The first way is to have @code{diff} convert all tabs into the correct 1706number of spaces before outputting them; select this method with the 1707@samp{-t} or @samp{--expand-tabs} option. @code{diff} assumes that 1708tabstops are set every 8 columns. To use this form of output with 1709@code{patch}, you must give @code{patch} the @samp{-l} or 1710@samp{--ignore-white-space} option (@pxref{Changed White Space}, for more 1711information). 1712 1713The other method for making tabs line up correctly is to add a tab 1714character instead of a space after the indicator character at the 1715beginning of the line. This ensures that all following tab characters 1716are in the same position relative to tabstops that they were in the 1717original files, so that the output is aligned correctly. Its 1718disadvantage is that it can make long lines too long to fit on one line 1719of the screen or the paper. It also does not work with the unified 1720output format, which does not have a space character after the change 1721type indicator character. Select this method with the @samp{-T} or 1722@samp{--initial-tab} option. 1723 1724@node Pagination, , Tabs, Adjusting Output 1725@section Paginating @code{diff} Output 1726@cindex paginating @code{diff} output 1727 1728It can be convenient to have long output page-numbered and time-stamped. 1729The @samp{-l} and @samp{--paginate} options do this by sending the 1730@code{diff} output through the @code{pr} program. Here is what the page 1731header might look like for @samp{diff -lc lao tzu}: 1732 1733@example 1734Mar 11 13:37 1991 diff -lc lao tzu Page 1 1735@end example 1736 1737@node diff Performance, Comparing Three Files, Adjusting Output, Top 1738@chapter @code{diff} Performance Tradeoffs 1739@cindex performance of @code{diff} 1740 1741GNU @code{diff} runs quite efficiently; however, in some circumstances 1742you can cause it to run faster or produce a more compact set of changes. 1743There are two ways that you can affect the performance of GNU 1744@code{diff} by changing the way it compares files. 1745 1746Performance has more than one dimension. These options improve one 1747aspect of performance at the cost of another, or they improve 1748performance in some cases while hurting it in others. 1749 1750The way that GNU @code{diff} determines which lines have changed always 1751comes up with a near-minimal set of differences. Usually it is good 1752enough for practical purposes. If the @code{diff} output is large, you 1753might want @code{diff} to use a modified algorithm that sometimes 1754produces a smaller set of differences. The @samp{-d} or 1755@samp{--minimal} option does this; however, it can also cause 1756@code{diff} to run more slowly than usual, so it is not the default 1757behavior. 1758 1759When the files you are comparing are large and have small groups of 1760changes scattered throughout them, you can use the @samp{-H} or 1761@samp{--speed-large-files} option to make a different modification to 1762the algorithm that @code{diff} uses. If the input files have a constant 1763small density of changes, this option speeds up the comparisons without 1764changing the output. If not, @code{diff} might produce a larger set of 1765differences; however, the output will still be correct. 1766 1767Normally @code{diff} discards the prefix and suffix that is common to 1768both files before it attempts to find a minimal set of differences. 1769This makes @code{diff} run faster, but occasionally it may produce 1770non-minimal output. The @samp{--horizon-lines=@var{lines}} option 1771prevents @code{diff} from discarding the last @var{lines} lines of the 1772prefix and the first @var{lines} lines of the suffix. This gives 1773@code{diff} further opportunities to find a minimal output. 1774 1775@node Comparing Three Files, diff3 Merging, diff Performance, Top 1776@chapter Comparing Three Files 1777@cindex comparing three files 1778@cindex format of @code{diff3} output 1779 1780Use the program @code{diff3} to compare three files and show any 1781differences among them. (@code{diff3} can also merge files; see 1782@ref{diff3 Merging}). 1783 1784The ``normal'' @code{diff3} output format shows each hunk of 1785differences without surrounding context. Hunks are labeled depending 1786on whether they are two-way or three-way, and lines are annotated by 1787their location in the input files. 1788 1789@xref{Invoking diff3}, for more information on how to run @code{diff3}. 1790 1791@menu 1792* Sample diff3 Input:: Sample @code{diff3} input for examples. 1793* Detailed diff3 Normal:: A detailed description of normal output format. 1794* diff3 Hunks:: The format of normal output format. 1795* Example diff3 Normal:: Sample output in the normal format. 1796@end menu 1797 1798@node Sample diff3 Input, Detailed diff3 Normal, , Comparing Three Files 1799@section A Third Sample Input File 1800@cindex @code{diff3} sample input 1801@cindex sample input for @code{diff3} 1802 1803Here is a third sample file that will be used in examples to illustrate 1804the output of @code{diff3} and how various options can change it. The 1805first two files are the same that we used for @code{diff} (@pxref{Sample 1806diff Input}). This is the third sample file, called @file{tao}: 1807 1808@example 1809The Way that can be told of is not the eternal Way; 1810The name that can be named is not the eternal name. 1811The Nameless is the origin of Heaven and Earth; 1812The named is the mother of all things. 1813 1814Therefore let there always be non-being, 1815 so we may see their subtlety, 1816And let there always be being, 1817 so we may see their result. 1818The two are the same, 1819But after they are produced, 1820 they have different names. 1821 1822 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 1823@end example 1824 1825@node Detailed diff3 Normal, diff3 Hunks, Sample diff3 Input, Comparing Three Files 1826@section Detailed Description of @code{diff3} Normal Format 1827 1828Each hunk begins with a line marked @samp{====}. Three-way hunks have 1829plain @samp{====} lines, and two-way hunks have @samp{1}, @samp{2}, or 1830@samp{3} appended to specify which of the three input files differ in 1831that hunk. The hunks contain copies of two or three sets of input 1832lines each preceded by one or two commands identifying where the lines 1833came from. 1834 1835Normally, two spaces precede each copy of an input line to distinguish 1836it from the commands. But with the @samp{-T} or @samp{--initial-tab} 1837option, @code{diff3} uses a tab instead of two spaces; this lines up 1838tabs correctly. @xref{Tabs}, for more information. 1839 1840Commands take the following forms: 1841 1842@table @samp 1843@item @var{file}:@var{l}a 1844This hunk appears after line @var{l} of file @var{file}, and 1845contains no lines in that file. To edit this file to yield the other 1846files, one must append hunk lines taken from the other files. For 1847example, @samp{1:11a} means that the hunk follows line 11 in the first 1848file and contains no lines from that file. 1849 1850@item @var{file}:@var{r}c 1851This hunk contains the lines in the range @var{r} of file @var{file}. 1852The range @var{r} is a comma-separated pair of line numbers, or just one 1853number if the range is a singleton. To edit this file to yield the 1854other files, one must change the specified lines to be the lines taken 1855from the other files. For example, @samp{2:11,13c} means that the hunk 1856contains lines 11 through 13 from the second file. 1857@end table 1858 1859If the last line in a set of input lines is incomplete 1860(@pxref{Incomplete Lines}), it is distinguished on output from a full 1861line by a following line that starts with @samp{\}. 1862 1863@node diff3 Hunks, Example diff3 Normal, Detailed diff3 Normal, Comparing Three Files 1864@section @code{diff3} Hunks 1865@cindex hunks for @code{diff3} 1866@cindex @code{diff3} hunks 1867 1868Groups of lines that differ in two or three of the input files are 1869called @dfn{diff3 hunks}, by analogy with @code{diff} hunks 1870(@pxref{Hunks}). If all three input files differ in a @code{diff3} 1871hunk, the hunk is called a @dfn{three-way hunk}; if just two input files 1872differ, it is a @dfn{two-way hunk}. 1873 1874As with @code{diff}, several solutions are possible. When comparing the 1875files @samp{A}, @samp{B}, and @samp{C}, @code{diff3} normally finds 1876@code{diff3} hunks by merging the two-way hunks output by the two 1877commands @samp{diff A B} and @samp{diff A C}. This does not necessarily 1878minimize the size of the output, but exceptions should be rare. 1879 1880For example, suppose @file{F} contains the three lines @samp{a}, 1881@samp{b}, @samp{f}, @file{G} contains the lines @samp{g}, @samp{b}, 1882@samp{g}, and @file{H} contains the lines @samp{a}, @samp{b}, 1883@samp{h}. @samp{diff3 F G H} might output the following: 1884 1885@example 1886====2 18871:1c 18883:1c 1889 a 18902:1c 1891 g 1892==== 18931:3c 1894 f 18952:3c 1896 g 18973:3c 1898 h 1899@end example 1900 1901@noindent 1902because it found a two-way hunk containing @samp{a} in the first and 1903third files and @samp{g} in the second file, then the single line 1904@samp{b} common to all three files, then a three-way hunk containing 1905the last line of each file. 1906 1907@node Example diff3 Normal, , diff3 Hunks, Comparing Three Files 1908@section An Example of @code{diff3} Normal Format 1909 1910Here is the output of the command @samp{diff3 lao tzu tao} 1911(@pxref{Sample diff3 Input}, for the complete contents of the files). 1912Notice that it shows only the lines that are different among the three 1913files. 1914 1915@example 1916====2 19171:1,2c 19183:1,2c 1919 The Way that can be told of is not the eternal Way; 1920 The name that can be named is not the eternal name. 19212:0a 1922====1 19231:4c 1924 The Named is the mother of all things. 19252:2,3c 19263:4,5c 1927 The named is the mother of all things. 1928 1929====3 19301:8c 19312:7c 1932 so we may see their outcome. 19333:9c 1934 so we may see their result. 1935==== 19361:11a 19372:11,13c 1938 They both may be called deep and profound. 1939 Deeper and more profound, 1940 The door of all subtleties! 19413:13,14c 1942 1943 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 1944@end example 1945 1946@node diff3 Merging, Interactive Merging, Comparing Three Files, Top 1947@chapter Merging From a Common Ancestor 1948@cindex merging from a common ancestor 1949 1950When two people have made changes to copies of the same file, 1951@code{diff3} can produce a merged output that contains both sets of 1952changes together with warnings about conflicts. 1953 1954One might imagine programs with names like @code{diff4} and @code{diff5} 1955to compare more than three files simultaneously, but in practice the 1956need rarely arises. You can use @code{diff3} to merge three or more 1957sets of changes to a file by merging two change sets at a time. 1958 1959@code{diff3} can incorporate changes from two modified versions into a 1960common preceding version. This lets you merge the sets of changes 1961represented by the two newer files. Specify the common ancestor version 1962as the second argument and the two newer versions as the first and third 1963arguments, like this: 1964 1965@example 1966diff3 @var{mine} @var{older} @var{yours} 1967@end example 1968 1969@noindent 1970You can remember the order of the arguments by noting that they are in 1971alphabetical order. 1972 1973@cindex conflict 1974@cindex overlap 1975You can think of this as subtracting @var{older} from @var{yours} and 1976adding the result to @var{mine}, or as merging into @var{mine} the 1977changes that would turn @var{older} into @var{yours}. This merging is 1978well-defined as long as @var{mine} and @var{older} match in the 1979neighborhood of each such change. This fails to be true when all three 1980input files differ or when only @var{older} differs; we call this 1981a @dfn{conflict}. When all three input files differ, we call the 1982conflict an @dfn{overlap}. 1983 1984@code{diff3} gives you several ways to handle overlaps and conflicts. 1985You can omit overlaps or conflicts, or select only overlaps, 1986or mark conflicts with special @samp{<<<<<<<} and @samp{>>>>>>>} lines. 1987 1988@code{diff3} can output the merge results as an @code{ed} script that 1989that can be applied to the first file to yield the merged output. 1990However, it is usually better to have @code{diff3} generate the merged 1991output directly; this bypasses some problems with @code{ed}. 1992 1993@menu 1994* Which Changes:: Selecting changes to incorporate. 1995* Marking Conflicts:: Marking conflicts. 1996* Bypassing ed:: Generating merged output directly. 1997* Merging Incomplete Lines:: How @code{diff3} merges incomplete lines. 1998* Saving the Changed File:: Emulating System V behavior. 1999@end menu 2000 2001@node Which Changes, Marking Conflicts, , diff3 Merging 2002@section Selecting Which Changes to Incorporate 2003@cindex overlapping change, selection of 2004@cindex unmerged change 2005 2006You can select all unmerged changes from @var{older} to @var{yours} for merging 2007into @var{mine} with the @samp{-e} or @samp{--ed} option. You can 2008select only the nonoverlapping unmerged changes with @samp{-3} or 2009@samp{--easy-only}, and you can select only the overlapping changes with 2010@samp{-x} or @samp{--overlap-only}. 2011 2012The @samp{-e}, @samp{-3} and @samp{-x} options select only 2013@dfn{unmerged changes}, i.e.@: changes where @var{mine} and @var{yours} 2014differ; they ignore changes from @var{older} to @var{yours} where 2015@var{mine} and @var{yours} are identical, because they assume that such 2016changes have already been merged. If this assumption is not a safe 2017one, you can use the @samp{-A} or @samp{--show-all} option 2018(@pxref{Marking Conflicts}). 2019 2020Here is the output of the command @code{diff3} with each of these three 2021options (@pxref{Sample diff3 Input}, for the complete contents of the files). 2022Notice that @samp{-e} outputs the union of the disjoint sets of changes 2023output by @samp{-3} and @samp{-x}. 2024 2025Output of @samp{diff3 -e lao tzu tao}: 2026@example 202711a 2028 2029 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2030. 20318c 2032 so we may see their result. 2033. 2034@end example 2035 2036Output of @samp{diff3 -3 lao tzu tao}: 2037@example 20388c 2039 so we may see their result. 2040. 2041@end example 2042 2043Output of @samp{diff3 -x lao tzu tao}: 2044@example 204511a 2046 2047 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2048. 2049@end example 2050 2051@node Marking Conflicts, Bypassing ed, Which Changes, diff3 Merging 2052@section Marking Conflicts 2053@cindex conflict marking 2054@cindex @samp{<<<<<<<} for marking conflicts 2055 2056@code{diff3} can mark conflicts in the merged output by 2057bracketing them with special marker lines. A conflict 2058that comes from two files @var{A} and @var{B} is marked as follows: 2059 2060@example 2061<<<<<<< @var{A} 2062@r{lines from @var{A}} 2063======= 2064@r{lines from @var{B}} 2065>>>>>>> @var{B} 2066@end example 2067 2068A conflict that comes from three files @var{A}, @var{B} and @var{C} is 2069marked as follows: 2070 2071@example 2072<<<<<<< @var{A} 2073@r{lines from @var{A}} 2074||||||| @var{B} 2075@r{lines from @var{B}} 2076======= 2077@r{lines from @var{C}} 2078>>>>>>> @var{C} 2079@end example 2080 2081The @samp{-A} or @samp{--show-all} option acts like the @samp{-e} 2082option, except that it brackets conflicts, and it outputs all changes 2083from @var{older} to @var{yours}, not just the unmerged changes. Thus, 2084given the sample input files (@pxref{Sample diff3 Input}), @samp{diff3 2085-A lao tzu tao} puts brackets around the conflict where only @file{tzu} 2086differs: 2087 2088@example 2089<<<<<<< tzu 2090======= 2091The Way that can be told of is not the eternal Way; 2092The name that can be named is not the eternal name. 2093>>>>>>> tao 2094@end example 2095 2096And it outputs the three-way conflict as follows: 2097 2098@example 2099<<<<<<< lao 2100||||||| tzu 2101They both may be called deep and profound. 2102Deeper and more profound, 2103The door of all subtleties! 2104======= 2105 2106 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2107>>>>>>> tao 2108@end example 2109 2110The @samp{-E} or @samp{--show-overlap} option outputs less information 2111than the @samp{-A} or @samp{--show-all} option, because it outputs only 2112unmerged changes, and it never outputs the contents of the second 2113file. Thus the @samp{-E} option acts like the @samp{-e} option, 2114except that it brackets the first and third files from three-way 2115overlapping changes. Similarly, @samp{-X} acts like @samp{-x}, except 2116it brackets all its (necessarily overlapping) changes. For example, 2117for the three-way overlapping change above, the @samp{-E} and @samp{-X} 2118options output the following: 2119 2120@example 2121<<<<<<< lao 2122======= 2123 2124 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2125>>>>>>> tao 2126@end example 2127 2128If you are comparing files that have meaningless or uninformative names, 2129you can use the @samp{-L @var{label}} or @samp{--label=@var{label}} 2130option to show alternate names in the @samp{<<<<<<<}, @samp{|||||||} 2131and @samp{>>>>>>>} brackets. This option can be given up to three 2132times, once for each input file. Thus @samp{diff3 -A -L X -L Y -L Z A 2133B C} acts like @samp{diff3 -A A B C}, except that the output looks like 2134it came from files named @samp{X}, @samp{Y} and @samp{Z} rather than 2135from files named @samp{A}, @samp{B} and @samp{C}. 2136 2137@node Bypassing ed, Merging Incomplete Lines, Marking Conflicts, diff3 Merging 2138@section Generating the Merged Output Directly 2139@cindex merged @code{diff3} format 2140 2141With the @samp{-m} or @samp{--merge} option, @code{diff3} outputs the 2142merged file directly. This is more efficient than using @code{ed} to 2143generate it, and works even with non-text files that @code{ed} would 2144reject. If you specify @samp{-m} without an @code{ed} script option, 2145@samp{-A} (@samp{--show-all}) is assumed. 2146 2147For example, the command @samp{diff3 -m lao tzu tao} 2148(@pxref{Sample diff3 Input} for a copy of the input files) would output 2149the following: 2150 2151@example 2152<<<<<<< tzu 2153======= 2154The Way that can be told of is not the eternal Way; 2155The name that can be named is not the eternal name. 2156>>>>>>> tao 2157The Nameless is the origin of Heaven and Earth; 2158The Named is the mother of all things. 2159Therefore let there always be non-being, 2160 so we may see their subtlety, 2161And let there always be being, 2162 so we may see their result. 2163The two are the same, 2164But after they are produced, 2165 they have different names. 2166<<<<<<< lao 2167||||||| tzu 2168They both may be called deep and profound. 2169Deeper and more profound, 2170The door of all subtleties! 2171======= 2172 2173 -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2174>>>>>>> tao 2175@end example 2176 2177@node Merging Incomplete Lines, Saving the Changed File, Bypassing ed, diff3 Merging 2178@section How @code{diff3} Merges Incomplete Lines 2179@cindex incomplete line merging 2180 2181With @samp{-m}, incomplete lines (@pxref{Incomplete Lines}) are simply 2182copied to the output as they are found; if the merged output ends in an 2183conflict and one of the input files ends in an incomplete 2184line, succeeding @samp{|||||||}, @samp{=======} or @samp{>>>>>>>} 2185brackets appear somewhere other than the start of a line because 2186they are appended to the incomplete line. 2187 2188Without @samp{-m}, if an @code{ed} script option is specified and an 2189incomplete line is found, @code{diff3} generates a warning and acts as 2190if a newline had been present. 2191 2192@node Saving the Changed File, , Merging Incomplete Lines, diff3 Merging 2193@section Saving the Changed File 2194@cindex System V @code{diff3} compatibility 2195 2196Traditional Unix @code{diff3} generates an @code{ed} script without the 2197trailing @samp{w} and and @samp{q} commands that save the changes. 2198System V @code{diff3} generates these extra commands. GNU @code{diff3} 2199normally behaves like traditional Unix @code{diff3}, but with the 2200@samp{-i} option it behaves like System V @code{diff3} and appends the 2201@samp{w} and @samp{q} commands. 2202 2203The @samp{-i} option requires one of the @code{ed} script options 2204@samp{-AeExX3}, and is incompatible with the merged output option 2205@samp{-m}. 2206 2207@node Interactive Merging, Merging with patch, diff3 Merging, Top 2208@chapter Interactive Merging with @code{sdiff} 2209@cindex diff merging 2210@cindex interactive merging 2211 2212With @code{sdiff}, you can merge two files interactively based on a 2213side-by-side @samp{-y} format comparison (@pxref{Side by Side}). Use 2214@samp{-o @var{file}} or @samp{--output=@var{file}} to specify where to 2215put the merged text. @xref{Invoking sdiff}, for more details on the 2216options to @code{sdiff}. 2217 2218Another way to merge files interactively is to use the Emacs Lisp 2219package @code{emerge}. @xref{emerge, , emerge, emacs, The GNU Emacs 2220Manual}, for more information. 2221 2222@menu 2223* sdiff Option Summary::Summary of @code{sdiff} options. 2224* Merge Commands:: Merging two files interactively. 2225@end menu 2226 2227@node sdiff Option Summary, Merge Commands, , Interactive Merging 2228@section Specifying @code{diff} Options to @code{sdiff} 2229@cindex @code{sdiff} output format 2230 2231The following @code{sdiff} options have the same meaning as for 2232@code{diff}. @xref{diff Options}, for the use of these options. 2233 2234@example 2235-a -b -d -i -t -v 2236-B -H -I @var{regexp} 2237 2238--ignore-blank-lines --ignore-case 2239--ignore-matching-lines=@var{regexp} --ignore-space-change 2240--left-column --minimal --speed-large-files 2241--suppress-common-lines --expand-tabs 2242--text --version --width=@var{columns} 2243@end example 2244 2245For historical reasons, @code{sdiff} has alternate names for some 2246options. The @samp{-l} option is equivalent to the @samp{--left-column} 2247option, and similarly @samp{-s} is equivalent to 2248@samp{--suppress-common-lines}. The meaning of the @code{sdiff} 2249@samp{-w} and @samp{-W} options is interchanged from that of 2250@code{diff}: with @code{sdiff}, @samp{-w @var{columns}} is equivalent to 2251@samp{--width=@var{columns}}, and @samp{-W} is equivalent to 2252@samp{--ignore-all-space}. @code{sdiff} without the @samp{-o} option is 2253equivalent to @code{diff} with the @samp{-y} or @samp{--side-by-side} 2254option (@pxref{Side by Side}). 2255 2256@node Merge Commands, , sdiff Option Summary, Interactive Merging 2257@section Merge Commands 2258@cindex merge commands 2259@cindex merging interactively 2260 2261Groups of common lines, with a blank gutter, are copied from the first 2262file to the output. After each group of differing lines, @code{sdiff} 2263prompts with @samp{%} and pauses, waiting for one of the following 2264commands. Follow each command with @key{RET}. 2265 2266@table @samp 2267@item e 2268Discard both versions. 2269Invoke a text editor on an empty temporary file, 2270then copy the resulting file to the output. 2271 2272@item eb 2273Concatenate the two versions, edit the result in a temporary file, 2274then copy the edited result to the output. 2275 2276@item el 2277Edit a copy of the left version, then copy the result to the output. 2278 2279@item er 2280Edit a copy of the right version, then copy the result to the output. 2281 2282@item l 2283Copy the left version to the output. 2284 2285@item q 2286Quit. 2287 2288@item r 2289Copy the right version to the output. 2290 2291@item s 2292Silently copy common lines. 2293 2294@item v 2295Verbosely copy common lines. This is the default. 2296@end table 2297 2298The text editor invoked is specified by the @code{EDITOR} environment 2299variable if it is set. The default is system-dependent. 2300 2301@node Merging with patch, Making Patches, Interactive Merging, Top 2302@chapter Merging with @code{patch} 2303 2304@code{patch} takes comparison output produced by @code{diff} and applies 2305the differences to a copy of the original file, producing a patched 2306version. With @code{patch}, you can distribute just the changes to a 2307set of files instead of distributing the entire file set; your 2308correspondents can apply @code{patch} to update their copy of the files 2309with your changes. @code{patch} automatically determines the diff 2310format, skips any leading or trailing headers, and uses the headers to 2311determine which file to patch. This lets your correspondents feed an 2312article or message containing a difference listing directly to 2313@code{patch}. 2314 2315@code{patch} detects and warns about common problems like forward 2316patches. It saves the original version of the files it patches, and 2317saves any patches that it could not apply. It can also maintain a 2318@code{patchlevel.h} file to ensures that your correspondents apply 2319diffs in the proper order. 2320 2321@code{patch} accepts a series of diffs in its standard input, usually 2322separated by headers that specify which file to patch. It applies 2323@code{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not 2324exactly match the original file, @code{patch} uses heuristics to try to 2325patch the file as well as it can. If no approximate match can be found, 2326@code{patch} rejects the hunk and skips to the next hunk. @code{patch} 2327normally replaces each file @var{f} with its new version, saving the 2328original file in @samp{@var{f}.orig}, and putting reject hunks (if any) 2329into @samp{@var{f}.rej}. 2330 2331@xref{Invoking patch}, for detailed information on the options to 2332@code{patch}. @xref{Backups}, for more information on how 2333@code{patch} names backup files. @xref{Rejects}, for more information 2334on where @code{patch} puts reject hunks. 2335 2336@menu 2337* patch Input:: Selecting the type of @code{patch} input. 2338* Imperfect:: Dealing with imperfect patches. 2339* Empty Files:: Removing empty files after patching. 2340* Multiple Patches:: Handling multiple patches in a file specially. 2341* patch Messages:: Messages and questions @code{patch} can produce. 2342@end menu 2343 2344@node patch Input, Imperfect, , Merging with patch 2345@section Selecting the @code{patch} Input Format 2346@cindex @code{patch} input format 2347 2348@code{patch} normally determines which @code{diff} format the patch 2349file uses by examining its contents. For patch files that contain 2350particularly confusing leading text, you might need to use one of the 2351following options to force @code{patch} to interpret the patch file as a 2352certain format of diff. The output formats listed here are the only 2353ones that @code{patch} can understand. 2354 2355@table @samp 2356@item -c 2357@itemx --context 2358context diff. 2359 2360@item -e 2361@itemx --ed 2362@code{ed} script. 2363 2364@item -n 2365@itemx --normal 2366normal diff. 2367 2368@item -u 2369@itemx --unified 2370unified diff. 2371@end table 2372 2373@node Imperfect, Empty Files, patch Input, Merging with patch 2374@section Applying Imperfect Patches 2375@cindex imperfect patch application 2376 2377@code{patch} tries to skip any leading text in the patch file, apply the 2378diff, and then skip any trailing text. Thus you can feed a news article 2379or mail message directly to @code{patch}, and it should work. If the 2380entire diff is indented by a constant amount of white space, @code{patch} 2381automatically ignores the indentation. 2382 2383However, certain other types of imperfect input require user 2384intervention. 2385 2386@menu 2387* Changed White Space:: When tabs and spaces don't match exactly. 2388* Reversed Patches:: Applying reversed patches correctly. 2389* Inexact:: Helping @code{patch} find close matches. 2390@end menu 2391 2392@node Changed White Space, Reversed Patches, , Imperfect 2393@subsection Applying Patches with Changed White Space 2394@cindex white space in patches 2395 2396Sometimes mailers, editors, or other programs change spaces into tabs, 2397or vice versa. If this happens to a patch file or an input file, the 2398files might look the same, but @code{patch} will not be able to match 2399them properly. If this problem occurs, use the @samp{-l} or 2400@samp{--ignore-white-space} option, which makes @code{patch} compare 2401white space loosely so that any sequence of white space in the patch file 2402matches any sequence of white space in the input files. Non-white-space 2403characters must still match exactly. Each line of the context must 2404still match a line in the input file. 2405 2406@node Reversed Patches, Inexact, Changed White Space, Imperfect 2407@subsection Applying Reversed Patches 2408@cindex reversed patches 2409 2410Sometimes people run @code{diff} with the new file first instead of 2411second. This creates a diff that is ``reversed''. To apply such 2412patches, give @code{patch} the @samp{-R} or @samp{--reverse} option. 2413@code{patch} then attempts to swap each hunk around before applying it. 2414Rejects come out in the swapped format. The @samp{-R} option does not 2415work with @code{ed} scripts because there is too little information in 2416them to reconstruct the reverse operation. 2417 2418Often @code{patch} can guess that the patch is reversed. If the first 2419hunk of a patch fails, @code{patch} reverses the hunk to see if it can 2420apply it that way. If it can, @code{patch} asks you if you want to have 2421the @samp{-R} option set; if it can't, @code{patch} continues to apply 2422the patch normally. This method cannot detect a reversed patch if it is 2423a normal diff and the first command is an append (which should have been 2424a delete) since appends always succeed, because a null context matches 2425anywhere. But most patches add or change lines rather than delete them, 2426so most reversed normal diffs begin with a delete, which fails, and 2427@code{patch} notices. 2428 2429If you apply a patch that you have already applied, @code{patch} thinks 2430it is a reversed patch and offers to un-apply the patch. This could be 2431construed as a feature. If you did this inadvertently and you don't 2432want to un-apply the patch, just answer @samp{n} to this offer and to 2433the subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the 2434@code{patch} process. 2435 2436@node Inexact, , Reversed Patches, Imperfect 2437@subsection Helping @code{patch} Find Inexact Matches 2438@cindex inexact patches 2439@cindex fuzz factor when patching 2440 2441For context diffs, and to a lesser extent normal diffs, @code{patch} can 2442detect when the line numbers mentioned in the patch are incorrect, and 2443it attempts to find the correct place to apply each hunk of the patch. 2444As a first guess, it takes the line number mentioned in the hunk, plus 2445or minus any offset used in applying the previous hunk. If that is not 2446the correct place, @code{patch} scans both forward and backward for a 2447set of lines matching the context given in the hunk. 2448 2449First @code{patch} looks for a place where all lines of the context 2450match. If it cannot find such a place, and it is reading a context or 2451unified diff, and the maximum fuzz factor is set to 1 or more, then 2452@code{patch} makes another scan, ignoring the first and last line of 2453context. If that fails, and the maximum fuzz factor is set to 2 or 2454more, it makes another scan, ignoring the first two and last two lines 2455of context are ignored. It continues similarly if the maximum fuzz 2456factor is larger. 2457 2458The @samp{-F @var{lines}} or @samp{--fuzz=@var{lines}} option sets the 2459maximum fuzz factor to @var{lines}. This option only applies to context 2460and unified diffs; it ignores up to @var{lines} lines while looking for 2461the place to install a hunk. Note that a larger fuzz factor increases 2462the odds of making a faulty patch. The default fuzz factor is 2; it may 2463not be set to more than the number of lines of context in the diff, 2464ordinarily 3. 2465 2466If @code{patch} cannot find a place to install a hunk of the patch, it 2467writes the hunk out to a reject file (@pxref{Rejects}, for information 2468on how reject files are named). It writes out rejected hunks in context 2469format no matter what form the input patch is in. If the input is a 2470normal or @code{ed} diff, many of the contexts are simply null. The 2471line numbers on the hunks in the reject file may be different from those 2472in the patch file: they show the approximate location where @code{patch} 2473thinks the failed hunks belong in the new file rather than in the old 2474one. 2475 2476As it completes each hunk, @code{patch} tells you whether the hunk 2477succeeded or failed, and if it failed, on which line (in the new file) 2478@code{patch} thinks the hunk should go. If this is different from the 2479line number specified in the diff, it tells you the offset. A single 2480large offset @emph{may} indicate that @code{patch} installed a hunk in 2481the wrong place. @code{patch} also tells you if it used a fuzz factor 2482to make the match, in which case you should also be slightly suspicious. 2483 2484@code{patch} cannot tell if the line numbers are off in an @code{ed} 2485script, and can only detect wrong line numbers in a normal diff when it 2486finds a change or delete command. It may have the same problem with a 2487context diff using a fuzz factor equal to or greater than the number of 2488lines of context shown in the diff (typically 3). In these cases, you 2489should probably look at a context diff between your original and patched 2490input files to see if the changes make sense. Compiling without errors 2491is a pretty good indication that the patch worked, but not a guarantee. 2492 2493@code{patch} usually produces the correct results, even when it must 2494make many guesses. However, the results are guaranteed only when 2495the patch is applied to an exact copy of the file that the patch was 2496generated from. 2497 2498@node Empty Files, Multiple Patches, Imperfect, Merging with patch 2499@section Removing Empty Files 2500@cindex empty files, removing 2501@cindex removing empty files 2502 2503Sometimes when comparing two directories, the first directory contains a 2504file that the second directory does not. If you give @code{diff} the 2505@samp{-N} or @samp{--new-file} option, it outputs a diff that deletes 2506the contents of this file. By default, @code{patch} leaves an empty 2507file after applying such a diff. The @samp{-E} or 2508@samp{--remove-empty-files} option to @code{patch} deletes output files 2509that are empty after applying the diff. 2510 2511@node Multiple Patches, patch Messages, Empty Files, Merging with patch 2512@section Multiple Patches in a File 2513@cindex multiple patches 2514 2515If the patch file contains more than one patch, @code{patch} tries to 2516apply each of them as if they came from separate patch files. This 2517means that it determines the name of the file to patch for each patch, 2518and that it examines the leading text before each patch for file names 2519and prerequisite revision level (@pxref{Making Patches}, for more on 2520that topic). 2521 2522For the second and subsequent patches in the patch file, you can give 2523options and another original file name by separating their argument 2524lists with a @samp{+}. However, the argument list for a second or 2525subsequent patch may not specify a new patch file, since that does not 2526make sense. 2527 2528For example, to tell @code{patch} to strip the first three slashes from 2529the name of the first patch in the patch file and none from subsequent 2530patches, and to use @file{code.c} as the first input file, you can use: 2531 2532@example 2533patch -p3 code.c + -p0 < patchfile 2534@end example 2535 2536The @samp{-S} or @samp{--skip} option ignores the current patch from the 2537patch file, but continue looking for the next patch in the file. Thus, 2538to ignore the first and third patches in the patch file, you can use: 2539 2540@example 2541patch -S + + -S + < patch file 2542@end example 2543 2544@node patch Messages, , Multiple Patches, Merging with patch 2545@section Messages and Questions from @code{patch} 2546@cindex @code{patch} messages and questions 2547@cindex diagnostics from @code{patch} 2548@cindex messages from @code{patch} 2549 2550@code{patch} can produce a variety of messages, especially if it has 2551trouble decoding its input. In a few situations where it's not sure how 2552to proceed, @code{patch} normally prompts you for more information from 2553the keyboard. There are options to suppress printing non-fatal messages 2554and stopping for keyboard input. 2555 2556The message @samp{Hmm...} indicates that @code{patch} is reading text in 2557the patch file, attempting to determine whether there is a patch in that 2558text, and if so, what kind of patch it is. 2559 2560You can inhibit all terminal output from @code{patch}, unless an error 2561occurs, by using the @samp{-s}, @samp{--quiet}, or @samp{--silent} 2562option. 2563 2564There are two ways you can prevent @code{patch} from asking you any 2565questions. The @samp{-f} or @samp{--force} option assumes that you know 2566what you are doing. It assumes the following: 2567 2568@itemize @bullet 2569@item 2570skip patches that do not contain file names in their headers; 2571 2572@item 2573patch files even though they have the wrong version for the 2574@samp{Prereq:} line in the patch; 2575 2576@item 2577assume that patches are not reversed even if they look like they are. 2578@end itemize 2579 2580The @samp{-t} or @samp{--batch} option is similar to @samp{-f}, in that 2581it suppresses questions, but it makes somewhat different assumptions: 2582 2583@itemize @bullet 2584@item 2585skip patches that do not contain file names in their headers 2586(the same as @samp{-f}); 2587 2588@item 2589skip patches for which the file has the wrong version for the 2590@samp{Prereq:} line in the patch; 2591 2592@item 2593assume that patches are reversed if they look like they are. 2594@end itemize 2595 2596@code{patch} exits with a non-zero status if it creates any reject 2597files. When applying a set of patches in a loop, you should check the 2598exit status, so you don't apply a later patch to a partially patched 2599file. 2600 2601@node Making Patches, Invoking cmp, Merging with patch, Top 2602@chapter Tips for Making Patch Distributions 2603@cindex patch making tips 2604@cindex tips for patch making 2605 2606Here are some things you should keep in mind if you are going to 2607distribute patches for updating a software package. 2608 2609Make sure you have specified the file names correctly, either in a 2610context diff header or with an @samp{Index:} line. If you are patching 2611files in a subdirectory, be sure to tell the patch user to specify a 2612@samp{-p} or @samp{--strip} option as needed. Take care to not send out 2613reversed patches, since these make people wonder whether they have 2614already applied the patch. 2615 2616To save people from partially applying a patch before other patches that 2617should have gone before it, you can make the first patch in the patch 2618file update a file with a name like @file{patchlevel.h} or 2619@file{version.c}, which contains a patch level or version number. If 2620the input file contains the wrong version number, @code{patch} will 2621complain immediately. 2622 2623An even clearer way to prevent this problem is to put a @samp{Prereq:} 2624line before the patch. If the leading text in the patch file contains a 2625line that starts with @samp{Prereq:}, @code{patch} takes the next word 2626from that line (normally a version number) and checks whether the next 2627input file contains that word, preceded and followed by either 2628white space or a newline. If not, @code{patch} prompts you for 2629confirmation before proceeding. This makes it difficult to accidentally 2630apply patches in the wrong order. 2631 2632Since @code{patch} does not handle incomplete lines properly, make sure 2633that all the source files in your program end with a newline whenever 2634you release a version. 2635 2636To create a patch that changes an older version of a package into a 2637newer version, first make a copy of the older version in a scratch 2638directory. Typically you do that by unpacking a @code{tar} or 2639@code{shar} archive of the older version. 2640 2641You might be able to reduce the size of the patch by renaming or 2642removing some files before making the patch. If the older version of 2643the package contains any files that the newer version does not, or if 2644any files have been renamed between the two versions, make a list of 2645@code{rm} and @code{mv} commands for the user to execute in the old 2646version directory before applying the patch. Then run those commands 2647yourself in the scratch directory. 2648 2649If there are any files that you don't need to include in the patch 2650because they can easily be rebuilt from other files (for example, 2651@file{TAGS} and output from @code{yacc} and @code{makeinfo}), replace 2652the versions in the scratch directory with the newer versions, using 2653@code{rm} and @code{ln} or @code{cp}. 2654 2655Now you can create the patch. The de-facto standard @code{diff} format 2656for patch distributions is context format with two lines of context, 2657produced by giving @code{diff} the @samp{-C 2} option. Do not use less 2658than two lines of context, because @code{patch} typically needs at 2659least two lines for proper operation. Give @code{diff} the @samp{-P} 2660option in case the newer version of the package contains any files that 2661the older one does not. Make sure to specify the scratch directory 2662first and the newer directory second. 2663 2664Add to the top of the patch a note telling the user any @code{rm} and 2665@code{mv} commands to run before applying the patch. Then you can 2666remove the scratch directory. 2667 2668@node Invoking cmp, Invoking diff, Making Patches, Top 2669@chapter Invoking @code{cmp} 2670@cindex invoking @code{cmp} 2671@cindex @code{cmp} invocation 2672 2673The @code{cmp} command compares two files, and if they differ, tells the 2674first byte and line number where they differ. Its arguments are as 2675follows: 2676 2677@example 2678cmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file}@var{]} 2679@end example 2680 2681The file name @samp{-} is always the standard input. @code{cmp} also 2682uses the standard input if one file name is omitted. 2683 2684An exit status of 0 means no differences were found, 1 means some 2685differences were found, and 2 means trouble. 2686 2687@menu 2688* cmp Options:: Summary of options to @code{cmp}. 2689@end menu 2690 2691@node cmp Options, , , Invoking cmp 2692@section Options to @code{cmp} 2693@cindex @code{cmp} options 2694@cindex options for @code{cmp} 2695 2696Below is a summary of all of the options that GNU @code{cmp} accepts. 2697Most options have two equivalent names, one of which is a single letter 2698preceded by @samp{-}, and the other of which is a long name preceded by 2699@samp{--}. Multiple single letter options (unless they take an 2700argument) can be combined into a single command line word: @samp{-cl} is 2701equivalent to @samp{-c -l}. 2702 2703@table @samp 2704@item -c 2705Print the differing characters. Display control characters as a 2706@samp{^} followed by a letter of the alphabet and precede characters 2707that have the high bit set with @samp{M-} (which stands for ``meta''). 2708 2709@item --ignore-initial=@var{bytes} 2710Ignore any differences in the the first @var{bytes} bytes of the input files. 2711Treat files with fewer than @var{bytes} bytes as if they are empty. 2712 2713@item -l 2714Print the (decimal) offsets and (octal) values of all differing bytes. 2715 2716@item --print-chars 2717Print the differing characters. Display control characters as a 2718@samp{^} followed by a letter of the alphabet and precede characters 2719that have the high bit set with @samp{M-} (which stands for ``meta''). 2720 2721@item --quiet 2722@itemx -s 2723@itemx --silent 2724Do not print anything; only return an exit status indicating whether 2725the files differ. 2726 2727@item --verbose 2728Print the (decimal) offsets and (octal) values of all differing bytes. 2729 2730@item -v 2731@item --version 2732Output the version number of @code{cmp}. 2733@end table 2734 2735@node Invoking diff, Invoking diff3, Invoking cmp, Top 2736@chapter Invoking @code{diff} 2737@cindex invoking @code{diff} 2738@cindex @code{diff} invocation 2739 2740The format for running the @code{diff} command is: 2741 2742@example 2743diff @var{options}@dots{} @var{from-file} @var{to-file} 2744@end example 2745 2746In the simplest case, @code{diff} compares the contents of the two files 2747@var{from-file} and @var{to-file}. A file name of @samp{-} stands for 2748text read from the standard input. As a special case, @samp{diff - -} 2749compares a copy of standard input to itself. 2750 2751If @var{from-file} is a directory and @var{to-file} is not, @code{diff} 2752compares the file in @var{from-file} whose file name is that of @var{to-file}, 2753and vice versa. The non-directory file must not be @samp{-}. 2754 2755If both @var{from-file} and @var{to-file} are directories, 2756@code{diff} compares corresponding files in both directories, in 2757alphabetical order; this comparison is not recursive unless the 2758@samp{-r} or @samp{--recursive} option is given. @code{diff} never 2759compares the actual contents of a directory as if it were a file. The 2760file that is fully specified may not be standard input, because standard 2761input is nameless and the notion of ``file with the same name'' does not 2762apply. 2763 2764@code{diff} options begin with @samp{-}, so normally @var{from-file} and 2765@var{to-file} may not begin with @samp{-}. However, @samp{--} as an 2766argument by itself treats the remaining arguments as file names even if 2767they begin with @samp{-}. 2768 2769An exit status of 0 means no differences were found, 1 means some 2770differences were found, and 2 means trouble. 2771 2772@menu 2773* diff Options:: Summary of options to @code{diff}. 2774@end menu 2775 2776@node diff Options, , , Invoking diff 2777@section Options to @code{diff} 2778@cindex @code{diff} options 2779@cindex options for @code{diff} 2780 2781Below is a summary of all of the options that GNU @code{diff} accepts. 2782Most options have two equivalent names, one of which is a single letter 2783preceded by @samp{-}, and the other of which is a long name preceded by 2784@samp{--}. Multiple single letter options (unless they take an 2785argument) can be combined into a single command line word: @samp{-ac} is 2786equivalent to @samp{-a -c}. Long named options can be abbreviated to 2787any unique prefix of their name. Brackets ([ and ]) indicate that an 2788option takes an optional argument. 2789 2790@table @samp 2791@item -@var{lines} 2792Show @var{lines} (an integer) lines of context. This option does not 2793specify an output format by itself; it has no effect unless it is 2794combined with @samp{-c} (@pxref{Context Format}) or @samp{-u} 2795(@pxref{Unified Format}). This option is obsolete. For proper 2796operation, @code{patch} typically needs at least two lines of context. 2797 2798@item -a 2799Treat all files as text and compare them line-by-line, even if they 2800do not seem to be text. @xref{Binary}. 2801 2802@item -b 2803Ignore changes in amount of white space. @xref{White Space}. 2804 2805@item -B 2806Ignore changes that just insert or delete blank lines. @xref{Blank 2807Lines}. 2808 2809@item --binary 2810Read and write data in binary mode. @xref{Binary}. 2811 2812@item --brief 2813Report only whether the files differ, not the details of the 2814differences. @xref{Brief}. 2815 2816@item -c 2817Use the context output format. @xref{Context Format}. 2818 2819@item -C @var{lines} 2820@itemx --context@r{[}=@var{lines}@r{]} 2821Use the context output format, showing @var{lines} (an integer) lines of 2822context, or three if @var{lines} is not given. @xref{Context Format}. 2823For proper operation, @code{patch} typically needs at least two lines of 2824context. 2825 2826@item --changed-group-format=@var{format} 2827Use @var{format} to output a line group containing differing lines from 2828both files in if-then-else format. @xref{Line Group Formats}. 2829 2830@item -d 2831Change the algorithm perhaps find a smaller set of changes. This makes 2832@code{diff} slower (sometimes much slower). @xref{diff Performance}. 2833 2834@item -D @var{name} 2835Make merged @samp{#ifdef} format output, conditional on the preprocessor 2836macro @var{name}. @xref{If-then-else}. 2837 2838@item -e 2839@itemx --ed 2840Make output that is a valid @code{ed} script. @xref{ed Scripts}. 2841 2842@item --exclude=@var{pattern} 2843When comparing directories, ignore files and subdirectories whose basenames 2844match @var{pattern}. @xref{Comparing Directories}. 2845 2846@item --exclude-from=@var{file} 2847When comparing directories, ignore files and subdirectories whose basenames 2848match any pattern contained in @var{file}. @xref{Comparing Directories}. 2849 2850@item --expand-tabs 2851Expand tabs to spaces in the output, to preserve the alignment of tabs 2852in the input files. @xref{Tabs}. 2853 2854@item -f 2855Make output that looks vaguely like an @code{ed} script but has changes 2856in the order they appear in the file. @xref{Forward ed}. 2857 2858@item -F @var{regexp} 2859In context and unified format, for each hunk of differences, show some 2860of the last preceding line that matches @var{regexp}. @xref{Specified 2861Headings}. 2862 2863@item --forward-ed 2864Make output that looks vaguely like an @code{ed} script but has changes 2865in the order they appear in the file. @xref{Forward ed}. 2866 2867@item -h 2868This option currently has no effect; it is present for Unix 2869compatibility. 2870 2871@item -H 2872Use heuristics to speed handling of large files that have numerous 2873scattered small changes. @xref{diff Performance}. 2874 2875@item --horizon-lines=@var{lines} 2876Do not discard the last @var{lines} lines of the common prefix 2877and the first @var{lines} lines of the common suffix. 2878@xref{diff Performance}. 2879 2880@item -i 2881Ignore changes in case; consider upper- and lower-case letters 2882equivalent. @xref{Case Folding}. 2883 2884@item -I @var{regexp} 2885Ignore changes that just insert or delete lines that match @var{regexp}. 2886@xref{Specified Folding}. 2887 2888@item --ifdef=@var{name} 2889Make merged if-then-else output using @var{name}. @xref{If-then-else}. 2890 2891@item --ignore-all-space 2892Ignore white space when comparing lines. @xref{White Space}. 2893 2894@item --ignore-blank-lines 2895Ignore changes that just insert or delete blank lines. @xref{Blank 2896Lines}. 2897 2898@item --ignore-case 2899Ignore changes in case; consider upper- and lower-case to be the same. 2900@xref{Case Folding}. 2901 2902@item --ignore-matching-lines=@var{regexp} 2903Ignore changes that just insert or delete lines that match @var{regexp}. 2904@xref{Specified Folding}. 2905 2906@item --ignore-space-change 2907Ignore changes in amount of white space. 2908@xref{White Space}. 2909 2910@item --initial-tab 2911Output a tab rather than a space before the text of a line in normal or 2912context format. This causes the alignment of tabs in the line to look 2913normal. @xref{Tabs}. 2914 2915@item -l 2916Pass the output through @code{pr} to paginate it. @xref{Pagination}. 2917 2918@item -L @var{label} 2919Use @var{label} instead of the file name in the context format 2920(@pxref{Context Format}) and unified format (@pxref{Unified Format}) 2921headers. @xref{RCS}. 2922 2923@item --label=@var{label} 2924Use @var{label} instead of the file name in the context format 2925(@pxref{Context Format}) and unified format (@pxref{Unified Format}) 2926headers. 2927 2928@item --left-column 2929Print only the left column of two common lines in side by side format. 2930@xref{Side by Side Format}. 2931 2932@item --line-format=@var{format} 2933Use @var{format} to output all input lines in if-then-else format. 2934@xref{Line Formats}. 2935 2936@item --minimal 2937Change the algorithm to perhaps find a smaller set of changes. This 2938makes @code{diff} slower (sometimes much slower). @xref{diff 2939Performance}. 2940 2941@item -n 2942Output RCS-format diffs; like @samp{-f} except that each command 2943specifies the number of lines affected. @xref{RCS}. 2944 2945@item -N 2946@itemx --new-file 2947In directory comparison, if a file is found in only one directory, 2948treat it as present but empty in the other directory. @xref{Comparing 2949Directories}. 2950 2951@item --new-group-format=@var{format} 2952Use @var{format} to output a group of lines taken from just the second 2953file in if-then-else format. @xref{Line Group Formats}. 2954 2955@item --new-line-format=@var{format} 2956Use @var{format} to output a line taken from just the second file in 2957if-then-else format. @xref{Line Formats}. 2958 2959@item --old-group-format=@var{format} 2960Use @var{format} to output a group of lines taken from just the first 2961file in if-then-else format. @xref{Line Group Formats}. 2962 2963@item --old-line-format=@var{format} 2964Use @var{format} to output a line taken from just the first file in 2965if-then-else format. @xref{Line Formats}. 2966 2967@item -p 2968Show which C function each change is in. @xref{C Function Headings}. 2969 2970@item -P 2971When comparing directories, if a file appears only in the second 2972directory of the two, treat it as present but empty in the other. 2973@xref{Comparing Directories}. 2974 2975@item --paginate 2976Pass the output through @code{pr} to paginate it. @xref{Pagination}. 2977 2978@item -q 2979Report only whether the files differ, not the details of the 2980differences. @xref{Brief}. 2981 2982@item -r 2983When comparing directories, recursively compare any subdirectories 2984found. @xref{Comparing Directories}. 2985 2986@item --rcs 2987Output RCS-format diffs; like @samp{-f} except that each command 2988specifies the number of lines affected. @xref{RCS}. 2989 2990@item --recursive 2991When comparing directories, recursively compare any subdirectories 2992found. @xref{Comparing Directories}. 2993 2994@item --report-identical-files 2995Report when two files are the same. @xref{Comparing Directories}. 2996 2997@item -s 2998Report when two files are the same. @xref{Comparing Directories}. 2999 3000@item -S @var{file} 3001When comparing directories, start with the file @var{file}. This is 3002used for resuming an aborted comparison. @xref{Comparing Directories}. 3003 3004@item --sdiff-merge-assist 3005Print extra information to help @code{sdiff}. @code{sdiff} uses this 3006option when it runs @code{diff}. This option is not intended for users 3007to use directly. 3008 3009@item --show-c-function 3010Show which C function each change is in. @xref{C Function Headings}. 3011 3012@item --show-function-line=@var{regexp} 3013In context and unified format, for each hunk of differences, show some 3014of the last preceding line that matches @var{regexp}. @xref{Specified 3015Headings}. 3016 3017@item --side-by-side 3018Use the side by side output format. @xref{Side by Side Format}. 3019 3020@item --speed-large-files 3021Use heuristics to speed handling of large files that have numerous 3022scattered small changes. @xref{diff Performance}. 3023 3024@item --starting-file=@var{file} 3025When comparing directories, start with the file @var{file}. This is 3026used for resuming an aborted comparison. @xref{Comparing Directories}. 3027 3028@item --suppress-common-lines 3029Do not print common lines in side by side format. 3030@xref{Side by Side Format}. 3031 3032@item -t 3033Expand tabs to spaces in the output, to preserve the alignment of tabs 3034in the input files. @xref{Tabs}. 3035 3036@item -T 3037Output a tab rather than a space before the text of a line in normal or 3038context format. This causes the alignment of tabs in the line to look 3039normal. @xref{Tabs}. 3040 3041@item --text 3042Treat all files as text and compare them line-by-line, even if they 3043do not appear to be text. @xref{Binary}. 3044 3045@item -u 3046Use the unified output format. @xref{Unified Format}. 3047 3048@item --unchanged-group-format=@var{format} 3049Use @var{format} to output a group of common lines taken from both files 3050in if-then-else format. @xref{Line Group Formats}. 3051 3052@item --unchanged-line-format=@var{format} 3053Use @var{format} to output a line common to both files in if-then-else 3054format. @xref{Line Formats}. 3055 3056@item --unidirectional-new-file 3057When comparing directories, if a file appears only in the second 3058directory of the two, treat it as present but empty in the other. 3059@xref{Comparing Directories}. 3060 3061@item -U @var{lines} 3062@itemx --unified@r{[}=@var{lines}@r{]} 3063Use the unified output format, showing @var{lines} (an integer) lines of 3064context, or three if @var{lines} is not given. @xref{Unified Format}. 3065For proper operation, @code{patch} typically needs at least two lines of 3066context. 3067 3068@item -v 3069@itemx --version 3070Output the version number of @code{diff}. 3071 3072@item -w 3073Ignore white space when comparing lines. @xref{White Space}. 3074 3075@item -W @var{columns} 3076@itemx --width=@var{columns} 3077Use an output width of @var{columns} in side by side format. 3078@xref{Side by Side Format}. 3079 3080@item -x @var{pattern} 3081When comparing directories, ignore files and subdirectories whose basenames 3082match @var{pattern}. @xref{Comparing Directories}. 3083 3084@item -X @var{file} 3085When comparing directories, ignore files and subdirectories whose basenames 3086match any pattern contained in @var{file}. @xref{Comparing Directories}. 3087 3088@item -y 3089Use the side by side output format. @xref{Side by Side Format}. 3090@end table 3091 3092@node Invoking diff3, Invoking patch, Invoking diff, Top 3093@chapter Invoking @code{diff3} 3094@cindex invoking @code{diff3} 3095@cindex @code{diff3} invocation 3096 3097The @code{diff3} command compares three files and outputs descriptions 3098of their differences. Its arguments are as follows: 3099 3100@example 3101diff3 @var{options}@dots{} @var{mine} @var{older} @var{yours} 3102@end example 3103 3104The files to compare are @var{mine}, @var{older}, and @var{yours}. 3105At most one of these three file names may be @samp{-}, 3106which tells @code{diff3} to read the standard input for that file. 3107 3108An exit status of 0 means @code{diff3} was successful, 1 means some 3109conflicts were found, and 2 means trouble. 3110 3111@menu 3112* diff3 Options:: Summary of options to @code{diff3}. 3113@end menu 3114 3115@node diff3 Options, , , Invoking diff3 3116@section Options to @code{diff3} 3117@cindex @code{diff3} options 3118@cindex options for @code{diff3} 3119 3120Below is a summary of all of the options that GNU @code{diff3} 3121accepts. Multiple single letter options (unless they take an argument) 3122can be combined into a single command line argument. 3123 3124@table @samp 3125@item -a 3126Treat all files as text and compare them line-by-line, even if they 3127do not appear to be text. @xref{Binary}. 3128 3129@item -A 3130Incorporate all changes from @var{older} to @var{yours} into @var{mine}, 3131surrounding all conflicts with bracket lines. 3132@xref{Marking Conflicts}. 3133 3134@item -e 3135Generate an @code{ed} script that incorporates all the changes from 3136@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}. 3137 3138@item -E 3139Like @samp{-e}, except bracket lines from overlapping changes' first 3140and third files. 3141@xref{Marking Conflicts}. 3142With @samp{-e}, an overlapping change looks like this: 3143 3144@example 3145<<<<<<< @var{mine} 3146@r{lines from @var{mine}} 3147======= 3148@r{lines from @var{yours}} 3149>>>>>>> @var{yours} 3150@end example 3151 3152@item --ed 3153Generate an @code{ed} script that incorporates all the changes from 3154@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}. 3155 3156@item --easy-only 3157Like @samp{-e}, except output only the nonoverlapping changes. 3158@xref{Which Changes}. 3159 3160@item -i 3161Generate @samp{w} and @samp{q} commands at the end of the @code{ed} 3162script for System V compatibility. This option must be combined with 3163one of the @samp{-AeExX3} options, and may not be combined with @samp{-m}. 3164@xref{Saving the Changed File}. 3165 3166@item --initial-tab 3167Output a tab rather than two spaces before the text of a line in normal format. 3168This causes the alignment of tabs in the line to look normal. @xref{Tabs}. 3169 3170@item -L @var{label} 3171@itemx --label=@var{label} 3172Use the label @var{label} for the brackets output by the @samp{-A}, 3173@samp{-E} and @samp{-X} options. This option may be given up to three 3174times, one for each input file. The default labels are the names of 3175the input files. Thus @samp{diff3 -L X -L Y -L Z -m A B C} acts like 3176@samp{diff3 -m A B C}, except that the output looks like it came from 3177files named @samp{X}, @samp{Y} and @samp{Z} rather than from files 3178named @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}. 3179 3180@item -m 3181@itemx --merge 3182Apply the edit script to the first file and send the result to standard 3183output. Unlike piping the output from @code{diff3} to @code{ed}, this 3184works even for binary files and incomplete lines. @samp{-A} is assumed 3185if no edit script option is specified. @xref{Bypassing ed}. 3186 3187@item --overlap-only 3188Like @samp{-e}, except output only the overlapping changes. 3189@xref{Which Changes}. 3190 3191@item --show-all 3192Incorporate all unmerged changes from @var{older} to @var{yours} into 3193@var{mine}, surrounding all overlapping changes with bracket lines. 3194@xref{Marking Conflicts}. 3195 3196@item --show-overlap 3197Like @samp{-e}, except bracket lines from overlapping changes' first 3198and third files. 3199@xref{Marking Conflicts}. 3200 3201@item -T 3202Output a tab rather than two spaces before the text of a line in normal format. 3203This causes the alignment of tabs in the line to look normal. @xref{Tabs}. 3204 3205@item --text 3206Treat all files as text and compare them line-by-line, even if they 3207do not appear to be text. @xref{Binary}. 3208 3209@item -v 3210@itemx --version 3211Output the version number of @code{diff3}. 3212 3213@item -x 3214Like @samp{-e}, except output only the overlapping changes. 3215@xref{Which Changes}. 3216 3217@item -X 3218Like @samp{-E}, except output only the overlapping changes. 3219In other words, like @samp{-x}, except bracket changes as in @samp{-E}. 3220@xref{Marking Conflicts}. 3221 3222@item -3 3223Like @samp{-e}, except output only the nonoverlapping changes. 3224@xref{Which Changes}. 3225@end table 3226 3227@node Invoking patch, Invoking sdiff, Invoking diff3, Top 3228@chapter Invoking @code{patch} 3229@cindex invoking @code{patch} 3230@cindex @code{patch} invocation 3231 3232Normally @code{patch} is invoked like this: 3233 3234@example 3235patch <@var{patchfile} 3236@end example 3237 3238The full format for invoking @code{patch} is: 3239 3240@example 3241patch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]} @r{[}+ @var{options}@dots{} @r{[}@var{origfile}@r{]}@r{]}@dots{} 3242@end example 3243 3244If you do not specify @var{patchfile}, or if @var{patchfile} is 3245@samp{-}, @code{patch} reads the patch (that is, the @code{diff} output) 3246from the standard input. 3247 3248You can specify one or more of the original files as @var{orig} arguments; 3249each one and options for interpreting it is separated from the others with a 3250@samp{+}. @xref{Multiple Patches}, for more information. 3251 3252If you do not specify an input file on the command line, @code{patch} 3253tries to figure out from the @dfn{leading text} (any text in the patch 3254that comes before the @code{diff} output) which file to edit. In the 3255header of a context or unified diff, @code{patch} looks in lines 3256beginning with @samp{***}, @samp{---}, or @samp{+++}; among those, it 3257chooses the shortest name of an existing file. Otherwise, if there is 3258an @samp{Index:} line in the leading text, @code{patch} tries to use the 3259file name from that line. If @code{patch} cannot figure out the name of 3260an existing file from the leading text, it prompts you for the name of 3261the file to patch. 3262 3263If the input file does not exist or is read-only, and a suitable RCS or 3264SCCS file exists, @code{patch} attempts to check out or get the file 3265before proceeding. 3266 3267By default, @code{patch} replaces the original input file with the 3268patched version, after renaming the original file into a backup file 3269(@pxref{Backups}, for a description of how @code{patch} names backup 3270files). You can also specify where to put the output with the @samp{-o 3271@var{output-file}} or @samp{--output=@var{output-file}} option. 3272 3273@menu 3274* patch Directories:: Changing directory and stripping directories. 3275* Backups:: Backup file names. 3276* Rejects:: Reject file names. 3277* patch Options:: Summary table of options to @code{patch}. 3278@end menu 3279 3280@node patch Directories, Backups, , Invoking patch 3281@section Applying Patches in Other Directories 3282@cindex directories and patch 3283@cindex patching directories 3284 3285The @samp{-d @var{directory}} or @samp{--directory=@var{directory}} 3286option to @code{patch} makes directory @var{directory} the current 3287directory for interpreting both file names in the patch file, and file 3288names given as arguments to other options (such as @samp{-B} and 3289@samp{-o}). For example, while in a news reading program, you can patch 3290a file in the @file{/usr/src/emacs} directory directly from the article 3291containing the patch like this: 3292 3293@example 3294| patch -d /usr/src/emacs 3295@end example 3296 3297Sometimes the file names given in a patch contain leading directories, 3298but you keep your files in a directory different from the one given in 3299the patch. In those cases, you can use the 3300@samp{-p@r{[}@var{number}@r{]}} or @samp{--strip@r{[}=@var{number}@r{]}} 3301option to set the file name strip count to @var{number}. The strip 3302count tells @code{patch} how many slashes, along with the directory 3303names between them, to strip from the front of file names. @samp{-p} 3304with no @var{number} given is equivalent to @samp{-p0}. By default, 3305@code{patch} strips off all leading directories, leaving just the base file 3306names, except that when a file name given in the patch is a relative 3307file name and all of its leading directories already exist, @code{patch} does 3308not strip off the leading directory. (A @dfn{relative} file name is one 3309that does not start with a slash.) 3310 3311@code{patch} looks for each file (after any slashes have been stripped) 3312in the current directory, or if you used the @samp{-d @var{directory}} 3313option, in that directory. 3314 3315For example, suppose the file name in the patch file is 3316@file{/gnu/src/emacs/etc/NEWS}. Using @samp{-p} or @samp{-p0} gives the 3317entire file name unmodified, @samp{-p1} gives 3318@file{gnu/src/emacs/etc/NEWS} (no leading slash), @samp{-p4} gives 3319@file{etc/NEWS}, and not specifying @samp{-p} at all gives @file{NEWS}. 3320 3321@node Backups, Rejects, patch Directories, Invoking patch 3322@section Backup File Names 3323@cindex backup file names 3324 3325Normally, @code{patch} renames an original input file into a backup file 3326by appending to its name the extension @samp{.orig}, or @samp{~} on 3327systems that do not support long file names. The @samp{-b 3328@var{backup-suffix}} or @samp{--suffix=@var{backup-suffix}} option uses 3329@var{backup-suffix} as the backup extension instead. 3330 3331Alternately, you can specify the extension for backup files with the 3332@code{SIMPLE_BACKUP_SUFFIX} environment variable, which the options 3333override. 3334 3335@code{patch} can also create numbered backup files the way GNU Emacs 3336does. With this method, instead of having a single backup of each file, 3337@code{patch} makes a new backup file name each time it patches a file. 3338For example, the backups of a file named @file{sink} would be called, 3339successively, @file{sink.~1~}, @file{sink.~2~}, @file{sink.~3~}, etc. 3340 3341The @samp{-V @var{backup-style}} or 3342@samp{--version-control=@var{backup-style}} option takes as an argument 3343a method for creating backup file names. You can alternately control 3344the type of backups that @code{patch} makes with the 3345@code{VERSION_CONTROL} environment variable, which the @samp{-V} option 3346overrides. The value of the @code{VERSION_CONTROL} environment variable 3347and the argument to the @samp{-V} option are like the GNU Emacs 3348@code{version-control} variable (@pxref{Backups, 3349emacs, The GNU Emacs Manual}, for more information on backup versions in 3350Emacs). They also recognize synonyms that are more descriptive. The 3351valid values are listed below; unique abbreviations are acceptable. 3352 3353@table @samp 3354@item t 3355@itemx numbered 3356Always make numbered backups. 3357 3358@item nil 3359@itemx existing 3360Make numbered backups of files that already have them, simple backups of 3361the others. This is the default. 3362 3363@item never 3364@itemx simple 3365Always make simple backups. 3366@end table 3367 3368Alternately, you can tell @code{patch} to prepend a prefix, such as a 3369directory name, to produce backup file names. The @samp{-B 3370@var{backup-prefix}} or @samp{--prefix=@var{backup-prefix}} option makes 3371backup files by prepending @var{backup-prefix} to them. If you use this 3372option, @code{patch} ignores any @samp{-b} option that you give. 3373 3374If the backup file already exists, @code{patch} creates a new backup 3375file name by changing the first lowercase letter in the last component 3376of the file name into uppercase. If there are no more lowercase letters 3377in the name, it removes the first character from the name. It repeats 3378this process until it comes up with a backup file name that does not 3379already exist. 3380 3381If you specify the output file with the @samp{-o} option, that file is 3382the one that is backed up, not the input file. 3383 3384@node Rejects, patch Options, Backups, Invoking patch 3385@section Reject File Names 3386@cindex reject file names 3387 3388The names for reject files (files containing patches that @code{patch} 3389could not find a place to apply) are normally the name of the output 3390file with @samp{.rej} appended (or @samp{#} on systems that do not 3391support long file names). 3392 3393Alternatively, you can tell @code{patch} to place all of the rejected 3394patches in a single file. The @samp{-r @var{reject-file}} or 3395@samp{--reject-file=@var{reject-file}} option uses @var{reject-file} as 3396the reject file name. 3397 3398@node patch Options, , Rejects, Invoking patch 3399@section Options to @code{patch} 3400@cindex @code{patch} options 3401@cindex options for @code{patch} 3402 3403Here is a summary of all of the options that @code{patch} accepts. 3404Older versions of @code{patch} do not accept long-named options or the 3405@samp{-t}, @samp{-E}, or @samp{-V} options. 3406 3407Multiple single-letter options that do not take an argument can be 3408combined into a single command line argument (with only one dash). 3409Brackets ([ and ]) indicate that an option takes an optional argument. 3410 3411@table @samp 3412@item -b @var{backup-suffix} 3413Use @var{backup-suffix} as the backup extension instead of 3414@samp{.orig} or @samp{~}. @xref{Backups}. 3415 3416@item -B @var{backup-prefix} 3417Use @var{backup-prefix} as a prefix to the backup file name. If this 3418option is specified, any @samp{-b} option is ignored. @xref{Backups}. 3419 3420@item --batch 3421Do not ask any questions. @xref{patch Messages}. 3422 3423@item -c 3424@itemx --context 3425Interpret the patch file as a context diff. @xref{patch Input}. 3426 3427@item -d @var{directory} 3428@itemx --directory=@var{directory} 3429Makes directory @var{directory} the current directory for interpreting 3430both file names in the patch file, and file names given as arguments to 3431other options. @xref{patch Directories}. 3432 3433@item -D @var{name} 3434Make merged if-then-else output using @var{format}. @xref{If-then-else}. 3435 3436@item --debug=@var{number} 3437Set internal debugging flags. Of interest only to @code{patch} 3438patchers. 3439 3440@item -e 3441@itemx --ed 3442Interpret the patch file as an @code{ed} script. @xref{patch Input}. 3443 3444@item -E 3445Remove output files that are empty after the patches have been applied. 3446@xref{Empty Files}. 3447 3448@item -f 3449Assume that the user knows exactly what he or she is doing, and do not 3450ask any questions. @xref{patch Messages}. 3451 3452@item -F @var{lines} 3453Set the maximum fuzz factor to @var{lines}. @xref{Inexact}. 3454 3455@item --force 3456Assume that the user knows exactly what he or she is doing, and do not 3457ask any questions. @xref{patch Messages}. 3458 3459@item --forward 3460Ignore patches that @code{patch} thinks are reversed or already applied. 3461See also @samp{-R}. @xref{Reversed Patches}. 3462 3463@item --fuzz=@var{lines} 3464Set the maximum fuzz factor to @var{lines}. @xref{Inexact}. 3465 3466@item --help 3467Print a summary of the options that @code{patch} recognizes, then exit. 3468 3469@item --ifdef=@var{name} 3470Make merged if-then-else output using @var{format}. @xref{If-then-else}. 3471 3472@item --ignore-white-space 3473@itemx -l 3474Let any sequence of white space in the patch file match any sequence of 3475white space in the input file. @xref{Changed White Space}. 3476 3477@item -n 3478@itemx --normal 3479Interpret the patch file as a normal diff. @xref{patch Input}. 3480 3481@item -N 3482Ignore patches that @code{patch} thinks are reversed or already applied. 3483See also @samp{-R}. @xref{Reversed Patches}. 3484 3485@item -o @var{output-file} 3486@itemx --output=@var{output-file} 3487Use @var{output-file} as the output file name. @xref{patch Options}. 3488 3489@item -p@r{[}@var{number}@r{]} 3490Set the file name strip count to @var{number}. @xref{patch Directories}. 3491 3492@item --prefix=@var{backup-prefix} 3493Use @var{backup-prefix} as a prefix to the backup file name. If this 3494option is specified, any @samp{-b} option is ignored. @xref{Backups}. 3495 3496@item --quiet 3497Work silently unless an error occurs. @xref{patch Messages}. 3498 3499@item -r @var{reject-file} 3500Use @var{reject-file} as the reject file name. @xref{Rejects}. 3501 3502@item -R 3503Assume that this patch was created with the old and new files swapped. 3504@xref{Reversed Patches}. 3505 3506@item --reject-file=@var{reject-file} 3507Use @var{reject-file} as the reject file name. @xref{Rejects}. 3508 3509@item --remove-empty-files 3510Remove output files that are empty after the patches have been applied. 3511@xref{Empty Files}. 3512 3513@item --reverse 3514Assume that this patch was created with the old and new files swapped. 3515@xref{Reversed Patches}. 3516 3517@item -s 3518Work silently unless an error occurs. @xref{patch Messages}. 3519 3520@item -S 3521Ignore this patch from the patch file, but continue looking for the next 3522patch in the file. @xref{Multiple Patches}. 3523 3524@item --silent 3525Work silently unless an error occurs. @xref{patch Messages}. 3526 3527@item --skip 3528Ignore this patch from the patch file, but continue looking for the next 3529patch in the file. @xref{Multiple Patches}. 3530 3531@item --strip@r{[}=@var{number}@r{]} 3532Set the file name strip count to @var{number}. @xref{patch Directories}. 3533 3534@item --suffix=@var{backup-suffix} 3535Use @var{backup-suffix} as the backup extension instead of 3536@samp{.orig} or @samp{~}. @xref{Backups}. 3537 3538@item -t 3539Do not ask any questions. @xref{patch Messages}. 3540 3541@item -u 3542@itemx --unified 3543Interpret the patch file as a unified diff. @xref{patch Input}. 3544 3545@item -v 3546Output the revision header and patch level of @code{patch}. 3547 3548@item -V @var{backup-style} 3549Select the kind of backups to make. @xref{Backups}. 3550 3551@item --version 3552Output the revision header and patch level of @code{patch}, then exit. 3553 3554@item --version=control=@var{backup-style} 3555Select the kind of backups to make. @xref{Backups}. 3556 3557@item -x @var{number} 3558Set internal debugging flags. Of interest only to @code{patch} 3559patchers. 3560@end table 3561 3562@node Invoking sdiff, Incomplete Lines, Invoking patch, Top 3563@chapter Invoking @code{sdiff} 3564@cindex invoking @code{sdiff} 3565@cindex @code{sdiff} invocation 3566 3567The @code{sdiff} command merges two files and interactively outputs the 3568results. Its arguments are as follows: 3569 3570@example 3571sdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file} 3572@end example 3573 3574This merges @var{from-file} with @var{to-file}, with output to @var{outfile}. 3575If @var{from-file} is a directory and @var{to-file} is not, @code{sdiff} 3576compares the file in @var{from-file} whose file name is that of @var{to-file}, 3577and vice versa. @var{from-file} and @var{to-file} may not both be 3578directories. 3579 3580@code{sdiff} options begin with @samp{-}, so normally @var{from-file} 3581and @var{to-file} may not begin with @samp{-}. However, @samp{--} as an 3582argument by itself treats the remaining arguments as file names even if 3583they begin with @samp{-}. You may not use @samp{-} as an input file. 3584 3585An exit status of 0 means no differences were found, 1 means some 3586differences were found, and 2 means trouble. 3587 3588@code{sdiff} without @samp{-o} (or @samp{--output}) produces a 3589side-by-side difference. This usage is obsolete; use @samp{diff 3590--side-by-side} instead. 3591 3592@menu 3593* sdiff Options:: Summary of options to @code{diff}. 3594@end menu 3595 3596@node sdiff Options, , , Invoking sdiff 3597@section Options to @code{sdiff} 3598@cindex @code{sdiff} options 3599@cindex options for @code{sdiff} 3600 3601Below is a summary of all of the options that GNU @code{sdiff} accepts. 3602Each option has two equivalent names, one of which is a single 3603letter preceded by @samp{-}, and the other of which is a long name 3604preceded by @samp{--}. Multiple single letter options (unless they take 3605an argument) can be combined into a single command line argument. Long 3606named options can be abbreviated to any unique prefix of their name. 3607 3608@table @samp 3609@item -a 3610Treat all files as text and compare them line-by-line, even if they 3611do not appear to be text. @xref{Binary}. 3612 3613@item -b 3614Ignore changes in amount of white space. @xref{White Space}. 3615 3616@item -B 3617Ignore changes that just insert or delete blank lines. @xref{Blank 3618Lines}. 3619 3620@item -d 3621Change the algorithm to perhaps find a smaller set of changes. This 3622makes @code{sdiff} slower (sometimes much slower). @xref{diff 3623Performance}. 3624 3625@item -H 3626Use heuristics to speed handling of large files that have numerous 3627scattered small changes. @xref{diff Performance}. 3628 3629@item --expand-tabs 3630Expand tabs to spaces in the output, to preserve the alignment of tabs 3631in the input files. @xref{Tabs}. 3632 3633@item -i 3634Ignore changes in case; consider upper- and lower-case to be the same. 3635@xref{Case Folding}. 3636 3637@item -I @var{regexp} 3638Ignore changes that just insert or delete lines that match @var{regexp}. 3639@xref{Specified Folding}. 3640 3641@item --ignore-all-space 3642Ignore white space when comparing lines. @xref{White Space}. 3643 3644@item --ignore-blank-lines 3645Ignore changes that just insert or delete blank lines. @xref{Blank 3646Lines}. 3647 3648@item --ignore-case 3649Ignore changes in case; consider upper- and lower-case to be the same. 3650@xref{Case Folding}. 3651 3652@item --ignore-matching-lines=@var{regexp} 3653Ignore changes that just insert or delete lines that match @var{regexp}. 3654@xref{Specified Folding}. 3655 3656@item --ignore-space-change 3657Ignore changes in amount of white space. 3658@xref{White Space}. 3659 3660@item -l 3661@itemx --left-column 3662Print only the left column of two common lines. 3663@xref{Side by Side Format}. 3664 3665@item --minimal 3666Change the algorithm to perhaps find a smaller set of changes. This 3667makes @code{sdiff} slower (sometimes much slower). @xref{diff 3668Performance}. 3669 3670@item -o @var{file} 3671@itemx --output=@var{file} 3672Put merged output into @var{file}. This option is required for merging. 3673 3674@item -s 3675@itemx --suppress-common-lines 3676Do not print common lines. @xref{Side by Side Format}. 3677 3678@item --speed-large-files 3679Use heuristics to speed handling of large files that have numerous 3680scattered small changes. @xref{diff Performance}. 3681 3682@item -t 3683Expand tabs to spaces in the output, to preserve the alignment of tabs 3684in the input files. @xref{Tabs}. 3685 3686@item --text 3687Treat all files as text and compare them line-by-line, even if they 3688do not appear to be text. @xref{Binary}. 3689 3690@item -v 3691@itemx --version 3692Output the version number of @code{sdiff}. 3693 3694@item -w @var{columns} 3695@itemx --width=@var{columns} 3696Use an output width of @var{columns}. @xref{Side by Side Format}. 3697Note that for historical reasons, this option is @samp{-W} in @code{diff}, 3698@samp{-w} in @code{sdiff}. 3699 3700@item -W 3701Ignore horizontal white space when comparing lines. @xref{White Space}. 3702Note that for historical reasons, this option is @samp{-w} in @code{diff}, 3703@samp{-W} in @code{sdiff}. 3704@end table 3705 3706@node Incomplete Lines, Projects, Invoking sdiff, Top 3707@chapter Incomplete Lines 3708@cindex incomplete lines 3709@cindex full lines 3710@cindex newline treatment by @code{diff} 3711 3712When an input file ends in a non-newline character, its last line is 3713called an @dfn{incomplete line} because its last character is not a 3714newline. All other lines are called @dfn{full lines} and end in a 3715newline character. Incomplete lines do not match full lines unless 3716differences in white space are ignored (@pxref{White Space}). 3717 3718An incomplete line is normally distinguished on output from a full line 3719by a following line that starts with @samp{\}. However, the RCS format 3720(@pxref{RCS}) outputs the incomplete line as-is, without any trailing 3721newline or following line. The side by side format normally represents 3722incomplete lines as-is, but in some cases uses a @samp{\} or @samp{/} 3723gutter marker; @xref{Side by Side}. The if-then-else line format 3724preserves a line's incompleteness with @samp{%L}, and discards the 3725newline with @samp{%l}; @xref{Line Formats}. Finally, with the 3726@code{ed} and forward @code{ed} output formats (@pxref{Output Formats}) 3727@code{diff} cannot represent an incomplete line, so it pretends there 3728was a newline and reports an error. 3729 3730For example, suppose @file{F} and @file{G} are one-byte files that 3731contain just @samp{f} and @samp{g}, respectively. Then @samp{diff F G} 3732outputs 3733 3734@example 37351c1 3736< f 3737\ No newline at end of file 3738--- 3739> g 3740\ No newline at end of file 3741@end example 3742 3743@noindent 3744(The exact message may differ in non-English locales.) 3745@samp{diff -n F G} outputs the following without a trailing newline: 3746 3747@example 3748d1 1 3749a1 1 3750g 3751@end example 3752 3753@samp{diff -e F G} reports two errors and outputs the following: 3754 3755@example 37561c 3757g 3758. 3759@end example 3760 3761@node Projects, Concept Index, Incomplete Lines, Top 3762@chapter Future Projects 3763 3764Here are some ideas for improving GNU @code{diff} and @code{patch}. The 3765GNU project has identified some improvements as potential programming 3766projects for volunteers. You can also help by reporting any bugs that 3767you find. 3768 3769If you are a programmer and would like to contribute something to the 3770GNU project, please consider volunteering for one of these projects. If 3771you are seriously contemplating work, please write to 3772@samp{gnu@@prep.ai.mit.edu} to coordinate with other volunteers. 3773 3774@menu 3775* Shortcomings:: Suggested projects for improvements. 3776* Bugs:: Reporting bugs. 3777@end menu 3778 3779@node Shortcomings, Bugs, , Projects 3780@section Suggested Projects for Improving GNU @code{diff} and @code{patch} 3781@cindex projects for directories 3782 3783One should be able to use GNU @code{diff} to generate a patch from any 3784pair of directory trees, and given the patch and a copy of one such 3785tree, use @code{patch} to generate a faithful copy of the other. 3786Unfortunately, some changes to directory trees cannot be expressed using 3787current patch formats; also, @code{patch} does not handle some of the 3788existing formats. These shortcomings motivate the following suggested 3789projects. 3790 3791@menu 3792* Changing Structure:: Handling changes to the directory structure. 3793* Special Files:: Handling symbolic links, device special files, etc. 3794* Unusual File Names:: Handling file names that contain unusual characters. 3795* Arbitrary Limits:: Patching non-text files. 3796* Large Files:: Handling files that do not fit in memory. 3797* Ignoring Changes:: Ignoring certain changes while showing others. 3798@end menu 3799 3800@node Changing Structure, Special Files, , Shortcomings 3801@subsection Handling Changes to the Directory Structure 3802@cindex directory structure changes 3803 3804@code{diff} and @code{patch} do not handle some changes to directory 3805structure. For example, suppose one directory tree contains a directory 3806named @samp{D} with some subsidiary files, and another contains a file 3807with the same name @samp{D}. @samp{diff -r} does not output enough 3808information for @code{patch} to transform the the directory subtree into 3809the file. 3810 3811There should be a way to specify that a file has been deleted without 3812having to include its entire contents in the patch file. There should 3813also be a way to tell @code{patch} that a file was renamed, even if 3814there is no way for @code{diff} to generate such information. 3815 3816These problems can be fixed by extending the @code{diff} output format 3817to represent changes in directory structure, and extending @code{patch} 3818to understand these extensions. 3819 3820@node Special Files, Unusual File Names, Changing Structure, Shortcomings 3821@subsection Files that are Neither Directories Nor Regular Files 3822@cindex special files 3823 3824Some files are neither directories nor regular files: they are unusual 3825files like symbolic links, device special files, named pipes, and 3826sockets. Currently, @code{diff} treats symbolic links like regular files; 3827it treats other special files like regular files if they are specified 3828at the top level, but simply reports their presence when comparing 3829directories. This means that @code{patch} cannot represent changes 3830to such files. For example, if you change which file a symbolic link 3831points to, @code{diff} outputs the difference between the two files, 3832instead of the change to the symbolic link. 3833 3834@c This might not be a good idea; is it wise for root to install devices 3835@c this way? 3836@code{diff} should optionally report changes to special files specially, 3837and @code{patch} should be extended to understand these extensions. 3838 3839@node Unusual File Names, Arbitrary Limits, Special Files, Shortcomings 3840@subsection File Names that Contain Unusual Characters 3841@cindex file names with unusual characters 3842 3843When a file name contains an unusual character like a newline or 3844white space, @samp{diff -r} generates a patch that @code{patch} cannot 3845parse. The problem is with format of @code{diff} output, not just with 3846@code{patch}, because with odd enough file names one can cause 3847@code{diff} to generate a patch that is syntactically correct but 3848patches the wrong files. The format of @code{diff} output should be 3849extended to handle all possible file names. 3850 3851@node Arbitrary Limits, Large Files, Unusual File Names, Shortcomings 3852@subsection Arbitrary Limits 3853@cindex binary file patching 3854 3855GNU @code{diff} can analyze files with arbitrarily long lines and files 3856that end in incomplete lines. However, @code{patch} cannot patch such 3857files. The @code{patch} internal limits on line lengths should be 3858removed, and @code{patch} should be extended to parse @code{diff} 3859reports of incomplete lines. 3860 3861@node Large Files, Ignoring Changes, Arbitrary Limits, Shortcomings 3862@subsection Handling Files that Do Not Fit in Memory 3863@cindex large files 3864 3865@code{diff} operates by reading both files into memory. This method 3866fails if the files are too large, and @code{diff} should have a fallback. 3867 3868One way to do this is to scan the files sequentially to compute hash 3869codes of the lines and put the lines in equivalence classes based only 3870on hash code. Then compare the files normally. This does produce some 3871false matches. 3872 3873Then scan the two files sequentially again, checking each match to see 3874whether it is real. When a match is not real, mark both the 3875``matching'' lines as changed. Then build an edit script as usual. 3876 3877The output routines would have to be changed to scan the files 3878sequentially looking for the text to print. 3879 3880@node Ignoring Changes,, Large Files, Shortcomings 3881@subsection Ignoring Certain Changes 3882 3883It would be nice to have a feature for specifying two strings, one in 3884@var{from-file} and one in @var{to-file}, which should be considered to 3885match. Thus, if the two strings are @samp{foo} and @samp{bar}, then if 3886two lines differ only in that @samp{foo} in file 1 corresponds to 3887@samp{bar} in file 2, the lines are treated as identical. 3888 3889It is not clear how general this feature can or should be, or 3890what syntax should be used for it. 3891 3892@node Bugs, , Shortcomings, Projects 3893@section Reporting Bugs 3894@cindex bug reports 3895@cindex reporting bugs 3896 3897If you think you have found a bug in GNU @code{cmp}, @code{diff}, 3898@code{diff3}, @code{sdiff}, or @code{patch}, please report it by 3899electronic mail to @samp{bug-gnu-utils@@prep.ai.mit.edu}. Send as 3900precise a description of the problem as you can, including sample input 3901files that produce the bug, if applicable. 3902 3903Because Larry Wall has not released a new version of @code{patch} since 3904mid 1988 and the GNU version of @code{patch} has been changed since 3905then, please send bug reports for @code{patch} by electronic mail to 3906both @samp{bug-gnu-utils@@prep.ai.mit.edu} and 3907@samp{lwall@@netlabs.com}. 3908 3909@node Concept Index, , Projects, Top 3910@unnumbered Concept Index 3911 3912@printindex cp 3913 3914@shortcontents 3915@contents 3916@bye 3917