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