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