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