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