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 2468Edit a copy of the left version, then copy the result to the output. 2469 2470@item er 2471Edit a copy of the right version, then copy the result to the output. 2472 2473@item l 2474Copy the left version to the output. 2475 2476@item q 2477Quit. 2478 2479@item r 2480Copy the right version to the output. 2481 2482@item s 2483Silently copy common lines. 2484 2485@item v 2486Verbosely copy common lines. This is the default. 2487@end table 2488 2489@vindex EDITOR 2490The text editor invoked is specified by the @env{EDITOR} environment 2491variable if it is set. The default is system-dependent. 2492 2493@node Merging with patch 2494@chapter Merging with @command{patch} 2495 2496@command{patch} takes comparison output produced by @command{diff} and applies 2497the differences to a copy of the original file, producing a patched 2498version. With @command{patch}, you can distribute just the changes to a 2499set of files instead of distributing the entire file set; your 2500correspondents can apply @command{patch} to update their copy of the files 2501with your changes. @command{patch} automatically determines the diff 2502format, skips any leading or trailing headers, and uses the headers to 2503determine which file to patch. This lets your correspondents feed a 2504mail message containing a difference listing directly to 2505@command{patch}. 2506 2507@command{patch} detects and warns about common problems like forward 2508patches. It saves any patches that it could not apply. It can also maintain a 2509@code{patchlevel.h} file to ensure that your correspondents apply 2510diffs in the proper order. 2511 2512@command{patch} accepts a series of diffs in its standard input, usually 2513separated by headers that specify which file to patch. It applies 2514@command{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not 2515exactly match the original file, @command{patch} uses heuristics to try to 2516patch the file as well as it can. If no approximate match can be found, 2517@command{patch} rejects the hunk and skips to the next hunk. @command{patch} 2518normally replaces each file @var{f} with its new version, putting reject 2519hunks (if any) into @samp{@var{f}.rej}. 2520 2521@xref{Invoking patch}, for detailed information on the options to 2522@command{patch}. 2523 2524@menu 2525* patch Input:: Selecting the type of @command{patch} input. 2526* Revision Control:: Getting files from @acronym{RCS}, @acronym{SCCS}, etc. 2527* Imperfect:: Dealing with imperfect patches. 2528* Creating and Removing:: Creating and removing files with a patch. 2529* Patching Time Stamps:: Updating time stamps on patched files. 2530* Multiple Patches:: Handling multiple patches in a file. 2531* patch Directories:: Changing directory and stripping directories. 2532* Backups:: Whether backup files are made. 2533* Backup Names:: Backup file names. 2534* Reject Names:: Reject file names. 2535* patch Messages:: Messages and questions @command{patch} can produce. 2536* patch and POSIX:: Conformance to the @acronym{POSIX} standard. 2537* patch and Tradition:: @acronym{GNU} versus traditional @command{patch}. 2538@end menu 2539 2540@node patch Input 2541@section Selecting the @command{patch} Input Format 2542@cindex @command{patch} input format 2543 2544@command{patch} normally determines which @command{diff} format the patch 2545file uses by examining its contents. For patch files that contain 2546particularly confusing leading text, you might need to use one of the 2547following options to force @command{patch} to interpret the patch file as a 2548certain format of diff. The output formats listed here are the only 2549ones that @command{patch} can understand. 2550 2551@table @option 2552@item -c 2553@itemx --context 2554context diff. 2555 2556@item -e 2557@itemx --ed 2558@command{ed} script. 2559 2560@item -n 2561@itemx --normal 2562normal diff. 2563 2564@item -u 2565@itemx --unified 2566unified diff. 2567@end table 2568 2569@node Revision Control 2570@section Revision Control 2571@cindex revision control 2572@cindex version control 2573@cindex @acronym{RCS} 2574@cindex ClearCase 2575@cindex @acronym{SCCS} 2576 2577If a nonexistent input file is under a revision control system 2578supported by @command{patch}, @command{patch} normally asks the user 2579whether to get (or check out) the file from the revision control 2580system. Patch currently supports @acronym{RCS}, ClearCase and 2581@acronym{SCCS}. Under @acronym{RCS} and @acronym{SCCS}, 2582@command{patch} also asks when the input file is read-only and matches 2583the default version in the revision control system. 2584 2585@vindex PATCH_GET 2586The @option{-g @var{num}} or @option{--get=@var{num}} option affects access 2587to files under supported revision control systems. If @var{num} is 2588positive, @command{patch} gets the file without asking the user; if 2589zero, @command{patch} neither asks the user nor gets the file; and if 2590negative, @command{patch} asks the user before getting the file. The 2591default value of @var{num} is given by the value of the 2592@env{PATCH_GET} environment variable if it is set; if not, the default 2593value is zero if @command{patch} is conforming to @acronym{POSIX}, negative 2594otherwise. @xref{patch and POSIX}. 2595 2596@vindex VERSION_CONTROL 2597The choice of revision control system is unaffected by the 2598@env{VERSION_CONTROL} environment variable (@pxref{Backup Names}). 2599 2600@node Imperfect 2601@section Applying Imperfect Patches 2602@cindex imperfect patch application 2603 2604@command{patch} tries to skip any leading text in the patch file, 2605apply the diff, and then skip any trailing text. Thus you can feed a 2606mail message directly to @command{patch}, and it should work. If the 2607entire diff is indented by a constant amount of white space, 2608@command{patch} automatically ignores the indentation. If a context 2609diff contains trailing carriage return on each line, @command{patch} 2610automatically ignores the carriage return. If a context diff has been 2611encapsulated by prepending @w{@samp{- }} to lines beginning with @samp{-} 2612as per @uref{ftp://ftp.isi.edu/in-notes/rfc934.txt, Internet RFC 934}, 2613@command{patch} automatically unencapsulates the input. 2614 2615However, certain other types of imperfect input require user 2616intervention or testing. 2617 2618@menu 2619* Changed White Space:: When tabs and spaces don't match exactly. 2620* Reversed Patches:: Applying reversed patches correctly. 2621* Inexact:: Helping @command{patch} find close matches. 2622* Dry Runs:: Predicting what @command{patch} will do. 2623@end menu 2624 2625@node Changed White Space 2626@subsection Applying Patches with Changed White Space 2627@cindex white space in patches 2628 2629Sometimes mailers, editors, or other programs change spaces into tabs, 2630or vice versa. If this happens to a patch file or an input file, the 2631files might look the same, but @command{patch} will not be able to match 2632them properly. If this problem occurs, use the @option{-l} or 2633@option{--ignore-white-space} option, which makes @command{patch} compare 2634blank characters (i.e.@: spaces and tabs) loosely so that any nonempty 2635sequence of blanks in the patch file matches any nonempty sequence of 2636blanks in the input files. Non-blank 2637characters must still match exactly. Each line of the context must 2638still match a line in the input file. 2639 2640@node Reversed Patches 2641@subsection Applying Reversed Patches 2642@cindex reversed patches 2643 2644Sometimes people run @command{diff} with the new file first instead of 2645second. This creates a diff that is ``reversed''. To apply such 2646patches, give @command{patch} the @option{-R} or @option{--reverse} option. 2647@command{patch} then attempts to swap each hunk around before applying it. 2648Rejects come out in the swapped format. 2649 2650Often @command{patch} can guess that the patch is reversed. If the first 2651hunk of a patch fails, @command{patch} reverses the hunk to see if it can 2652apply it that way. If it can, @command{patch} asks you if you want to have 2653the @option{-R} option set; if it can't, @command{patch} continues to apply 2654the patch normally. This method cannot detect a reversed patch if it is 2655a normal diff and the first command is an append (which should have been 2656a delete) since appends always succeed, because a null context matches 2657anywhere. But most patches add or change lines rather than delete them, 2658so most reversed normal diffs begin with a delete, which fails, and 2659@command{patch} notices. 2660 2661If you apply a patch that you have already applied, @command{patch} thinks 2662it is a reversed patch and offers to un-apply the patch. This could be 2663construed as a feature. If you did this inadvertently and you don't 2664want to un-apply the patch, just answer @samp{n} to this offer and to 2665the subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the 2666@command{patch} process. 2667 2668@node Inexact 2669@subsection Helping @command{patch} Find Inexact Matches 2670@cindex inexact patches 2671@cindex fuzz factor when patching 2672 2673For context diffs, and to a lesser extent normal diffs, @command{patch} can 2674detect when the line numbers mentioned in the patch are incorrect, and 2675it attempts to find the correct place to apply each hunk of the patch. 2676As a first guess, it takes the line number mentioned in the hunk, plus 2677or minus any offset used in applying the previous hunk. If that is not 2678the correct place, @command{patch} scans both forward and backward for a 2679set of lines matching the context given in the hunk. 2680 2681First @command{patch} looks for a place where all lines of the context 2682match. If it cannot find such a place, and it is reading a context or 2683unified diff, and the maximum fuzz factor is set to 1 or more, then 2684@command{patch} makes another scan, ignoring the first and last line of 2685context. If that fails, and the maximum fuzz factor is set to 2 or 2686more, it makes another scan, ignoring the first two and last two lines 2687of context are ignored. It continues similarly if the maximum fuzz 2688factor is larger. 2689 2690The @option{-F @var{lines}} or @option{--fuzz=@var{lines}} option sets the 2691maximum fuzz factor to @var{lines}. This option only applies to context 2692and unified diffs; it ignores up to @var{lines} lines while looking for 2693the place to install a hunk. Note that a larger fuzz factor increases 2694the odds of making a faulty patch. The default fuzz factor is 2; there 2695is no point to setting it to more than the number of lines of context 2696in the diff, ordinarily 3. 2697 2698If @command{patch} cannot find a place to install a hunk of the patch, it 2699writes the hunk out to a reject file (@pxref{Reject Names}, for information 2700on how reject files are named). It writes out rejected hunks in context 2701format no matter what form the input patch is in. If the input is a 2702normal or @command{ed} diff, many of the contexts are simply null. The 2703line numbers on the hunks in the reject file may be different from those 2704in the patch file: they show the approximate location where @command{patch} 2705thinks the failed hunks belong in the new file rather than in the old 2706one. 2707 2708If the @option{--verbose} option is given, then 2709as it completes each hunk @command{patch} tells you whether the hunk 2710succeeded or failed, and if it failed, on which line (in the new file) 2711@command{patch} thinks the hunk should go. If this is different from the 2712line number specified in the diff, it tells you the offset. A single 2713large offset @emph{may} indicate that @command{patch} installed a hunk in 2714the wrong place. @command{patch} also tells you if it used a fuzz factor 2715to make the match, in which case you should also be slightly suspicious. 2716 2717@command{patch} cannot tell if the line numbers are off in an @command{ed} 2718script, and can only detect wrong line numbers in a normal diff when it 2719finds a change or delete command. It may have the same problem with a 2720context diff using a fuzz factor equal to or greater than the number of 2721lines of context shown in the diff (typically 3). In these cases, you 2722should probably look at a context diff between your original and patched 2723input files to see if the changes make sense. Compiling without errors 2724is a pretty good indication that the patch worked, but not a guarantee. 2725 2726A patch against an empty file applies to a nonexistent file, and vice 2727versa. @xref{Creating and Removing}. 2728 2729@command{patch} usually produces the correct results, even when it must 2730make many guesses. However, the results are guaranteed only when 2731the patch is applied to an exact copy of the file that the patch was 2732generated from. 2733 2734@node Dry Runs 2735@subsection Predicting what @command{patch} will do 2736@cindex testing @command{patch} 2737@cindex dry runs for @command{patch} 2738 2739It may not be obvious in advance what @command{patch} will do with a 2740complicated or poorly formatted patch. If you are concerned that the 2741input might cause @command{patch} to modify the wrong files, you can 2742use the @option{--dry-run} option, which causes @command{patch} to 2743print the results of applying patches without actually changing any 2744files. You can then inspect the diagnostics generated by the dry run 2745to see whether @command{patch} will modify the files that you expect. 2746If the patch does not do what you want, you can modify the patch (or 2747the other options to @command{patch}) and try another dry run. Once 2748you are satisfied with the proposed patch you can apply it by invoking 2749@command{patch} as before, but this time without the 2750@option{--dry-run} option. 2751 2752@node Creating and Removing 2753@section Creating and Removing Files 2754@cindex creating files 2755@cindex empty files, removing 2756@cindex removing empty files 2757 2758Sometimes when comparing two directories, a file may exist in one 2759directory but not the other. If you give @command{diff} the 2760@option{-N} or @option{--new-file} option, or if you supply an old or 2761new file that is named @file{/dev/null} or is empty and is dated the 2762Epoch (1970-01-01 00:00:00 UTC), @command{diff} outputs a patch that 2763adds or deletes the contents of this file. When given such a patch, 2764@command{patch} normally creates a new file or removes the old file. 2765However, when conforming to @acronym{POSIX} (@pxref{patch and POSIX}), 2766@command{patch} does not remove the old file, but leaves it empty. 2767The @option{-E} or @option{--remove-empty-files} option causes 2768@command{patch} to remove output files that are empty after applying a 2769patch, even if the patch does not appear to be one that removed the 2770file. 2771 2772If the patch appears to create a file that already exists, 2773@command{patch} asks for confirmation before applying the patch. 2774 2775@node Patching Time Stamps 2776@section Updating Time Stamps on Patched Files 2777@cindex time stamps on patched files 2778 2779When @command{patch} updates a file, it normally sets the file's 2780last-modified time stamp to the current time of day. If you are using 2781@command{patch} to track a software distribution, this can cause 2782@command{make} to incorrectly conclude that a patched file is out of 2783date. For example, if @file{syntax.c} depends on @file{syntax.y}, and 2784@command{patch} updates @file{syntax.c} and then @file{syntax.y}, then 2785@file{syntax.c} will normally appear to be out of date with respect to 2786@file{syntax.y} even though its contents are actually up to date. 2787 2788The @option{-Z} or @option{--set-utc} option causes @command{patch} to 2789set a patched file's modification and access times to the time stamps 2790given in context diff headers. If the context diff headers do not 2791specify a time zone, they are assumed to use Coordinated Universal 2792Time (@acronym{UTC}, often known as @acronym{GMT}). 2793 2794The @option{-T} or @option{--set-time} option acts like @option{-Z} or 2795@option{--set-utc}, except that it assumes that the context diff 2796headers' time stamps use local time instead of @acronym{UTC}. This option 2797is not recommended, because patches using local time cannot easily be 2798used by people in other time zones, and because local time stamps are 2799ambiguous when local clocks move backwards during daylight-saving time 2800adjustments. If the context diff headers specify a time zone, this 2801option is equivalent to @option{-Z} or @option{--set-utc}. 2802 2803@command{patch} normally refrains from setting a file's time stamps if 2804the file's original last-modified time stamp does not match the time 2805given in the diff header, of if the file's contents do not exactly 2806match the patch. However, if the @option{-f} or @option{--force} 2807option is given, the file's time stamps are set regardless. 2808 2809Due to the limitations of the current @command{diff} format, 2810@command{patch} cannot update the times of files whose contents have 2811not changed. Also, if you set file time stamps to values other than 2812the current time of day, you should also remove (e.g., with @samp{make 2813clean}) all files that depend on the patched files, so that later 2814invocations of @command{make} do not get confused by the patched 2815files' times. 2816 2817@node Multiple Patches 2818@section Multiple Patches in a File 2819@cindex multiple patches 2820@cindex intuiting file names from patches 2821 2822If the patch file contains more than one patch, and if you do not 2823specify an input file on the command line, @command{patch} tries to 2824apply each patch as if they came from separate patch files. This 2825means that it determines the name of the file to patch for each patch, 2826and that it examines the leading text before each patch for file names 2827and prerequisite revision level (@pxref{Making Patches}, for more on 2828that topic). 2829 2830@command{patch} uses the following rules to intuit a file name from 2831the leading text before a patch. First, @command{patch} takes an 2832ordered list of candidate file names as follows: 2833 2834@itemize @bullet 2835@item 2836If the header is that of a context diff, @command{patch} takes the old 2837and new file names in the header. A name is ignored if it does not 2838have enough slashes to satisfy the @option{-p@var{num}} or 2839@option{--strip=@var{num}} option. The name @file{/dev/null} is also 2840ignored. 2841 2842@item 2843If there is an @samp{Index:} line in the leading garbage and if either 2844the old and new names are both absent or if @command{patch} is 2845conforming to @acronym{POSIX}, @command{patch} takes the name in the 2846@samp{Index:} line. 2847 2848@item 2849For the purpose of the following rules, the candidate file names are 2850considered to be in the order (old, new, index), regardless of the 2851order that they appear in the header. 2852@end itemize 2853 2854@noindent 2855Then @command{patch} selects a file name from the candidate list as 2856follows: 2857 2858@itemize @bullet 2859@item 2860If some of the named files exist, @command{patch} selects the first 2861name if conforming to @acronym{POSIX}, and the best name otherwise. 2862 2863@item 2864If @command{patch} is not ignoring @acronym{RCS}, ClearCase, and @acronym{SCCS} 2865(@pxref{Revision Control}), and no named files exist but an @acronym{RCS}, 2866ClearCase, or @acronym{SCCS} master is found, @command{patch} selects the 2867first named file with an @acronym{RCS}, ClearCase, or @acronym{SCCS} master. 2868 2869@item 2870If no named files exist, no @acronym{RCS}, ClearCase, or @acronym{SCCS} master 2871was found, some names are given, @command{patch} is not conforming to 2872@acronym{POSIX}, and the patch appears to create a file, @command{patch} 2873selects the best name requiring the creation of the fewest 2874directories. 2875 2876@item 2877If no file name results from the above heuristics, you are asked for 2878the name of the file to patch, and @command{patch} selects that name. 2879@end itemize 2880 2881To determine the @dfn{best} of a nonempty list of file names, 2882@command{patch} first takes all the names with the fewest path name 2883components; of those, it then takes all the names with the shortest 2884basename; of those, it then takes all the shortest names; finally, it 2885takes the first remaining name. 2886 2887@xref{patch and POSIX}, to see whether @command{patch} is conforming 2888to @acronym{POSIX}. 2889 2890@node patch Directories 2891@section Applying Patches in Other Directories 2892@cindex directories and patch 2893@cindex patching directories 2894 2895The @option{-d @var{directory}} or @option{--directory=@var{directory}} 2896option to @command{patch} makes directory @var{directory} the current 2897directory for interpreting both file names in the patch file, and file 2898names given as arguments to other options (such as @option{-B} and 2899@option{-o}). For example, while in a mail reading program, you can patch 2900a file in the @file{/usr/src/emacs} directory directly from a message 2901containing the patch like this: 2902 2903@example 2904| patch -d /usr/src/emacs 2905@end example 2906 2907Sometimes the file names given in a patch contain leading directories, 2908but you keep your files in a directory different from the one given in 2909the patch. In those cases, you can use the 2910@option{-p@var{number}} or @option{--strip=@var{number}} 2911option to set the file name strip count to @var{number}. The strip 2912count tells @command{patch} how many slashes, along with the directory 2913names between them, to strip from the front of file names. A sequence 2914of one or more adjacent slashes is counted as a single slash. By 2915default, @command{patch} strips off all leading directories, leaving 2916just the base file names. 2917 2918For example, suppose the file name in the patch file is 2919@file{/gnu/src/emacs/etc/NEWS}. Using @option{-p0} gives the 2920entire file name unmodified, @option{-p1} gives 2921@file{gnu/src/emacs/etc/NEWS} (no leading slash), @option{-p4} gives 2922@file{etc/NEWS}, and not specifying @option{-p} at all gives @file{NEWS}. 2923 2924@command{patch} looks for each file (after any slashes have been stripped) 2925in the current directory, or if you used the @option{-d @var{directory}} 2926option, in that directory. 2927 2928@node Backups 2929@section Backup Files 2930@cindex backup file strategy 2931 2932Normally, @command{patch} creates a backup file if the patch does not 2933exactly match the original input file, because in that case the 2934original data might not be recovered if you undo the patch with 2935@samp{patch -R} (@pxref{Reversed Patches}). However, when conforming 2936to @acronym{POSIX}, @command{patch} does not create backup files by 2937default. @xref{patch and POSIX}. 2938 2939The @option{-b} or @option{--backup} option causes @command{patch} to 2940make a backup file regardless of whether the patch matches the 2941original input. The @option{--backup-if-mismatch} option causes 2942@command{patch} to create backup files for mismatches files; this is 2943the default when not conforming to @acronym{POSIX}. The 2944@option{--no-backup-if-mismatch} option causes @command{patch} to not 2945create backup files, even for mismatched patches; this is the default 2946when conforming to @acronym{POSIX}. 2947 2948When backing up a file that does not exist, an empty, unreadable 2949backup file is created as a placeholder to represent the nonexistent 2950file. 2951 2952@node Backup Names 2953@section Backup File Names 2954@cindex backup file names 2955 2956Normally, @command{patch} renames an original input file into a backup 2957file by appending to its name the extension @samp{.orig}, or @samp{~} 2958if using @samp{.orig} would make the backup file name too 2959long.@footnote{A coding error in @acronym{GNU} @command{patch} version 29602.5.4 causes it to always use @samp{~}, but this should be fixed in 2961the next release.} The @option{-z @var{backup-suffix}} or 2962@option{--suffix=@var{backup-suffix}} option causes @command{patch} to 2963use @var{backup-suffix} as the backup extension instead. 2964 2965@vindex SIMPLE_BACKUP_SUFFIX 2966Alternately, you can specify the extension for backup files with the 2967@env{SIMPLE_BACKUP_SUFFIX} environment variable, which the options 2968override. 2969 2970@command{patch} can also create numbered backup files the way 2971@acronym{GNU} Emacs does. With this method, instead of having a 2972single backup of each file, @command{patch} makes a new backup file 2973name each time it patches a file. For example, the backups of a file 2974named @file{sink} would be called, successively, @file{sink.~1~}, 2975@file{sink.~2~}, @file{sink.~3~}, etc. 2976 2977@vindex PATCH_VERSION_CONTROL 2978@vindex VERSION_CONTROL 2979The @option{-V @var{backup-style}} or 2980@option{--version-control=@var{backup-style}} option takes as an 2981argument a method for creating backup file names. You can alternately 2982control the type of backups that @command{patch} makes with the 2983@env{PATCH_VERSION_CONTROL} environment variable, which the 2984@option{-V} option overrides. If @env{PATCH_VERSION_CONTROL} is not 2985set, the @env{VERSION_CONTROL} environment variable is used instead. 2986Please note that these options and variables control backup file 2987names; they do not affect the choice of revision control system 2988(@pxref{Revision Control}). 2989 2990The values of these environment variables and the argument to the 2991@option{-V} option are like the @acronym{GNU} Emacs @code{version-control} 2992variable (@pxref{Backup Names, , , emacs, The @acronym{GNU} Emacs Manual}, 2993for more information on backup versions in Emacs). They also 2994recognize synonyms that are more descriptive. The valid values are 2995listed below; unique abbreviations are acceptable. 2996 2997@table @option 2998@item t 2999@itemx numbered 3000Always make numbered backups. 3001 3002@item nil 3003@itemx existing 3004Make numbered backups of files that already have them, simple backups of 3005the others. This is the default. 3006 3007@item never 3008@itemx simple 3009Always make simple backups. 3010@end table 3011 3012You can also tell @command{patch} to prepend a prefix, such as a 3013directory name, to produce backup file names. The @option{-B 3014@var{prefix}} or @option{--prefix=@var{prefix}} option makes backup 3015files by prepending @var{prefix} to them. The @option{-Y 3016@var{prefix}} or @option{--basename-prefix=@var{prefix}} prepends 3017@var{prefix} to the last file name component of backup file names 3018instead; for example, @option{-Y ~} causes the backup name for 3019@file{dir/file.c} to be @file{dir/~file.c}. If you use either of 3020these prefix options, the suffix-based options are ignored. 3021 3022If you specify the output file with the @option{-o} option, that file is 3023the one that is backed up, not the input file. 3024 3025Options that affect the names of backup files do not affect whether 3026backups are made. For example, if you specify the 3027@option{--no-backup-if-mismatch} option, none of the options described 3028in this section have any affect, because no backups are made. 3029 3030@node Reject Names 3031@section Reject File Names 3032@cindex reject file names 3033 3034The names for reject files (files containing patches that 3035@command{patch} could not find a place to apply) are normally the name 3036of the output file with @samp{.rej} appended (or @samp{#} if using 3037@samp{.rej} would make the backup file name too long). 3038 3039Alternatively, you can tell @command{patch} to place all of the rejected 3040patches in a single file. The @option{-r @var{reject-file}} or 3041@option{--reject-file=@var{reject-file}} option uses @var{reject-file} as 3042the reject file name. 3043 3044@node patch Messages 3045@section Messages and Questions from @command{patch} 3046@cindex @command{patch} messages and questions 3047@cindex diagnostics from @command{patch} 3048@cindex messages from @command{patch} 3049 3050@command{patch} can produce a variety of messages, especially if it 3051has trouble decoding its input. In a few situations where it's not 3052sure how to proceed, @command{patch} normally prompts you for more 3053information from the keyboard. There are options to produce more or 3054fewer messages, to have it not ask for keyboard input, and to 3055affect the way that file names are quoted in messages. 3056 3057@menu 3058* More or Fewer Messages:: Controlling the verbosity of @command{patch}. 3059* patch and Keyboard Input:: Inhibiting keyboard input. 3060* patch Quoting Style:: Quoting file names in diagnostics. 3061@end menu 3062 3063@command{patch} exits with status 0 if all hunks are applied successfully, 30641 if some hunks cannot be applied, and 2 if there is more serious trouble. 3065When applying a set of patches in a loop, you should check the 3066exit status, so you don't apply a later patch to a partially patched 3067file. 3068 3069@node More or Fewer Messages 3070@subsection Controlling the Verbosity of @command{patch} 3071@cindex verbose messages from @command{patch} 3072@cindex inhibit messages from @command{patch} 3073 3074You can cause @command{patch} to produce more messages by using the 3075@option{--verbose} option. For example, when you give this option, 3076the message @samp{Hmm...} indicates that @command{patch} is reading text in 3077the patch file, attempting to determine whether there is a patch in that 3078text, and if so, what kind of patch it is. 3079 3080You can inhibit all terminal output from @command{patch}, unless an error 3081occurs, by using the @option{-s}, @option{--quiet}, or @option{--silent} 3082option. 3083 3084@node patch and Keyboard Input 3085@subsection Inhibiting Keyboard Input 3086@cindex keyboard input to @command{patch} 3087 3088There are two ways you can prevent @command{patch} from asking you any 3089questions. The @option{-f} or @option{--force} option assumes that you know 3090what you are doing. It causes @command{patch} to do the following: 3091 3092@itemize @bullet 3093@item 3094Skip patches that do not contain file names in their headers. 3095 3096@item 3097Patch files even though they have the wrong version for the 3098@samp{Prereq:} line in the patch; 3099 3100@item 3101Assume that patches are not reversed even if they look like they are. 3102@end itemize 3103 3104@noindent 3105The @option{-t} or @option{--batch} option is similar to @option{-f}, in that 3106it suppresses questions, but it makes somewhat different assumptions: 3107 3108@itemize @bullet 3109@item 3110Skip patches that do not contain file names in their headers 3111(the same as @option{-f}). 3112 3113@item 3114Skip patches for which the file has the wrong version for the 3115@samp{Prereq:} line in the patch; 3116 3117@item 3118Assume that patches are reversed if they look like they are. 3119@end itemize 3120 3121@node patch Quoting Style 3122@subsection @command{patch} Quoting Style 3123@cindex quoting style 3124 3125When @command{patch} outputs a file name in a diagnostic message, it 3126can format the name in any of several ways. This can be useful to 3127output file names unambiguously, even if they contain punctuation or 3128special characters like newlines. The 3129@option{--quoting-style=@var{word}} option controls how names are 3130output. The @var{word} should be one of the following: 3131 3132@table @samp 3133@item literal 3134Output names as-is. 3135@item shell 3136Quote names for the shell if they contain shell metacharacters or would 3137cause ambiguous output. 3138@item shell-always 3139Quote names for the shell, even if they would normally not require quoting. 3140@item c 3141Quote names as for a C language string. 3142@item escape 3143Quote as with @samp{c} except omit the surrounding double-quote 3144characters. 3145@c The following are not yet implemented in patch 2.5.4. 3146@c @item clocale 3147@c Quote as with @samp{c} except use quotation marks appropriate for the 3148@c locale. 3149@c @item locale 3150@c @c Use @t instead of @samp to avoid duplicate quoting in some output styles. 3151@c Like @samp{clocale}, but quote @t{`like this'} instead of @t{"like 3152@c this"} in the default C locale. This looks nicer on many displays. 3153@end table 3154 3155@vindex QUOTING_STYLE 3156You can specify the default value of the @option{--quoting-style} 3157option with the environment variable @env{QUOTING_STYLE}. If that 3158environment variable is not set, the default value is @samp{shell}, 3159but this default may change in a future version of @command{patch}. 3160 3161@node patch and POSIX 3162@section @command{patch} and the @acronym{POSIX} Standard 3163@cindex @acronym{POSIX} 3164 3165@vindex POSIXLY_CORRECT 3166If you specify the @option{--posix} option, or set the 3167@env{POSIXLY_CORRECT} environment variable, @command{patch} conforms 3168more strictly to the @acronym{POSIX} standard, as follows: 3169 3170@itemize @bullet 3171@item 3172Take the first existing file from the list (old, new, index) 3173when intuiting file names from diff headers. @xref{Multiple Patches}. 3174 3175@item 3176Do not remove files that are removed by a diff. 3177@xref{Creating and Removing}. 3178 3179@item 3180Do not ask whether to get files from @acronym{RCS}, ClearCase, or 3181@acronym{SCCS}. @xref{Revision Control}. 3182 3183@item 3184Require that all options precede the files in the command line. 3185 3186@item 3187Do not backup files, even when there is a mismatch. @xref{Backups}. 3188 3189@end itemize 3190 3191@node patch and Tradition 3192@section @acronym{GNU} @command{patch} and Traditional @command{patch} 3193@cindex traditional @command{patch} 3194 3195The current version of @acronym{GNU} @command{patch} normally follows the 3196@acronym{POSIX} standard. @xref{patch and POSIX}, for the few exceptions 3197to this general rule. 3198 3199Unfortunately, @acronym{POSIX} redefined the behavior of @command{patch} in 3200several important ways. You should be aware of the following 3201differences if you must interoperate with traditional @command{patch}, 3202or with @acronym{GNU} @command{patch} version 2.1 and earlier. 3203 3204@itemize @bullet 3205@item 3206In traditional @command{patch}, the @option{-p} option's operand was 3207optional, and a bare @option{-p} was equivalent to @option{-p0}. The 3208@option{-p} option now requires an operand, and @option{-p@ 0} is now 3209equivalent to @option{-p0}. For maximum compatibility, use options 3210like @option{-p0} and @option{-p1}. 3211 3212Also, traditional @command{patch} simply counted slashes when 3213stripping path prefixes; @command{patch} now counts pathname 3214components. That is, a sequence of one or more adjacent slashes now 3215counts as a single slash. For maximum portability, avoid sending 3216patches containing @file{//} in file names. 3217 3218@item 3219In traditional @command{patch}, backups were enabled by default. This 3220behavior is now enabled with the @option{-b} or @option{--backup} 3221option. 3222 3223Conversely, in @acronym{POSIX} @command{patch}, backups are never made, 3224even when there is a mismatch. In @acronym{GNU} @command{patch}, this 3225behavior is enabled with the @option{--no-backup-if-mismatch} option, 3226or by conforming to @acronym{POSIX}. 3227 3228The @option{-b@ @var{suffix}} option of traditional @command{patch} is 3229equivalent to the @samp{-b -z@ @var{suffix}} options of @acronym{GNU} 3230@command{patch}. 3231 3232@item 3233Traditional @command{patch} used a complicated (and incompletely 3234documented) method to intuit the name of the file to be patched from 3235the patch header. This method did not conform to @acronym{POSIX}, and had 3236a few gotchas. Now @command{patch} uses a different, equally 3237complicated (but better documented) method that is optionally 3238@acronym{POSIX}-conforming; we hope it has fewer gotchas. The two methods 3239are compatible if the file names in the context diff header and the 3240@samp{Index:} line are all identical after prefix-stripping. Your 3241patch is normally compatible if each header's file names all contain 3242the same number of slashes. 3243 3244@item 3245When traditional @command{patch} asked the user a question, it sent 3246the question to standard error and looked for an answer from the first 3247file in the following list that was a terminal: standard error, 3248standard output, @file{/dev/tty}, and standard input. Now 3249@command{patch} sends questions to standard output and gets answers 3250from @file{/dev/tty}. Defaults for some answers have been changed so 3251that @command{patch} never goes into an infinite loop when using 3252default answers. 3253 3254@item 3255Traditional @command{patch} exited with a status value that counted 3256the number of bad hunks, or with status 1 if there was real trouble. 3257Now @command{patch} exits with status 1 if some hunks failed, or with 32582 if there was real trouble. 3259 3260@item 3261Limit yourself to the following options when sending instructions 3262meant to be executed by anyone running @acronym{GNU} @command{patch}, 3263traditional @command{patch}, or a @command{patch} that conforms to 3264@acronym{POSIX}. Spaces are significant in the following list, and 3265operands are required. 3266 3267@example 3268@option{-c} 3269@option{-d @var{dir}} 3270@option{-D @var{define}} 3271@option{-e} 3272@option{-l} 3273@option{-n} 3274@option{-N} 3275@option{-o @var{outfile}} 3276@option{-p@var{num}} 3277@option{-R} 3278@option{-r @var{rejectfile}} 3279@end example 3280 3281@end itemize 3282 3283@node Making Patches 3284@chapter Tips for Making and Using Patches 3285 3286Use some common sense when making and using patches. For example, 3287when sending bug fixes to a program's maintainer, send several small 3288patches, one per independent subject, instead of one large, 3289harder-to-digest patch that covers all the subjects. 3290 3291Here are some other things you should keep in mind if you are going to 3292distribute patches for updating a software package. 3293 3294@menu 3295* Tips for Patch Producers:: Advice for making patches. 3296* Tips for Patch Consumers:: Advice for using patches. 3297* Avoiding Common Mistakes:: Avoiding common mistakes when using @command{patch}. 3298* Generating Smaller Patches:: How to generate smaller patches. 3299@end menu 3300 3301@node Tips for Patch Producers 3302@section Tips for Patch Producers 3303@cindex patch producer tips 3304 3305To create a patch that changes an older version of a package into a 3306newer version, first make a copy of the older and newer versions in 3307adjacent subdirectories. It is common to do that by unpacking 3308@command{tar} archives of the two versions. 3309 3310To generate the patch, use the command @samp{diff -Naur @var{old} 3311@var{new}} where @var{old} and @var{new} identify the old and new 3312directories. The names @var{old} and @var{new} should not contain any 3313slashes. The @option{-N} option lets the patch create and remove 3314files; @option{-a} lets the patch update non-text files; @option{-u} 3315generates useful time stamps and enough context; and @option{-r} lets 3316the patch update subdirectories. Here is an example command, using 3317Bourne shell syntax: 3318 3319@example 3320diff -Naur gcc-3.0.3 gcc-3.0.4 3321@end example 3322 3323Tell your recipients how to apply the patches. This should include 3324which working directory to use, and which @command{patch} options to 3325use; the option @samp{-p1} is recommended. Test your procedure by 3326pretending to be a recipient and applying your patches to a copy of 3327the original files. 3328 3329@xref{Avoiding Common Mistakes}, for how to avoid common mistakes when 3330generating a patch. 3331 3332@node Tips for Patch Consumers 3333@section Tips for Patch Consumers 3334@cindex patch consumer tips 3335 3336A patch producer should tell recipients how to apply the patches, so 3337the first rule of thumb for a patch consumer is to follow the 3338instructions supplied with the patch. 3339 3340@acronym{GNU} @command{diff} can analyze files with arbitrarily long lines 3341and files that end in incomplete lines. However, older versions of 3342@command{patch} cannot patch such files. If you are having trouble 3343applying such patches, try upgrading to a recent version of @acronym{GNU} 3344@command{patch}. 3345 3346@node Avoiding Common Mistakes 3347@section Avoiding Common Mistakes 3348@cindex common mistakes with patches 3349@cindex patch, common mistakes 3350 3351When producing a patch for multiple files, apply @command{diff} to 3352directories whose names do not have slashes. This reduces confusion 3353when the patch consumer specifies the @option{-p@var{number}} option, 3354since this option can have surprising results when the old and new 3355file names have different numbers of slashes. For example, do not 3356send a patch with a header that looks like this: 3357 3358@example 3359diff -Naur v2.0.29/prog/README prog/README 3360--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 3361+++ prog/README 2002-03-17 20:49:32.442260588 -0800 3362@end example 3363 3364@noindent 3365because the two file names have different numbers of slashes, and 3366different versions of @command{patch} interpret the file names 3367differently. To avoid confusion, send output that looks like this 3368instead: 3369 3370@example 3371diff -Naur v2.0.29/prog/README v2.0.30/prog/README 3372--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 3373+++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800 3374@end example 3375 3376Make sure you have specified the file names correctly, either in a 3377context diff header or with an @samp{Index:} line. Take care to not send out 3378reversed patches, since these make people wonder whether they have 3379already applied the patch. 3380 3381Avoid sending patches that compare backup file names like 3382@file{README.orig} or @file{README~}, since this might confuse 3383@command{patch} into patching a backup file instead of the real file. 3384Instead, send patches that compare the same base file names in 3385different directories, e.g.@: @file{old/README} and @file{new/README}. 3386 3387To save people from partially applying a patch before other patches that 3388should have gone before it, you can make the first patch in the patch 3389file update a file with a name like @file{patchlevel.h} or 3390@file{version.c}, which contains a patch level or version number. If 3391the input file contains the wrong version number, @command{patch} will 3392complain immediately. 3393 3394An even clearer way to prevent this problem is to put a @samp{Prereq:} 3395line before the patch. If the leading text in the patch file contains a 3396line that starts with @samp{Prereq:}, @command{patch} takes the next word 3397from that line (normally a version number) and checks whether the next 3398input file contains that word, preceded and followed by either 3399white space or a newline. If not, @command{patch} prompts you for 3400confirmation before proceeding. This makes it difficult to accidentally 3401apply patches in the wrong order. 3402 3403@node Generating Smaller Patches 3404@section Generating Smaller Patches 3405@cindex patches, shrinking 3406 3407The simplest way to generate a patch is to use @samp{diff -Naur} 3408(@pxref{Tips for Patch Producers}), but you might be able to reduce 3409the size of the patch by renaming or removing some files before making 3410the patch. If the older version of the package contains any files 3411that the newer version does not, or if any files have been renamed 3412between the two versions, make a list of @command{rm} and @command{mv} 3413commands for the user to execute in the old version directory before 3414applying the patch. Then run those commands yourself in the scratch 3415directory. 3416 3417If there are any files that you don't need to include in the patch 3418because they can easily be rebuilt from other files (for example, 3419@file{TAGS} and output from @command{yacc} and @command{makeinfo}), 3420exclude them from the patch by giving @command{diff} the @option{-x 3421@var{pattern}} option (@pxref{Comparing Directories}). If you want 3422your patch to modify a derived file because your recipients lack tools 3423to build it, make sure that the patch for the derived file follows any 3424patches for files that it depends on, so that the recipients' time 3425stamps will not confuse @command{make}. 3426 3427Now you can create the patch using @samp{diff -Naur}. Make sure to 3428specify the scratch directory first and the newer directory second. 3429 3430Add to the top of the patch a note telling the user any @command{rm} and 3431@command{mv} commands to run before applying the patch. Then you can 3432remove the scratch directory. 3433 3434You can also shrink the patch size by using fewer lines of context, 3435but bear in mind that @command{patch} typically needs at least two 3436lines for proper operation when patches do not exactly match the input 3437files. 3438 3439@node Invoking cmp 3440@chapter Invoking @command{cmp} 3441@cindex invoking @command{cmp} 3442@cindex @command{cmp} invocation 3443 3444The @command{cmp} command compares two files, and if they differ, 3445tells the first byte and line number where they differ or reports 3446that one file is a prefix of the other. Bytes and 3447lines are numbered starting with 1. The arguments of @command{cmp} 3448are as follows: 3449 3450@example 3451cmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file} @r{[}@var{from-skip} @r{[}@var{to-skip}@r{]}@r{]}@r{]} 3452@end example 3453 3454The file name @file{-} is always the standard input. @command{cmp} 3455also uses the standard input if one file name is omitted. The 3456@var{from-skip} and @var{to-skip} operands specify how many bytes to 3457ignore at the start of each file; they are equivalent to the 3458@option{--ignore-initial=@var{from-skip}:@var{to-skip}} option. 3459 3460By default, @command{cmp} outputs nothing if the two files have the 3461same contents. If one file is a prefix of the other, @command{cmp} 3462prints to standard error a message of the following form: 3463 3464@example 3465cmp: EOF on @var{shorter-file} 3466@end example 3467 3468Otherwise, @command{cmp} prints to standard output a message of the 3469following form: 3470 3471@example 3472@var{from-file} @var{to-file} differ: char @var{byte-number}, line @var{line-number} 3473@end example 3474 3475The message formats can differ outside the @acronym{POSIX} locale. 3476Also, @acronym{POSIX} allows the @acronym{EOF} message to be followed 3477by a blank and some additional information. 3478 3479An exit status of 0 means no differences were found, 1 means some 3480differences were found, and 2 means trouble. 3481 3482@menu 3483* cmp Options:: Summary of options to @command{cmp}. 3484@end menu 3485 3486@node cmp Options 3487@section Options to @command{cmp} 3488@cindex @command{cmp} options 3489@cindex options for @command{cmp} 3490 3491Below is a summary of all of the options that @acronym{GNU} 3492@command{cmp} accepts. Most options have two equivalent names, one of 3493which is a single letter preceded by @samp{-}, and the other of which 3494is a long name preceded by @samp{--}. Multiple single letter options 3495(unless they take an argument) can be combined into a single command 3496line word: @option{-bl} is equivalent to @option{-b -l}. 3497 3498@table @option 3499@item -b 3500@itemx --print-bytes 3501Print the differing bytes. Display control bytes as a 3502@samp{^} followed by a letter of the alphabet and precede bytes 3503that have the high bit set with @samp{M-} (which stands for ``meta''). 3504 3505@item --help 3506Output a summary of usage and then exit. 3507 3508@item -i @var{skip} 3509@itemx --ignore-initial=@var{skip} 3510Ignore any differences in the first @var{skip} bytes of the input 3511files. Treat files with fewer than @var{skip} bytes as if they are 3512empty. If @var{skip} is of the form 3513@option{@var{from-skip}:@var{to-skip}}, skip the first @var{from-skip} 3514bytes of the first input file and the first @var{to-skip} bytes of the 3515second. 3516 3517@item -l 3518@itemx --verbose 3519Output the (decimal) byte numbers and (octal) values of all differing bytes, 3520instead of the default standard output. 3521 3522@item -n @var{count} 3523@itemx --bytes=@var{count} 3524Compare at most @var{count} input bytes. 3525 3526@item -s 3527@itemx --quiet 3528@itemx --silent 3529Do not print anything; only return an exit status indicating whether 3530the files differ. 3531 3532@item -v 3533@itemx --version 3534Output version information and then exit. 3535@end table 3536 3537In the above table, operands that are byte counts are normally 3538decimal, but may be preceded by @samp{0} for octal and @samp{0x} for 3539hexadecimal. 3540 3541A byte count can be followed by a suffix to specify a multiple of that 3542count; in this case an omitted integer is understood to be 1. A bare 3543size letter, or one followed by @samp{iB}, specifies a multiple using 3544powers of 1024. A size letter followed by @samp{B} specifies powers 3545of 1000 instead. For example, @option{-n 4M} and @option{-n 4MiB} are 3546equivalent to @option{-n 4194304}, whereas @option{-n 4MB} is 3547equivalent to @option{-n 4000000}. This notation is upward compatible 3548with the @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI 3549prefixes} for decimal multiples and with the 3550@uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2 3551prefixes for binary multiples}. 3552 3553The following suffixes are defined. Large sizes like @code{1Y} may be 3554rejected by your computer due to limitations of its arithmetic. 3555 3556@table @samp 3557@item kB 3558@cindex kilobyte, definition of 3559kilobyte: @math{10^3 = 1000}. 3560@item k 3561@itemx K 3562@itemx KiB 3563@cindex kibibyte, definition of 3564kibibyte: @math{2^10 = 1024}. @samp{K} is special: the SI prefix is 3565@samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and 3566@acronym{POSIX} use @samp{k} to mean @samp{KiB}. 3567@item MB 3568@cindex megabyte, definition of 3569megabyte: @math{10^6 = 1,000,000}. 3570@item M 3571@itemx MiB 3572@cindex mebibyte, definition of 3573mebibyte: @math{2^20 = 1,048,576}. 3574@item GB 3575@cindex gigabyte, definition of 3576gigabyte: @math{10^9 = 1,000,000,000}. 3577@item G 3578@itemx GiB 3579@cindex gibibyte, definition of 3580gibibyte: @math{2^30 = 1,073,741,824}. 3581@item TB 3582@cindex terabyte, definition of 3583terabyte: @math{10^12 = 1,000,000,000,000}. 3584@item T 3585@itemx TiB 3586@cindex tebibyte, definition of 3587tebibyte: @math{2^40 = 1,099,511,627,776}. 3588@item PB 3589@cindex petabyte, definition of 3590petabyte: @math{10^15 = 1,000,000,000,000,000}. 3591@item P 3592@itemx PiB 3593@cindex pebibyte, definition of 3594pebibyte: @math{2^50 = 1,125,899,906,842,624}. 3595@item EB 3596@cindex exabyte, definition of 3597exabyte: @math{10^18 = 1,000,000,000,000,000,000}. 3598@item E 3599@itemx EiB 3600@cindex exbibyte, definition of 3601exbibyte: @math{2^60 = 1,152,921,504,606,846,976}. 3602@item ZB 3603@cindex zettabyte, definition of 3604zettabyte: @math{10^21 = 1,000,000,000,000,000,000,000} 3605@item Z 3606@itemx ZiB 3607@math{2^70 = 1,180,591,620,717,411,303,424}. 3608(@samp{Zi} is a GNU extension to IEC 60027-2.) 3609@item YB 3610@cindex yottabyte, definition of 3611yottabyte: @math{10^24 = 1,000,000,000,000,000,000,000,000}. 3612@item Y 3613@itemx YiB 3614@math{2^80 = 1,208,925,819,614,629,174,706,176}. 3615(@samp{Yi} is a GNU extension to IEC 60027-2.) 3616@end table 3617 3618@node Invoking diff 3619@chapter Invoking @command{diff} 3620@cindex invoking @command{diff} 3621@cindex @command{diff} invocation 3622 3623The format for running the @command{diff} command is: 3624 3625@example 3626diff @var{options}@dots{} @var{files}@dots{} 3627@end example 3628 3629In the simplest case, two file names @var{from-file} and 3630@var{to-file} are given, and @command{diff} compares the contents of 3631@var{from-file} and @var{to-file}. A file name of @file{-} stands for 3632text read from the standard input. As a special case, @samp{diff - -} 3633compares a copy of standard input to itself. 3634 3635If one file is a directory and the other is not, @command{diff} compares 3636the file in the directory whose name is that of the non-directory. 3637The non-directory file must not be @file{-}. 3638 3639If two file names are given and both are directories, 3640@command{diff} compares corresponding files in both directories, in 3641alphabetical order; this comparison is not recursive unless the 3642@option{-r} or @option{--recursive} option is given. @command{diff} never 3643compares the actual contents of a directory as if it were a file. The 3644file that is fully specified may not be standard input, because standard 3645input is nameless and the notion of ``file with the same name'' does not 3646apply. 3647 3648If the @option{--from-file=@var{file}} option is given, the number of 3649file names is arbitrary, and @var{file} is compared to each named file. 3650Similarly, if the @option{--to-file=@var{file}} option is given, each 3651named file is compared to @var{file}. 3652 3653@command{diff} options begin with @samp{-}, so normally file names 3654may not begin with @samp{-}. However, @option{--} as an 3655argument by itself treats the remaining arguments as file names even if 3656they begin with @samp{-}. 3657 3658An exit status of 0 means no differences were found, 1 means some 3659differences were found, and 2 means trouble. Normally, differing 3660binary files count as trouble, but this can be altered by using the 3661@option{-a} or @option{--text} option, or the @option{-q} or 3662@option{--brief} option. 3663 3664@menu 3665* diff Options:: Summary of options to @command{diff}. 3666@end menu 3667 3668@node diff Options 3669@section Options to @command{diff} 3670@cindex @command{diff} options 3671@cindex options for @command{diff} 3672 3673Below is a summary of all of the options that @acronym{GNU} 3674@command{diff} accepts. Most options have two equivalent names, one 3675of which is a single letter preceded by @samp{-}, and the other of 3676which is a long name preceded by @samp{--}. Multiple single letter 3677options (unless they take an argument) can be combined into a single 3678command line word: @option{-ac} is equivalent to @option{-a -c}. Long 3679named options can be abbreviated to any unique prefix of their name. 3680Brackets ([ and ]) indicate that an option takes an optional argument. 3681 3682@table @option 3683@item -a 3684@itemx --text 3685Treat all files as text and compare them line-by-line, even if they 3686do not seem to be text. @xref{Binary}. 3687 3688@item -b 3689@itemx --ignore-space-change 3690Ignore changes in amount of white space. @xref{White Space}. 3691 3692@item -B 3693@itemx --ignore-blank-lines 3694Ignore changes that just insert or delete blank lines. @xref{Blank 3695Lines}. 3696 3697@item --binary 3698Read and write data in binary mode. @xref{Binary}. 3699 3700@item -c 3701Use the context output format, showing three lines of context. 3702@xref{Context Format}. 3703 3704@item -C @var{lines} 3705@itemx --context@r{[}=@var{lines}@r{]} 3706Use the context output format, showing @var{lines} (an integer) lines of 3707context, or three if @var{lines} is not given. @xref{Context Format}. 3708For proper operation, @command{patch} typically needs at least two lines of 3709context. 3710 3711On older systems, @command{diff} supports an obsolete option 3712@option{-@var{lines}} that has effect when combined with @option{-c} 3713or @option{-p}. @acronym{POSIX} 1003.1-2001 (@pxref{Standards 3714conformance}) does not allow this; use @option{-C @var{lines}} 3715instead. 3716 3717@item --changed-group-format=@var{format} 3718Use @var{format} to output a line group containing differing lines from 3719both files in if-then-else format. @xref{Line Group Formats}. 3720 3721@item -d 3722@itemx --minimal 3723Change the algorithm perhaps find a smaller set of changes. This makes 3724@command{diff} slower (sometimes much slower). @xref{diff Performance}. 3725 3726@item -D @var{name} 3727@itemx --ifdef=@var{name} 3728Make merged @samp{#ifdef} format output, conditional on the preprocessor 3729macro @var{name}. @xref{If-then-else}. 3730 3731@item -e 3732@itemx --ed 3733Make output that is a valid @command{ed} script. @xref{ed Scripts}. 3734 3735@item -E 3736@itemx --ignore-tab-expansion 3737Ignore changes due to tab expansion. 3738@xref{White Space}. 3739 3740@item -f 3741@itemx --forward-ed 3742Make output that looks vaguely like an @command{ed} script but has changes 3743in the order they appear in the file. @xref{Forward ed}. 3744 3745@item -F @var{regexp} 3746@itemx --show-function-line=@var{regexp} 3747In context and unified format, for each hunk of differences, show some 3748of the last preceding line that matches @var{regexp}. @xref{Specified 3749Headings}. 3750 3751@item --from-file=@var{file} 3752Compare @var{file} to each operand; @var{file} may be a directory. 3753 3754@item --help 3755Output a summary of usage and then exit. 3756 3757@item --horizon-lines=@var{lines} 3758Do not discard the last @var{lines} lines of the common prefix 3759and the first @var{lines} lines of the common suffix. 3760@xref{diff Performance}. 3761 3762@item -i 3763@itemx --ignore-case 3764Ignore changes in case; consider upper- and lower-case letters 3765equivalent. @xref{Case Folding}. 3766 3767@item -I @var{regexp} 3768@itemx --ignore-matching-lines=@var{regexp} 3769Ignore changes that just insert or delete lines that match @var{regexp}. 3770@xref{Specified Lines}. 3771 3772@item --ignore-file-name-case 3773Ignore case when comparing file names during recursive comparison. 3774@xref{Comparing Directories}. 3775 3776@item -l 3777@itemx --paginate 3778Pass the output through @command{pr} to paginate it. @xref{Pagination}. 3779 3780@item --label=@var{label} 3781Use @var{label} instead of the file name in the context format 3782(@pxref{Context Format}) and unified format (@pxref{Unified Format}) 3783headers. @xref{RCS}. 3784 3785@item --left-column 3786Print only the left column of two common lines in side by side format. 3787@xref{Side by Side Format}. 3788 3789@item --line-format=@var{format} 3790Use @var{format} to output all input lines in if-then-else format. 3791@xref{Line Formats}. 3792 3793@item -n 3794@itemx --rcs 3795Output @acronym{RCS}-format diffs; like @option{-f} except that each command 3796specifies the number of lines affected. @xref{RCS}. 3797 3798@item -N 3799@itemx --new-file 3800In directory comparison, if a file is found in only one directory, 3801treat it as present but empty in the other directory. @xref{Comparing 3802Directories}. 3803 3804@item --new-group-format=@var{format} 3805Use @var{format} to output a group of lines taken from just the second 3806file in if-then-else format. @xref{Line Group Formats}. 3807 3808@item --new-line-format=@var{format} 3809Use @var{format} to output a line taken from just the second file in 3810if-then-else format. @xref{Line Formats}. 3811 3812@item --old-group-format=@var{format} 3813Use @var{format} to output a group of lines taken from just the first 3814file in if-then-else format. @xref{Line Group Formats}. 3815 3816@item --old-line-format=@var{format} 3817Use @var{format} to output a line taken from just the first file in 3818if-then-else format. @xref{Line Formats}. 3819 3820@item -p 3821@itemx --show-c-function 3822Show which C function each change is in. @xref{C Function Headings}. 3823 3824@item -q 3825@itemx --brief 3826Report only whether the files differ, not the details of the 3827differences. @xref{Brief}. 3828 3829@item -r 3830@itemx --recursive 3831When comparing directories, recursively compare any subdirectories 3832found. @xref{Comparing Directories}. 3833 3834@item -s 3835@itemx --report-identical-files 3836Report when two files are the same. @xref{Comparing Directories}. 3837 3838@item -S @var{file} 3839@itemx --starting-file=@var{file} 3840When comparing directories, start with the file @var{file}. This is 3841used for resuming an aborted comparison. @xref{Comparing Directories}. 3842 3843@item --speed-large-files 3844Use heuristics to speed handling of large files that have numerous 3845scattered small changes. @xref{diff Performance}. 3846 3847@item --strip-trailing-cr 3848Strip any trailing carriage return at the end of an input line. 3849@xref{Binary}. 3850 3851@item --suppress-common-lines 3852Do not print common lines in side by side format. 3853@xref{Side by Side Format}. 3854 3855@item -t 3856@itemx --expand-tabs 3857Expand tabs to spaces in the output, to preserve the alignment of tabs 3858in the input files. @xref{Tabs}. 3859 3860@item -T 3861@itemx --initial-tab 3862Output a tab rather than a space before the text of a line in normal or 3863context format. This causes the alignment of tabs in the line to look 3864normal. @xref{Tabs}. 3865 3866@item --tabsize=@var{columns} 3867Assume that tab stops are set every @var{columns} (default 8) print 3868columns. @xref{Tabs}. 3869 3870@item --to-file=@var{file} 3871Compare each operand to @var{file}; @var{file} may be a directory. 3872 3873@item -u 3874Use the unified output format, showing three lines of context. 3875@xref{Unified Format}. 3876 3877@item --unchanged-group-format=@var{format} 3878Use @var{format} to output a group of common lines taken from both files 3879in if-then-else format. @xref{Line Group Formats}. 3880 3881@item --unchanged-line-format=@var{format} 3882Use @var{format} to output a line common to both files in if-then-else 3883format. @xref{Line Formats}. 3884 3885@item --unidirectional-new-file 3886When comparing directories, if a file appears only in the second 3887directory of the two, treat it as present but empty in the other. 3888@xref{Comparing Directories}. 3889 3890@item -U @var{lines} 3891@itemx --unified@r{[}=@var{lines}@r{]} 3892Use the unified output format, showing @var{lines} (an integer) lines of 3893context, or three if @var{lines} is not given. @xref{Unified Format}. 3894For proper operation, @command{patch} typically needs at least two lines of 3895context. 3896 3897On older systems, @command{diff} supports an obsolete option 3898@option{-@var{lines}} that has effect when combined with @option{-u}. 3899@acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not allow 3900this; use @option{-U @var{lines}} instead. 3901 3902@item -v 3903@itemx --version 3904Output version information and then exit. 3905 3906@item -w 3907@itemx --ignore-all-space 3908Ignore white space when comparing lines. @xref{White Space}. 3909 3910@item -W @var{columns} 3911@itemx --width=@var{columns} 3912Output at most @var{columns} (default 130) print columns per line in 3913side by side format. @xref{Side by Side Format}. 3914 3915@item -x @var{pattern} 3916@itemx --exclude=@var{pattern} 3917When comparing directories, ignore files and subdirectories whose basenames 3918match @var{pattern}. @xref{Comparing Directories}. 3919 3920@item -X @var{file} 3921@itemx --exclude-from=@var{file} 3922When comparing directories, ignore files and subdirectories whose basenames 3923match any pattern contained in @var{file}. @xref{Comparing Directories}. 3924 3925@item -y 3926@itemx --side-by-side 3927Use the side by side output format. @xref{Side by Side Format}. 3928@end table 3929 3930@node Invoking diff3 3931@chapter Invoking @command{diff3} 3932@cindex invoking @command{diff3} 3933@cindex @command{diff3} invocation 3934 3935The @command{diff3} command compares three files and outputs descriptions 3936of their differences. Its arguments are as follows: 3937 3938@example 3939diff3 @var{options}@dots{} @var{mine} @var{older} @var{yours} 3940@end example 3941 3942The files to compare are @var{mine}, @var{older}, and @var{yours}. 3943At most one of these three file names may be @file{-}, 3944which tells @command{diff3} to read the standard input for that file. 3945 3946An exit status of 0 means @command{diff3} was successful, 1 means some 3947conflicts were found, and 2 means trouble. 3948 3949@menu 3950* diff3 Options:: Summary of options to @command{diff3}. 3951@end menu 3952 3953@node diff3 Options 3954@section Options to @command{diff3} 3955@cindex @command{diff3} options 3956@cindex options for @command{diff3} 3957 3958Below is a summary of all of the options that @acronym{GNU} @command{diff3} 3959accepts. Multiple single letter options (unless they take an argument) 3960can be combined into a single command line argument. 3961 3962@table @option 3963@item -a 3964@itemx --text 3965Treat all files as text and compare them line-by-line, even if they 3966do not appear to be text. @xref{Binary}. 3967 3968@item -A 3969@itemx --show-all 3970Incorporate all unmerged changes from @var{older} to @var{yours} into 3971@var{mine}, surrounding conflicts with bracket lines. 3972@xref{Marking Conflicts}. 3973 3974@item --diff-program=@var{program} 3975Use the compatible comparison program @var{program} to compare files 3976instead of @command{diff}. 3977 3978@item -e 3979@itemx --ed 3980Generate an @command{ed} script that incorporates all the changes from 3981@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}. 3982 3983@item -E 3984@itemx --show-overlap 3985Like @option{-e}, except bracket lines from overlapping changes' first 3986and third files. 3987@xref{Marking Conflicts}. 3988With @option{-E}, an overlapping change looks like this: 3989 3990@example 3991<<<<<<< @var{mine} 3992@r{lines from @var{mine}} 3993======= 3994@r{lines from @var{yours}} 3995>>>>>>> @var{yours} 3996@end example 3997 3998@item --help 3999Output a summary of usage and then exit. 4000 4001@item -i 4002Generate @samp{w} and @samp{q} commands at the end of the @command{ed} 4003script for System V compatibility. This option must be combined with 4004one of the @option{-AeExX3} options, and may not be combined with @option{-m}. 4005@xref{Saving the Changed File}. 4006 4007@item --label=@var{label} 4008Use the label @var{label} for the brackets output by the @option{-A}, 4009@option{-E} and @option{-X} options. This option may be given up to three 4010times, one for each input file. The default labels are the names of 4011the input files. Thus @samp{diff3 --label X --label Y --label Z -m A 4012B C} acts like 4013@samp{diff3 -m A B C}, except that the output looks like it came from 4014files named @samp{X}, @samp{Y} and @samp{Z} rather than from files 4015named @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}. 4016 4017@item -m 4018@itemx --merge 4019Apply the edit script to the first file and send the result to standard 4020output. Unlike piping the output from @command{diff3} to @command{ed}, this 4021works even for binary files and incomplete lines. @option{-A} is assumed 4022if no edit script option is specified. @xref{Bypassing ed}. 4023 4024@item --strip-trailing-cr 4025Strip any trailing carriage return at the end of an input line. 4026@xref{Binary}. 4027 4028@item -T 4029@itemx --initial-tab 4030Output a tab rather than two spaces before the text of a line in normal format. 4031This causes the alignment of tabs in the line to look normal. @xref{Tabs}. 4032 4033@item -v 4034@itemx --version 4035Output version information and then exit. 4036 4037@item -x 4038@itemx --overlap-only 4039Like @option{-e}, except output only the overlapping changes. 4040@xref{Which Changes}. 4041 4042@item -X 4043Like @option{-E}, except output only the overlapping changes. 4044In other words, like @option{-x}, except bracket changes as in @option{-E}. 4045@xref{Marking Conflicts}. 4046 4047@item -3 4048@itemx --easy-only 4049Like @option{-e}, except output only the nonoverlapping changes. 4050@xref{Which Changes}. 4051@end table 4052 4053@node Invoking patch 4054@chapter Invoking @command{patch} 4055@cindex invoking @command{patch} 4056@cindex @command{patch} invocation 4057 4058Normally @command{patch} is invoked like this: 4059 4060@example 4061patch <@var{patchfile} 4062@end example 4063 4064The full format for invoking @command{patch} is: 4065 4066@example 4067patch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]} 4068@end example 4069 4070You can also specify where to read the patch from with the @option{-i 4071@var{patchfile}} or @option{--input=@var{patchfile}} option. 4072If you do not specify @var{patchfile}, or if @var{patchfile} is 4073@file{-}, @command{patch} reads the patch (that is, the @command{diff} output) 4074from the standard input. 4075 4076If you do not specify an input file on the command line, @command{patch} 4077tries to intuit from the @dfn{leading text} (any text in the patch 4078that comes before the @command{diff} output) which file to edit. 4079@xref{Multiple Patches}. 4080 4081By default, @command{patch} replaces the original input file with the 4082patched version, possibly after renaming the original file into a 4083backup file (@pxref{Backup Names}, for a description of how 4084@command{patch} names backup files). You can also specify where to 4085put the output with the @option{-o @var{file}} or 4086@option{--output=@var{file}} option; however, do not use this option 4087if @var{file} is one of the input files. 4088 4089@menu 4090* patch Options:: Summary table of options to @command{patch}. 4091@end menu 4092 4093@node patch Options 4094@section Options to @command{patch} 4095@cindex @command{patch} options 4096@cindex options for @command{patch} 4097 4098Here is a summary of all of the options that @acronym{GNU} @command{patch} 4099accepts. @xref{patch and Tradition}, for which of these options are 4100safe to use in older versions of @command{patch}. 4101 4102Multiple single-letter options that do not take an argument can be 4103combined into a single command line argument with only one dash. 4104 4105@table @option 4106@item -b 4107@itemx --backup 4108Back up the original contents of each file, even if backups would 4109normally not be made. @xref{Backups}. 4110 4111@item -B @var{prefix} 4112@itemx --prefix=@var{prefix} 4113Prepend @var{prefix} to backup file names. @xref{Backup Names}. 4114 4115@item --backup-if-mismatch 4116Back up the original contents of each file if the patch does not 4117exactly match the file. This is the default behavior when not 4118conforming to @acronym{POSIX}. @xref{Backups}. 4119 4120@item --binary 4121Read and write all files in binary mode, except for standard output 4122and @file{/dev/tty}. This option has no effect on 4123@acronym{POSIX}-conforming systems like @acronym{GNU}/Linux. On systems where 4124this option makes a difference, the patch should be generated by 4125@samp{diff -a --binary}. @xref{Binary}. 4126 4127@item -c 4128@itemx --context 4129Interpret the patch file as a context diff. @xref{patch Input}. 4130 4131@item -d @var{directory} 4132@itemx --directory=@var{directory} 4133Make directory @var{directory} the current directory for interpreting 4134both file names in the patch file, and file names given as arguments to 4135other options. @xref{patch Directories}. 4136 4137@item -D @var{name} 4138@itemx --ifdef=@var{name} 4139Make merged if-then-else output using @var{name}. @xref{If-then-else}. 4140 4141@item --dry-run 4142Print the results of applying the patches without actually changing 4143any files. @xref{Dry Runs}. 4144 4145@item -e 4146@itemx --ed 4147Interpret the patch file as an @command{ed} script. @xref{patch Input}. 4148 4149@item -E 4150@itemx --remove-empty-files 4151Remove output files that are empty after the patches have been applied. 4152@xref{Creating and Removing}. 4153 4154@item -f 4155@itemx --force 4156Assume that the user knows exactly what he or she is doing, and do not 4157ask any questions. @xref{patch Messages}. 4158 4159@item -F @var{lines} 4160@itemx --fuzz=@var{lines} 4161Set the maximum fuzz factor to @var{lines}. @xref{Inexact}. 4162 4163@item -g @var{num} 4164@itemx --get=@var{num} 4165If @var{num} is positive, get input files from a revision control 4166system as necessary; if zero, do not get the files; if negative, ask 4167the user whether to get the files. @xref{Revision Control}. 4168 4169@item --help 4170Output a summary of usage and then exit. 4171 4172@item -i @var{patchfile} 4173@itemx --input=@var{patchfile} 4174Read the patch from @var{patchfile} rather than from standard input. 4175@xref{patch Options}. 4176 4177@item -l 4178@itemx --ignore-white-space 4179Let any sequence of blanks (spaces or tabs) in the patch file match 4180any sequence of blanks in the input file. @xref{Changed White Space}. 4181 4182@item -n 4183@itemx --normal 4184Interpret the patch file as a normal diff. @xref{patch Input}. 4185 4186@item -N 4187@itemx --forward 4188Ignore patches that @command{patch} thinks are reversed or already applied. 4189See also @option{-R}. @xref{Reversed Patches}. 4190 4191@item --no-backup-if-mismatch 4192Do not back up the original contents of files. This is the default 4193behavior when conforming to @acronym{POSIX}. @xref{Backups}. 4194 4195@item -o @var{file} 4196@itemx --output=@var{file} 4197Use @var{file} as the output file name. @xref{patch Options}. 4198 4199@item -p@var{number} 4200@itemx --strip=@var{number} 4201Set the file name strip count to @var{number}. @xref{patch Directories}. 4202 4203@item --posix 4204Conform to @acronym{POSIX}, as if the @env{POSIXLY_CORRECT} environment 4205variable had been set. @xref{patch and POSIX}. 4206 4207@item --quoting-style=@var{word} 4208Use style @var{word} to quote names in diagnostics, as if the 4209@env{QUOTING_STYLE} environment variable had been set to @var{word}. 4210@xref{patch Quoting Style}. 4211 4212@item -r @var{reject-file} 4213@itemx --reject-file=@var{reject-file} 4214Use @var{reject-file} as the reject file name. @xref{Reject Names}. 4215 4216@item -R 4217@itemx --reverse 4218Assume that this patch was created with the old and new files swapped. 4219@xref{Reversed Patches}. 4220 4221@item -s 4222@itemx --quiet 4223@itemx --silent 4224Work silently unless an error occurs. @xref{patch Messages}. 4225 4226@item -t 4227@itemx --batch 4228Do not ask any questions. @xref{patch Messages}. 4229 4230@item -T 4231@itemx --set-time 4232Set the modification and access times of patched files from time 4233stamps given in context diff headers, assuming that the context diff 4234headers use local time. @xref{Patching Time Stamps}. 4235 4236@item -u 4237@itemx --unified 4238Interpret the patch file as a unified diff. @xref{patch Input}. 4239 4240@item -v 4241@itemx --version 4242Output version information and then exit. 4243 4244@item -V @var{backup-style} 4245@itemx --version=control=@var{backup-style} 4246Select the naming convention for backup file names. @xref{Backup Names}. 4247 4248@item --verbose 4249Print more diagnostics than usual. @xref{patch Messages}. 4250 4251@item -x @var{number} 4252@itemx --debug=@var{number} 4253Set internal debugging flags. Of interest only to @command{patch} 4254patchers. 4255 4256@item -Y @var{prefix} 4257@itemx --basename-prefix=@var{prefix} 4258Prepend @var{prefix} to base names of backup files. @xref{Backup Names}. 4259 4260@item -z @var{suffix} 4261@itemx --suffix=@var{suffix} 4262Use @var{suffix} as the backup extension instead of @samp{.orig} or 4263@samp{~}. @xref{Backup Names}. 4264 4265@item -Z 4266@itemx --set-utc 4267Set the modification and access times of patched files from time 4268stamps given in context diff headers, assuming that the context diff 4269headers use @acronym{UTC}. @xref{Patching Time Stamps}. 4270 4271@end table 4272 4273@node Invoking sdiff 4274@chapter Invoking @command{sdiff} 4275@cindex invoking @command{sdiff} 4276@cindex @command{sdiff} invocation 4277 4278The @command{sdiff} command merges two files and interactively outputs the 4279results. Its arguments are as follows: 4280 4281@example 4282sdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file} 4283@end example 4284 4285This merges @var{from-file} with @var{to-file}, with output to @var{outfile}. 4286If @var{from-file} is a directory and @var{to-file} is not, @command{sdiff} 4287compares the file in @var{from-file} whose file name is that of @var{to-file}, 4288and vice versa. @var{from-file} and @var{to-file} may not both be 4289directories. 4290 4291@command{sdiff} options begin with @samp{-}, so normally @var{from-file} 4292and @var{to-file} may not begin with @samp{-}. However, @option{--} as an 4293argument by itself treats the remaining arguments as file names even if 4294they begin with @samp{-}. You may not use @file{-} as an input file. 4295 4296@command{sdiff} without @option{-o} (or @option{--output}) produces a 4297side-by-side difference. This usage is obsolete; use the @option{-y} 4298or @option{--side-by-side} option of @command{diff} instead. 4299 4300An exit status of 0 means no differences were found, 1 means some 4301differences were found, and 2 means trouble. 4302 4303@menu 4304* sdiff Options:: Summary of options to @command{diff}. 4305@end menu 4306 4307@node sdiff Options 4308@section Options to @command{sdiff} 4309@cindex @command{sdiff} options 4310@cindex options for @command{sdiff} 4311 4312Below is a summary of all of the options that @acronym{GNU} 4313@command{sdiff} accepts. Each option has two equivalent names, one of 4314which is a single letter preceded by @samp{-}, and the other of which 4315is a long name preceded by @samp{--}. Multiple single letter options 4316(unless they take an argument) can be combined into a single command 4317line argument. Long named options can be abbreviated to any unique 4318prefix of their name. 4319 4320@table @option 4321@item -a 4322@itemx --text 4323Treat all files as text and compare them line-by-line, even if they 4324do not appear to be text. @xref{Binary}. 4325 4326@item -b 4327@itemx --ignore-space-change 4328Ignore changes in amount of white space. @xref{White Space}. 4329 4330@item -B 4331@itemx --ignore-blank-lines 4332Ignore changes that just insert or delete blank lines. @xref{Blank 4333Lines}. 4334 4335@item -d 4336@itemx --minimal 4337Change the algorithm to perhaps find a smaller set of changes. This 4338makes @command{sdiff} slower (sometimes much slower). @xref{diff 4339Performance}. 4340 4341@item --diff-program=@var{program} 4342Use the compatible comparison program @var{program} to compare files 4343instead of @command{diff}. 4344 4345@item -E 4346@itemx --ignore-tab-expansion 4347Ignore changes due to tab expansion. 4348@xref{White Space}. 4349 4350@item --help 4351Output a summary of usage and then exit. 4352 4353@item -i 4354@itemx --ignore-case 4355Ignore changes in case; consider upper- and lower-case to be the same. 4356@xref{Case Folding}. 4357 4358@item -I @var{regexp} 4359@itemx --ignore-matching-lines=@var{regexp} 4360Ignore changes that just insert or delete lines that match @var{regexp}. 4361@xref{Specified Lines}. 4362 4363@item -l 4364@itemx --left-column 4365Print only the left column of two common lines. 4366@xref{Side by Side Format}. 4367 4368@item -o @var{file} 4369@itemx --output=@var{file} 4370Put merged output into @var{file}. This option is required for merging. 4371 4372@item -s 4373@itemx --suppress-common-lines 4374Do not print common lines. @xref{Side by Side Format}. 4375 4376@item --speed-large-files 4377Use heuristics to speed handling of large files that have numerous 4378scattered small changes. @xref{diff Performance}. 4379 4380@item --strip-trailing-cr 4381Strip any trailing carriage return at the end of an input line. 4382@xref{Binary}. 4383 4384@item -t 4385@itemx --expand-tabs 4386Expand tabs to spaces in the output, to preserve the alignment of tabs 4387in the input files. @xref{Tabs}. 4388 4389@item --tabsize=@var{columns} 4390Assume that tab stops are set every @var{columns} (default 8) print 4391columns. @xref{Tabs}. 4392 4393@item -v 4394@itemx --version 4395Output version information and then exit. 4396 4397@item -w @var{columns} 4398@itemx --width=@var{columns} 4399Output at most @var{columns} (default 130) print columns per line. 4400@xref{Side by Side Format}. Note that for historical reasons, this 4401option is @option{-W} in @command{diff}, @option{-w} in @command{sdiff}. 4402 4403@item -W 4404@itemx --ignore-all-space 4405Ignore white space when comparing lines. @xref{White Space}. 4406Note that for historical reasons, this option is @option{-w} in @command{diff}, 4407@option{-W} in @command{sdiff}. 4408@end table 4409 4410@node Standards conformance 4411@chapter Standards conformance 4412@cindex @acronym{POSIX} 4413 4414@vindex POSIXLY_CORRECT 4415In a few cases, the @acronym{GNU} utilities' default behavior is 4416incompatible with the @acronym{POSIX} standard. To suppress these 4417incompatibilities, define the @env{POSIXLY_CORRECT} environment 4418variable. Unless you are checking for @acronym{POSIX} conformance, you 4419probably do not need to define @env{POSIXLY_CORRECT}. 4420 4421Normally options and operands can appear in any order, and programs act 4422as if all the options appear before any operands. For example, 4423@samp{diff lao tzu -C 2} acts like @samp{diff -C 2 lao tzu}, since 4424@samp{2} is an option-argument of @option{-C}. However, if the 4425@env{POSIXLY_CORRECT} environment variable is set, options must appear 4426before operands, unless otherwise specified for a particular command. 4427 4428Newer versions of @acronym{POSIX} are occasionally incompatible with older 4429versions. For example, older versions of @acronym{POSIX} allowed the 4430command @samp{diff -c -10} to have the same meaning as @samp{diff -C 443110}, but @acronym{POSIX} 1003.1-2001 @samp{diff} no longer allows 4432digit-string options like @option{-10}. 4433 4434@vindex _POSIX2_VERSION 4435The @acronym{GNU} utilities normally conform to the version of @acronym{POSIX} 4436that is standard for your system. To cause them to conform to a 4437different version of @acronym{POSIX}, define the @env{_POSIX2_VERSION} 4438environment variable to a value of the form @var{yyyymm} specifying 4439the year and month the standard was adopted. Two values are currently 4440supported for @env{_POSIX2_VERSION}: @samp{199209} stands for 4441@acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX} 44421003.1-2001. For example, if you are running older software that 4443assumes an older version of @acronym{POSIX} and uses @samp{diff -c -10}, 4444you can work around the compatibility problems by setting 4445@samp{_POSIX2_VERSION=199209} in your environment. 4446 4447@node Projects 4448@chapter Future Projects 4449 4450Here are some ideas for improving @acronym{GNU} @command{diff} and 4451@command{patch}. The @acronym{GNU} project has identified some 4452improvements as potential programming projects for volunteers. You 4453can also help by reporting any bugs that you find. 4454 4455If you are a programmer and would like to contribute something to the 4456@acronym{GNU} project, please consider volunteering for one of these 4457projects. If you are seriously contemplating work, please write to 4458@email{gvc@@gnu.org} to coordinate with other volunteers. 4459 4460@menu 4461* Shortcomings:: Suggested projects for improvements. 4462* Bugs:: Reporting bugs. 4463@end menu 4464 4465@node Shortcomings 4466@section Suggested Projects for Improving @acronym{GNU} @command{diff} and @command{patch} 4467@cindex projects for directories 4468 4469One should be able to use @acronym{GNU} @command{diff} to generate a 4470patch from any pair of directory trees, and given the patch and a copy 4471of one such tree, use @command{patch} to generate a faithful copy of 4472the other. Unfortunately, some changes to directory trees cannot be 4473expressed using current patch formats; also, @command{patch} does not 4474handle some of the existing formats. These shortcomings motivate the 4475following suggested projects. 4476 4477@menu 4478* Internationalization:: Handling multibyte and varying-width characters. 4479* Changing Structure:: Handling changes to the directory structure. 4480* Special Files:: Handling symbolic links, device special files, etc. 4481* Unusual File Names:: Handling file names that contain unusual characters. 4482* Time Stamp Order:: Outputting diffs in time stamp order. 4483* Ignoring Changes:: Ignoring certain changes while showing others. 4484* Speedups:: Improving performance. 4485@end menu 4486 4487@node Internationalization 4488@subsection Handling Multibyte and Varying-Width Characters 4489@cindex multibyte characters 4490@cindex varying-width characters 4491 4492@command{diff}, @command{diff3} and @command{sdiff} treat each line of 4493input as a string of unibyte characters. This can mishandle multibyte 4494characters in some cases. For example, when asked to ignore spaces, 4495@command{diff} does not properly ignore a multibyte space character. 4496 4497Also, @command{diff} currently assumes that each byte is one column 4498wide, and this assumption is incorrect in some locales, e.g., locales 4499that use UTF-8 encoding. This causes problems with the @option{-y} or 4500@option{--side-by-side} option of @command{diff}. 4501 4502These problems need to be fixed without unduly affecting the 4503performance of the utilities in unibyte environments. 4504 4505The IBM GNU/Linux Technology Center Internationalization Team has 4506proposed 4507@uref{http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz,patches 4508to support internationalized @command{diff}}. 4509Unfortunately, these patches are incomplete and are to an older 4510version of @command{diff}, so more work needs to be done in this area. 4511 4512@node Changing Structure 4513@subsection Handling Changes to the Directory Structure 4514@cindex directory structure changes 4515 4516@command{diff} and @command{patch} do not handle some changes to directory 4517structure. For example, suppose one directory tree contains a directory 4518named @samp{D} with some subsidiary files, and another contains a file 4519with the same name @samp{D}. @samp{diff -r} does not output enough 4520information for @command{patch} to transform the directory subtree into 4521the file. 4522 4523There should be a way to specify that a file has been removed without 4524having to include its entire contents in the patch file. There should 4525also be a way to tell @command{patch} that a file was renamed, even if 4526there is no way for @command{diff} to generate such information. 4527There should be a way to tell @command{patch} that a file's time stamp 4528has changed, even if its contents have not changed. 4529 4530These problems can be fixed by extending the @command{diff} output format 4531to represent changes in directory structure, and extending @command{patch} 4532to understand these extensions. 4533 4534@node Special Files 4535@subsection Files that are Neither Directories Nor Regular Files 4536@cindex special files 4537 4538Some files are neither directories nor regular files: they are unusual 4539files like symbolic links, device special files, named pipes, and 4540sockets. Currently, @command{diff} treats symbolic links as if they 4541were the pointed-to files, except that a recursive @command{diff} 4542reports an error if it detects infinite loops of symbolic links (e.g., 4543symbolic links to @file{..}). @command{diff} treats other special 4544files like regular files if they are specified at the top level, but 4545simply reports their presence when comparing directories. This means 4546that @command{patch} cannot represent changes to such files. For 4547example, if you change which file a symbolic link points to, 4548@command{diff} outputs the difference between the two files, instead 4549of the change to the symbolic link. 4550 4551@c This might not be a good idea; is it wise for root to install devices 4552@c this way? 4553@command{diff} should optionally report changes to special files specially, 4554and @command{patch} should be extended to understand these extensions. 4555 4556@node Unusual File Names 4557@subsection File Names that Contain Unusual Characters 4558@cindex file names with unusual characters 4559 4560When a file name contains an unusual character like a newline or 4561white space, @samp{diff -r} generates a patch that @command{patch} cannot 4562parse. The problem is with format of @command{diff} output, not just with 4563@command{patch}, because with odd enough file names one can cause 4564@command{diff} to generate a patch that is syntactically correct but 4565patches the wrong files. The format of @command{diff} output should be 4566extended to handle all possible file names. 4567 4568@node Time Stamp Order 4569@subsection Outputting Diffs in Time Stamp Order 4570 4571Applying @command{patch} to a multiple-file diff can result in files 4572whose time stamps are out of order. @acronym{GNU} @command{patch} has 4573options to restore the time stamps of the updated files 4574(@pxref{Patching Time Stamps}), but sometimes it is useful to generate 4575a patch that works even if the recipient does not have @acronym{GNU} patch, 4576or does not use these options. One way to do this would be to 4577implement a @command{diff} option to output diffs in time stamp order. 4578 4579@node Ignoring Changes 4580@subsection Ignoring Certain Changes 4581 4582It would be nice to have a feature for specifying two strings, one in 4583@var{from-file} and one in @var{to-file}, which should be considered to 4584match. Thus, if the two strings are @samp{foo} and @samp{bar}, then if 4585two lines differ only in that @samp{foo} in file 1 corresponds to 4586@samp{bar} in file 2, the lines are treated as identical. 4587 4588It is not clear how general this feature can or should be, or 4589what syntax should be used for it. 4590 4591A partial substitute is to filter one or both files before comparing, 4592e.g.: 4593 4594@example 4595sed 's/foo/bar/g' file1 | diff - file2 4596@end example 4597 4598However, this outputs the filtered text, not the original. 4599 4600@node Speedups 4601@subsection Improving Performance 4602 4603When comparing two large directory structures, one of which was 4604originally copied from the other with time stamps preserved (e.g., 4605with @samp{cp -pR}), it would greatly improve performance if an option 4606told @command{diff} to assume that two files with the same size and 4607time stamps have the same content. @xref{diff Performance}. 4608 4609@node Bugs 4610@section Reporting Bugs 4611@cindex bug reports 4612@cindex reporting bugs 4613 4614If you think you have found a bug in @acronym{GNU} @command{cmp}, 4615@command{diff}, @command{diff3}, or @command{sdiff}, please report it 4616by electronic mail to the 4617@uref{http://mail.gnu.org/mailman/listinfo/bug-gnu-utils,GNU utilities 4618bug report mailing list} @email{bug-gnu-utils@@gnu.org}. Please send 4619bug reports for @acronym{GNU} @command{patch} to 4620@email{bug-patch@@gnu.org}. Send as precise a description of the 4621problem as you can, including the output of the @option{--version} 4622option and sample input files that produce the bug, if applicable. If 4623you have a nontrivial fix for the bug, please send it as well. If you 4624have a patch, please send it too. It may simplify the maintainer's 4625job if the patch is relative to a recent test release, which you can 4626find in the directory @uref{ftp://alpha.gnu.org/gnu/diffutils/}. 4627 4628@node Copying This Manual 4629@appendix Copying This Manual 4630 4631@menu 4632* GNU Free Documentation License:: License for copying this manual. 4633@end menu 4634 4635@include fdl.texi 4636 4637@node Translations 4638@appendix Translations of This Manual 4639 4640Nishio Futoshi of the GNUjdoc project has prepared a Japanese 4641translation of this manual. Its most recent version can be found at 4642@uref{http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/}. 4643 4644@node Index 4645@appendix Index 4646 4647@printindex cp 4648 4649@bye 4650