diff.texi revision 170754
1170754Sdelphij\input texinfo @c -*-texinfo-*- 2170754Sdelphij@comment $Id: diff.texi,v 1.25 2004/04/12 07:44:35 eggert Exp $ 3170754Sdelphij@comment %**start of header 4170754Sdelphij@setfilename diff.info 5170754Sdelphij@include version.texi 6170754Sdelphij@settitle Comparing and Merging Files 7170754Sdelphij@syncodeindex vr cp 8170754Sdelphij@setchapternewpage odd 9170754Sdelphij@comment %**end of header 10170754Sdelphij@copying 11170754SdelphijThis manual is for GNU Diffutils 12170754Sdelphij(version @value{VERSION}, @value{UPDATED}), 13170754Sdelphijand documents the @acronym{GNU} @command{diff}, @command{diff3}, 14170754Sdelphij@command{sdiff}, and @command{cmp} commands for showing the 15170754Sdelphijdifferences between files and the @acronym{GNU} @command{patch} command for 16170754Sdelphijusing their output to update files. 17170754Sdelphij 18170754SdelphijCopyright @copyright{} 1992, 1993, 1994, 1998, 2001, 2002, 2004 Free 19170754SdelphijSoftware Foundation, Inc. 20170754Sdelphij 21170754Sdelphij@quotation 22170754SdelphijPermission is granted to copy, distribute and/or modify this document 23170754Sdelphijunder the terms of the GNU Free Documentation License, Version 1.1 or 24170754Sdelphijany later version published by the Free Software Foundation; with no 25170754SdelphijInvariant Sections, with the Front-Cover texts being ``A GNU Manual,'' 26170754Sdelphijand with the Back-Cover Texts as in (a) below. A copy of the 27170754Sdelphijlicense is included in the section entitled ``GNU Free Documentation 28170754SdelphijLicense.'' 29170754Sdelphij 30170754Sdelphij(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify 31170754Sdelphijthis GNU Manual, like GNU software. Copies published by the Free 32170754SdelphijSoftware Foundation raise funds for GNU development.'' 33170754Sdelphij@end quotation 34170754Sdelphij@end copying 35170754Sdelphij 36170754Sdelphij@c Debian install-info (up through at least version 1.9.20) uses only the 37170754Sdelphij@c first dircategory. Put this one first, as it is more useful in practice. 38170754Sdelphij@dircategory Individual utilities 39170754Sdelphij@direntry 40170754Sdelphij* cmp: (diff)Invoking cmp. Compare 2 files byte by byte. 41170754Sdelphij* diff: (diff)Invoking diff. Compare 2 files line by line. 42170754Sdelphij* diff3: (diff)Invoking diff3. Compare 3 files line by line. 43170754Sdelphij* patch: (diff)Invoking patch. Apply a patch to a file. 44170754Sdelphij* sdiff: (diff)Invoking sdiff. Merge 2 files side-by-side. 45170754Sdelphij@end direntry 46170754Sdelphij 47170754Sdelphij@dircategory Text creation and manipulation 48170754Sdelphij@direntry 49170754Sdelphij* Diff: (diff). Comparing and merging files. 50170754Sdelphij@end direntry 51170754Sdelphij 52170754Sdelphij@titlepage 53170754Sdelphij@title Comparing and Merging Files 54170754Sdelphij@subtitle for Diffutils @value{VERSION} and @code{patch} 2.5.4 55170754Sdelphij@subtitle @value{UPDATED} 56170754Sdelphij@author David MacKenzie, Paul Eggert, and Richard Stallman 57170754Sdelphij@page 58170754Sdelphij@vskip 0pt plus 1filll 59170754Sdelphij@insertcopying 60170754Sdelphij@end titlepage 61170754Sdelphij 62170754Sdelphij@shortcontents 63170754Sdelphij@contents 64170754Sdelphij 65170754Sdelphij@ifnottex 66170754Sdelphij@node Top 67170754Sdelphij@top Comparing and Merging Files 68170754Sdelphij 69170754Sdelphij@insertcopying 70170754Sdelphij@end ifnottex 71170754Sdelphij 72170754Sdelphij@menu 73170754Sdelphij* Overview:: Preliminary information. 74170754Sdelphij* Comparison:: What file comparison means. 75170754Sdelphij 76170754Sdelphij* Output Formats:: Formats for two-way difference reports. 77170754Sdelphij* Incomplete Lines:: Lines that lack trailing newlines. 78170754Sdelphij* Comparing Directories:: Comparing files and directories. 79170754Sdelphij* Adjusting Output:: Making @command{diff} output prettier. 80170754Sdelphij* diff Performance:: Making @command{diff} smarter or faster. 81170754Sdelphij 82170754Sdelphij* Comparing Three Files:: Formats for three-way difference reports. 83170754Sdelphij* diff3 Merging:: Merging from a common ancestor. 84170754Sdelphij 85170754Sdelphij* Interactive Merging:: Interactive merging with @command{sdiff}. 86170754Sdelphij 87170754Sdelphij* Merging with patch:: Using @command{patch} to change old files into new ones. 88170754Sdelphij* Making Patches:: Tips for making and using patch distributions. 89170754Sdelphij 90170754Sdelphij* Invoking cmp:: Compare two files byte by byte. 91170754Sdelphij* Invoking diff:: Compare two files line by line. 92170754Sdelphij* Invoking diff3:: Compare three files line by line. 93170754Sdelphij* Invoking patch:: Apply a diff file to an original. 94170754Sdelphij* Invoking sdiff:: Side-by-side merge of file differences. 95170754Sdelphij 96170754Sdelphij* Standards conformance:: Conformance to the @acronym{POSIX} standard. 97170754Sdelphij* Projects:: If you've found a bug or other shortcoming. 98170754Sdelphij 99170754Sdelphij* Copying This Manual:: How to make copies of this manual. 100170754Sdelphij* Translations:: Available translations of this manual. 101170754Sdelphij* Index:: Index. 102170754Sdelphij@end menu 103170754Sdelphij 104170754Sdelphij@node Overview 105170754Sdelphij@unnumbered Overview 106170754Sdelphij@cindex overview of @command{diff} and @command{patch} 107170754Sdelphij 108170754SdelphijComputer users often find occasion to ask how two files differ. Perhaps 109170754Sdelphijone file is a newer version of the other file. Or maybe the two files 110170754Sdelphijstarted out as identical copies but were changed by different people. 111170754Sdelphij 112170754SdelphijYou can use the @command{diff} command to show differences between two 113170754Sdelphijfiles, or each corresponding file in two directories. @command{diff} 114170754Sdelphijoutputs differences between files line by line in any of several 115170754Sdelphijformats, selectable by command line options. This set of differences is 116170754Sdelphijoften called a @dfn{diff} or @dfn{patch}. For files that are identical, 117170754Sdelphij@command{diff} normally produces no output; for binary (non-text) files, 118170754Sdelphij@command{diff} normally reports only that they are different. 119170754Sdelphij 120170754SdelphijYou can use the @command{cmp} command to show the byte and line numbers 121170754Sdelphijwhere two files differ. @command{cmp} can also show all the bytes 122170754Sdelphijthat differ between the two files, side by side. A way to compare 123170754Sdelphijtwo files character by character is the Emacs command @kbd{M-x 124170754Sdelphijcompare-windows}. @xref{Other Window, , Other Window, emacs, The @acronym{GNU} 125170754SdelphijEmacs Manual}, for more information on that command. 126170754Sdelphij 127170754SdelphijYou can use the @command{diff3} command to show differences among three 128170754Sdelphijfiles. When two people have made independent changes to a common 129170754Sdelphijoriginal, @command{diff3} can report the differences between the original 130170754Sdelphijand the two changed versions, and can produce a merged file that 131170754Sdelphijcontains both persons' changes together with warnings about conflicts. 132170754Sdelphij 133170754SdelphijYou can use the @command{sdiff} command to merge two files interactively. 134170754Sdelphij 135170754SdelphijYou can use the set of differences produced by @command{diff} to distribute 136170754Sdelphijupdates to text files (such as program source code) to other people. 137170754SdelphijThis method is especially useful when the differences are small compared 138170754Sdelphijto the complete files. Given @command{diff} output, you can use the 139170754Sdelphij@command{patch} program to update, or @dfn{patch}, a copy of the file. If you 140170754Sdelphijthink of @command{diff} as subtracting one file from another to produce 141170754Sdelphijtheir difference, you can think of @command{patch} as adding the difference 142170754Sdelphijto one file to reproduce the other. 143170754Sdelphij 144170754SdelphijThis manual first concentrates on making diffs, and later shows how to 145170754Sdelphijuse diffs to update files. 146170754Sdelphij 147170754Sdelphij@acronym{GNU} @command{diff} was written by Paul Eggert, Mike Haertel, 148170754SdelphijDavid Hayes, Richard Stallman, and Len Tower. Wayne Davison designed and 149170754Sdelphijimplemented the unified output format. The basic algorithm is described 150170754Sdelphijby Eugene W. Myers in ``An O(ND) Difference Algorithm and its Variations'', 151170754Sdelphij@cite{Algorithmica} Vol.@: 1 No.@: 2, 1986, pp.@: 251--266; and in ``A File 152170754SdelphijComparison Program'', Webb Miller and Eugene W. Myers, 153170754Sdelphij@cite{Software---Practice and Experience} Vol.@: 15 No.@: 11, 1985, 154170754Sdelphijpp.@: 1025--1040. 155170754Sdelphij@c From: "Gene Myers" <gene@cs.arizona.edu> 156170754Sdelphij@c They are about the same basic algorithm; the Algorithmica 157170754Sdelphij@c paper gives a rigorous treatment and the sub-algorithm for 158170754Sdelphij@c delivering scripts and should be the primary reference, but 159170754Sdelphij@c both should be mentioned. 160170754SdelphijThe algorithm was independently discovered as described by E. Ukkonen in 161170754Sdelphij``Algorithms for Approximate String Matching'', 162170754Sdelphij@cite{Information and Control} Vol.@: 64, 1985, pp.@: 100--118. 163170754Sdelphij@c From: "Gene Myers" <gene@cs.arizona.edu> 164170754Sdelphij@c Date: Wed, 29 Sep 1993 08:27:55 MST 165170754Sdelphij@c Ukkonen should be given credit for also discovering the algorithm used 166170754Sdelphij@c in GNU diff. 167170754SdelphijUnless the @option{--minimal} option is used, @command{diff} uses a 168170754Sdelphijheuristic by Paul Eggert that limits the cost to @math{O(N^1.5 log N)} 169170754Sdelphijat the price of producing suboptimal output for large inputs with many 170170754Sdelphijdifferences. Related algorithms are surveyed by Alfred V. Aho in 171170754Sdelphijsection 6.3 of ``Algorithms for Finding Patterns in Strings'', 172170754Sdelphij@cite{Handbook of Theoretical Computer Science} (Jan Van Leeuwen, 173170754Sdelphijed.), Vol.@: A, @cite{Algorithms and Complexity}, Elsevier/MIT Press, 174170754Sdelphij1990, pp.@: 255--300. 175170754Sdelphij 176170754Sdelphij@acronym{GNU} @command{diff3} was written by Randy Smith. @acronym{GNU} 177170754Sdelphij@command{sdiff} was written by Thomas Lord. @acronym{GNU} @command{cmp} 178170754Sdelphijwas written by Torbj@"orn Granlund and David MacKenzie. 179170754Sdelphij 180170754Sdelphij@acronym{GNU} @command{patch} was written mainly by Larry Wall and Paul Eggert; 181170754Sdelphijseveral @acronym{GNU} enhancements were contributed by Wayne Davison and 182170754SdelphijDavid MacKenzie. Parts of this manual are adapted from a manual page 183170754Sdelphijwritten by Larry Wall, with his permission. 184170754Sdelphij 185170754Sdelphij@node Comparison 186170754Sdelphij@chapter What Comparison Means 187170754Sdelphij@cindex introduction 188170754Sdelphij 189170754SdelphijThere are several ways to think about the differences between two files. 190170754SdelphijOne way to think of the differences is as a series of lines that were 191170754Sdelphijdeleted from, inserted in, or changed in one file to produce the other 192170754Sdelphijfile. @command{diff} compares two files line by line, finds groups of 193170754Sdelphijlines that differ, and reports each group of differing lines. It can 194170754Sdelphijreport the differing lines in several formats, which have different 195170754Sdelphijpurposes. 196170754Sdelphij 197170754Sdelphij@acronym{GNU} @command{diff} can show whether files are different 198170754Sdelphijwithout detailing the differences. It also provides ways to suppress 199170754Sdelphijcertain kinds of differences that are not important to you. Most 200170754Sdelphijcommonly, such differences are changes in the amount of white space 201170754Sdelphijbetween words or lines. @command{diff} also provides ways to suppress 202170754Sdelphijdifferences in alphabetic case or in lines that match a regular 203170754Sdelphijexpression that you provide. These options can accumulate; for 204170754Sdelphijexample, you can ignore changes in both white space and alphabetic 205170754Sdelphijcase. 206170754Sdelphij 207170754SdelphijAnother way to think of the differences between two files is as a 208170754Sdelphijsequence of pairs of bytes that can be either identical or 209170754Sdelphijdifferent. @command{cmp} reports the differences between two files 210170754Sdelphijbyte by byte, instead of line by line. As a result, it is often 211170754Sdelphijmore useful than @command{diff} for comparing binary files. For text 212170754Sdelphijfiles, @command{cmp} is useful mainly when you want to know only whether 213170754Sdelphijtwo files are identical, or whether one file is a prefix of the other. 214170754Sdelphij 215170754SdelphijTo illustrate the effect that considering changes byte by byte 216170754Sdelphijcan have compared with considering them line by line, think of what 217170754Sdelphijhappens if a single newline character is added to the beginning of a 218170754Sdelphijfile. If that file is then compared with an otherwise identical file 219170754Sdelphijthat lacks the newline at the beginning, @command{diff} will report that a 220170754Sdelphijblank line has been added to the file, while @command{cmp} will report that 221170754Sdelphijalmost every byte of the two files differs. 222170754Sdelphij 223170754Sdelphij@command{diff3} normally compares three input files line by line, finds 224170754Sdelphijgroups of lines that differ, and reports each group of differing lines. 225170754SdelphijIts output is designed to make it easy to inspect two different sets of 226170754Sdelphijchanges to the same file. 227170754Sdelphij 228170754Sdelphij@menu 229170754Sdelphij* Hunks:: Groups of differing lines. 230170754Sdelphij* White Space:: Suppressing differences in white space. 231170754Sdelphij* Blank Lines:: Suppressing differences whose lines are all blank. 232170754Sdelphij* Specified Lines:: Suppressing differences whose lines all match a pattern. 233170754Sdelphij* Case Folding:: Suppressing differences in alphabetic case. 234170754Sdelphij* Brief:: Summarizing which files are different. 235170754Sdelphij* Binary:: Comparing binary files or forcing text comparisons. 236170754Sdelphij@end menu 237170754Sdelphij 238170754Sdelphij@node Hunks 239170754Sdelphij@section Hunks 240170754Sdelphij@cindex hunks 241170754Sdelphij 242170754SdelphijWhen comparing two files, @command{diff} finds sequences of lines common to 243170754Sdelphijboth files, interspersed with groups of differing lines called 244170754Sdelphij@dfn{hunks}. Comparing two identical files yields one sequence of 245170754Sdelphijcommon lines and no hunks, because no lines differ. Comparing two 246170754Sdelphijentirely different files yields no common lines and one large hunk that 247170754Sdelphijcontains all lines of both files. In general, there are many ways to 248170754Sdelphijmatch up lines between two given files. @command{diff} tries to minimize 249170754Sdelphijthe total hunk size by finding large sequences of common lines 250170754Sdelphijinterspersed with small hunks of differing lines. 251170754Sdelphij 252170754SdelphijFor example, suppose the file @file{F} contains the three lines 253170754Sdelphij@samp{a}, @samp{b}, @samp{c}, and the file @file{G} contains the same 254170754Sdelphijthree lines in reverse order @samp{c}, @samp{b}, @samp{a}. If 255170754Sdelphij@command{diff} finds the line @samp{c} as common, then the command 256170754Sdelphij@samp{diff F G} produces this output: 257170754Sdelphij 258170754Sdelphij@example 259170754Sdelphij1,2d0 260170754Sdelphij< a 261170754Sdelphij< b 262170754Sdelphij3a2,3 263170754Sdelphij> b 264170754Sdelphij> a 265170754Sdelphij@end example 266170754Sdelphij 267170754Sdelphij@noindent 268170754SdelphijBut if @command{diff} notices the common line @samp{b} instead, it produces 269170754Sdelphijthis output: 270170754Sdelphij 271170754Sdelphij@example 272170754Sdelphij1c1 273170754Sdelphij< a 274170754Sdelphij--- 275170754Sdelphij> c 276170754Sdelphij3c3 277170754Sdelphij< c 278170754Sdelphij--- 279170754Sdelphij> a 280170754Sdelphij@end example 281170754Sdelphij 282170754Sdelphij@noindent 283170754SdelphijIt is also possible to find @samp{a} as the common line. @command{diff} 284170754Sdelphijdoes not always find an optimal matching between the files; it takes 285170754Sdelphijshortcuts to run faster. But its output is usually close to the 286170754Sdelphijshortest possible. You can adjust this tradeoff with the 287170754Sdelphij@option{-d} or @option{--minimal} option (@pxref{diff Performance}). 288170754Sdelphij 289170754Sdelphij@node White Space 290170754Sdelphij@section Suppressing Differences in Blank and Tab Spacing 291170754Sdelphij@cindex blank and tab difference suppression 292170754Sdelphij@cindex tab and blank difference suppression 293170754Sdelphij 294170754SdelphijThe @option{-E} or @option{--ignore-tab-expansion} option ignores the 295170754Sdelphijdistinction between tabs and spaces on input. A tab is considered to be 296170754Sdelphijequivalent to the number of spaces to the next tab stop (@pxref{Tabs}). 297170754Sdelphij 298170754SdelphijThe @option{-b} or @option{--ignore-space-change} option is stronger. 299170754SdelphijIt ignores white space at line end, and considers all other sequences of 300170754Sdelphijone or more white space characters within a line to be equivalent. With this 301170754Sdelphijoption, @command{diff} considers the following two lines to be equivalent, 302170754Sdelphijwhere @samp{$} denotes the line end: 303170754Sdelphij 304170754Sdelphij@example 305170754SdelphijHere lyeth muche rychnesse in lytell space. -- John Heywood$ 306170754SdelphijHere lyeth muche rychnesse in lytell space. -- John Heywood $ 307170754Sdelphij@end example 308170754Sdelphij 309170754SdelphijThe @option{-w} or @option{--ignore-all-space} option is stronger still. 310170754SdelphijIt ignores differences even if one line has white space where 311170754Sdelphijthe other line has none. @dfn{White space} characters include 312170754Sdelphijtab, newline, vertical tab, form feed, carriage return, and space; 313170754Sdelphijsome locales may define additional characters to be white space. 314170754SdelphijWith this option, @command{diff} considers the 315170754Sdelphijfollowing two lines to be equivalent, where @samp{$} denotes the line 316170754Sdelphijend and @samp{^M} denotes a carriage return: 317170754Sdelphij 318170754Sdelphij@example 319170754SdelphijHere lyeth muche rychnesse in lytell space.-- John Heywood$ 320170754Sdelphij He relyeth much erychnes seinly tells pace. --John Heywood ^M$ 321170754Sdelphij@end example 322170754Sdelphij 323170754Sdelphij@node Blank Lines 324170754Sdelphij@section Suppressing Differences Whose Lines Are All Blank 325170754Sdelphij@cindex blank line difference suppression 326170754Sdelphij 327170754SdelphijThe @option{-B} or @option{--ignore-blank-lines} option ignores changes 328170754Sdelphijthat consist entirely of blank lines. With this option, for example, a 329170754Sdelphijfile containing 330170754Sdelphij@example 331170754Sdelphij1. A point is that which has no part. 332170754Sdelphij 333170754Sdelphij2. A line is breadthless length. 334170754Sdelphij-- Euclid, The Elements, I 335170754Sdelphij@end example 336170754Sdelphij@noindent 337170754Sdelphijis considered identical to a file containing 338170754Sdelphij@example 339170754Sdelphij1. A point is that which has no part. 340170754Sdelphij2. A line is breadthless length. 341170754Sdelphij 342170754Sdelphij 343170754Sdelphij-- Euclid, The Elements, I 344170754Sdelphij@end example 345170754Sdelphij 346170754SdelphijNormally this option affects only lines that are completely empty, but 347170754Sdelphijif you also specify the @option{-b} or @option{--ignore-space-change} 348170754Sdelphijoption, or the @option{-w} or @option{--ignore-all-space} option, 349170754Sdelphijlines are also affected if they look empty but contain white space. 350170754SdelphijIn other words, @option{-B} is equivalent to @samp{-I '^$'} by 351170754Sdelphijdefault, but it is equivalent to @option{-I '^[[:space:]]*$'} if 352170754Sdelphij@option{-b} or @option{-w} is also specified. 353170754Sdelphij 354170754Sdelphij@node Specified Lines 355170754Sdelphij@section Suppressing Differences Whose Lines All Match a Regular Expression 356170754Sdelphij@cindex regular expression suppression 357170754Sdelphij 358170754SdelphijTo ignore insertions and deletions of lines that match a 359170754Sdelphij@command{grep}-style regular expression, use the @option{-I 360170754Sdelphij@var{regexp}} or @option{--ignore-matching-lines=@var{regexp}} option. 361170754SdelphijYou should escape 362170754Sdelphijregular expressions that contain shell metacharacters to prevent the 363170754Sdelphijshell from expanding them. For example, @samp{diff -I '^[[:digit:]]'} ignores 364170754Sdelphijall changes to lines beginning with a digit. 365170754Sdelphij 366170754SdelphijHowever, @option{-I} only ignores the insertion or deletion of lines that 367170754Sdelphijcontain the regular expression if every changed line in the hunk---every 368170754Sdelphijinsertion and every deletion---matches the regular expression. In other 369170754Sdelphijwords, for each nonignorable change, @command{diff} prints the complete set 370170754Sdelphijof changes in its vicinity, including the ignorable ones. 371170754Sdelphij 372170754SdelphijYou can specify more than one regular expression for lines to ignore by 373170754Sdelphijusing more than one @option{-I} option. @command{diff} tries to match each 374170754Sdelphijline against each regular expression. 375170754Sdelphij 376170754Sdelphij@node Case Folding 377170754Sdelphij@section Suppressing Case Differences 378170754Sdelphij@cindex case difference suppression 379170754Sdelphij 380170754Sdelphij@acronym{GNU} @command{diff} can treat lower case letters as 381170754Sdelphijequivalent to their upper case counterparts, so that, for example, it 382170754Sdelphijconsiders @samp{Funky Stuff}, @samp{funky STUFF}, and @samp{fUNKy 383170754SdelphijstuFf} to all be the same. To request this, use the @option{-i} or 384170754Sdelphij@option{--ignore-case} option. 385170754Sdelphij 386170754Sdelphij@node Brief 387170754Sdelphij@section Summarizing Which Files Differ 388170754Sdelphij@cindex summarizing which files differ 389170754Sdelphij@cindex brief difference reports 390170754Sdelphij 391170754SdelphijWhen you only want to find out whether files are different, and you 392170754Sdelphijdon't care what the differences are, you can use the summary output 393170754Sdelphijformat. In this format, instead of showing the differences between the 394170754Sdelphijfiles, @command{diff} simply reports whether files differ. The @option{-q} 395170754Sdelphijor @option{--brief} option selects this output format. 396170754Sdelphij 397170754SdelphijThis format is especially useful when comparing the contents of two 398170754Sdelphijdirectories. It is also much faster than doing the normal line by line 399170754Sdelphijcomparisons, because @command{diff} can stop analyzing the files as soon as 400170754Sdelphijit knows that there are any differences. 401170754Sdelphij 402170754SdelphijYou can also get a brief indication of whether two files differ by using 403170754Sdelphij@command{cmp}. For files that are identical, @command{cmp} produces no 404170754Sdelphijoutput. When the files differ, by default, @command{cmp} outputs the byte 405170754Sdelphijand line number where the first difference occurs, or reports that one 406170754Sdelphijfile is a prefix of the other. You can use 407170754Sdelphijthe @option{-s}, @option{--quiet}, or @option{--silent} option to 408170754Sdelphijsuppress that information, so that @command{cmp} 409170754Sdelphijproduces no output and reports whether the files differ using only its 410170754Sdelphijexit status (@pxref{Invoking cmp}). 411170754Sdelphij 412170754Sdelphij@c Fix this. 413170754SdelphijUnlike @command{diff}, @command{cmp} cannot compare directories; it can only 414170754Sdelphijcompare two files. 415170754Sdelphij 416170754Sdelphij@node Binary 417170754Sdelphij@section Binary Files and Forcing Text Comparisons 418170754Sdelphij@cindex binary file diff 419170754Sdelphij@cindex text versus binary diff 420170754Sdelphij 421170754SdelphijIf @command{diff} thinks that either of the two files it is comparing is 422170754Sdelphijbinary (a non-text file), it normally treats that pair of files much as 423170754Sdelphijif the summary output format had been selected (@pxref{Brief}), and 424170754Sdelphijreports only that the binary files are different. This is because line 425170754Sdelphijby line comparisons are usually not meaningful for binary files. 426170754Sdelphij 427170754Sdelphij@command{diff} determines whether a file is text or binary by checking the 428170754Sdelphijfirst few bytes in the file; the exact number of bytes is system 429170754Sdelphijdependent, but it is typically several thousand. If every byte in 430170754Sdelphijthat part of the file is non-null, @command{diff} considers the file to be 431170754Sdelphijtext; otherwise it considers the file to be binary. 432170754Sdelphij 433170754SdelphijSometimes you might want to force @command{diff} to consider files to be 434170754Sdelphijtext. For example, you might be comparing text files that contain 435170754Sdelphijnull characters; @command{diff} would erroneously decide that those are 436170754Sdelphijnon-text files. Or you might be comparing documents that are in a 437170754Sdelphijformat used by a word processing system that uses null characters to 438170754Sdelphijindicate special formatting. You can force @command{diff} to consider all 439170754Sdelphijfiles to be text files, and compare them line by line, by using the 440170754Sdelphij@option{-a} or @option{--text} option. If the files you compare using this 441170754Sdelphijoption do not in fact contain text, they will probably contain few 442170754Sdelphijnewline characters, and the @command{diff} output will consist of hunks 443170754Sdelphijshowing differences between long lines of whatever characters the files 444170754Sdelphijcontain. 445170754Sdelphij 446170754SdelphijYou can also force @command{diff} to report only whether files differ 447170754Sdelphij(but not how). Use the @option{-q} or @option{--brief} option for 448170754Sdelphijthis. 449170754Sdelphij 450170754SdelphijNormally, differing binary files count as trouble because the 451170754Sdelphijresulting @command{diff} output does not capture all the differences. 452170754SdelphijThis trouble causes @command{diff} to exit with status 2. However, 453170754Sdelphijthis trouble cannot occur with the @option{-a} or @option{--text} 454170754Sdelphijoption, or with the @option{-q} or @option{--brief} option, as these 455170754Sdelphijoptions both cause @command{diff} to generate a form of output that 456170754Sdelphijrepresents differences as requested. 457170754Sdelphij 458170754SdelphijIn operating systems that distinguish between text and binary files, 459170754Sdelphij@command{diff} normally reads and writes all data as text. Use the 460170754Sdelphij@option{--binary} option to force @command{diff} to read and write binary 461170754Sdelphijdata instead. This option has no effect on a @acronym{POSIX}-compliant system 462170754Sdelphijlike @acronym{GNU} or traditional Unix. However, many personal computer 463170754Sdelphijoperating systems represent the end of a line with a carriage return 464170754Sdelphijfollowed by a newline. On such systems, @command{diff} normally ignores 465170754Sdelphijthese carriage returns on input and generates them at the end of each 466170754Sdelphijoutput line, but with the @option{--binary} option @command{diff} treats 467170754Sdelphijeach carriage return as just another input character, and does not 468170754Sdelphijgenerate a carriage return at the end of each output line. This can be 469170754Sdelphijuseful when dealing with non-text files that are meant to be 470170754Sdelphijinterchanged with @acronym{POSIX}-compliant systems. 471170754Sdelphij 472170754SdelphijThe @option{--strip-trailing-cr} causes @command{diff} to treat input 473170754Sdelphijlines that end in carriage return followed by newline as if they end 474170754Sdelphijin plain newline. This can be useful when comparing text that is 475170754Sdelphijimperfectly imported from many personal computer operating systems. 476170754SdelphijThis option affects how lines are read, which in turn affects how they 477170754Sdelphijare compared and output. 478170754Sdelphij 479170754SdelphijIf you want to compare two files byte by byte, you can use the 480170754Sdelphij@command{cmp} program with the @option{-l} or @option{--verbose} 481170754Sdelphijoption to show the values of each differing byte in the two files. 482170754SdelphijWith @acronym{GNU} @command{cmp}, you can also use the @option{-b} or 483170754Sdelphij@option{--print-bytes} option to show the @acronym{ASCII} representation of 484170754Sdelphijthose bytes. @xref{Invoking cmp}, for more information. 485170754Sdelphij 486170754SdelphijIf @command{diff3} thinks that any of the files it is comparing is binary 487170754Sdelphij(a non-text file), it normally reports an error, because such 488170754Sdelphijcomparisons are usually not useful. @command{diff3} uses the same test as 489170754Sdelphij@command{diff} to decide whether a file is binary. As with @command{diff}, if 490170754Sdelphijthe input files contain a few non-text bytes but otherwise are like 491170754Sdelphijtext files, you can force @command{diff3} to consider all files to be text 492170754Sdelphijfiles and compare them line by line by using the @option{-a} or 493170754Sdelphij@option{--text} option. 494170754Sdelphij 495170754Sdelphij@node Output Formats 496170754Sdelphij@chapter @command{diff} Output Formats 497170754Sdelphij@cindex output formats 498170754Sdelphij@cindex format of @command{diff} output 499170754Sdelphij 500170754Sdelphij@command{diff} has several mutually exclusive options for output format. 501170754SdelphijThe following sections describe each format, illustrating how 502170754Sdelphij@command{diff} reports the differences between two sample input files. 503170754Sdelphij 504170754Sdelphij@menu 505170754Sdelphij* Sample diff Input:: Sample @command{diff} input files for examples. 506170754Sdelphij* Context:: Showing differences with the surrounding text. 507170754Sdelphij* Side by Side:: Showing differences in two columns. 508170754Sdelphij* Normal:: Showing differences without surrounding text. 509170754Sdelphij* Scripts:: Generating scripts for other programs. 510170754Sdelphij* If-then-else:: Merging files with if-then-else. 511170754Sdelphij@end menu 512170754Sdelphij 513170754Sdelphij@node Sample diff Input 514170754Sdelphij@section Two Sample Input Files 515170754Sdelphij@cindex @command{diff} sample input 516170754Sdelphij@cindex sample input for @command{diff} 517170754Sdelphij 518170754SdelphijHere are two sample files that we will use in numerous examples to 519170754Sdelphijillustrate the output of @command{diff} and how various options can change 520170754Sdelphijit. 521170754Sdelphij 522170754SdelphijThis is the file @file{lao}: 523170754Sdelphij 524170754Sdelphij@example 525170754SdelphijThe Way that can be told of is not the eternal Way; 526170754SdelphijThe name that can be named is not the eternal name. 527170754SdelphijThe Nameless is the origin of Heaven and Earth; 528170754SdelphijThe Named is the mother of all things. 529170754SdelphijTherefore let there always be non-being, 530170754Sdelphij so we may see their subtlety, 531170754SdelphijAnd let there always be being, 532170754Sdelphij so we may see their outcome. 533170754SdelphijThe two are the same, 534170754SdelphijBut after they are produced, 535170754Sdelphij they have different names. 536170754Sdelphij@end example 537170754Sdelphij 538170754SdelphijThis is the file @file{tzu}: 539170754Sdelphij 540170754Sdelphij@example 541170754SdelphijThe Nameless is the origin of Heaven and Earth; 542170754SdelphijThe named is the mother of all things. 543170754Sdelphij 544170754SdelphijTherefore let there always be non-being, 545170754Sdelphij so we may see their subtlety, 546170754SdelphijAnd let there always be being, 547170754Sdelphij so we may see their outcome. 548170754SdelphijThe two are the same, 549170754SdelphijBut after they are produced, 550170754Sdelphij they have different names. 551170754SdelphijThey both may be called deep and profound. 552170754SdelphijDeeper and more profound, 553170754SdelphijThe door of all subtleties! 554170754Sdelphij@end example 555170754Sdelphij 556170754SdelphijIn this example, the first hunk contains just the first two lines of 557170754Sdelphij@file{lao}, the second hunk contains the fourth line of @file{lao} 558170754Sdelphijopposing the second and third lines of @file{tzu}, and the last hunk 559170754Sdelphijcontains just the last three lines of @file{tzu}. 560170754Sdelphij 561170754Sdelphij@node Context 562170754Sdelphij@section Showing Differences in Their Context 563170754Sdelphij@cindex context output format 564170754Sdelphij@cindex @samp{!} output format 565170754Sdelphij 566170754SdelphijUsually, when you are looking at the differences between files, you will 567170754Sdelphijalso want to see the parts of the files near the lines that differ, to 568170754Sdelphijhelp you understand exactly what has changed. These nearby parts of the 569170754Sdelphijfiles are called the @dfn{context}. 570170754Sdelphij 571170754Sdelphij@acronym{GNU} @command{diff} provides two output formats that show context 572170754Sdelphijaround the differing lines: @dfn{context format} and @dfn{unified 573170754Sdelphijformat}. It can optionally show in which function or section of the 574170754Sdelphijfile the differing lines are found. 575170754Sdelphij 576170754SdelphijIf you are distributing new versions of files to other people in the 577170754Sdelphijform of @command{diff} output, you should use one of the output formats 578170754Sdelphijthat show context so that they can apply the diffs even if they have 579170754Sdelphijmade small changes of their own to the files. @command{patch} can apply 580170754Sdelphijthe diffs in this case by searching in the files for the lines of 581170754Sdelphijcontext around the differing lines; if those lines are actually a few 582170754Sdelphijlines away from where the diff says they are, @command{patch} can adjust 583170754Sdelphijthe line numbers accordingly and still apply the diff correctly. 584170754Sdelphij@xref{Imperfect}, for more information on using @command{patch} to apply 585170754Sdelphijimperfect diffs. 586170754Sdelphij 587170754Sdelphij@menu 588170754Sdelphij* Context Format:: An output format that shows surrounding lines. 589170754Sdelphij* Unified Format:: A more compact output format that shows context. 590170754Sdelphij* Sections:: Showing which sections of the files differences are in. 591170754Sdelphij* Alternate Names:: Showing alternate file names in context headers. 592170754Sdelphij@end menu 593170754Sdelphij 594170754Sdelphij@node Context Format 595170754Sdelphij@subsection Context Format 596170754Sdelphij 597170754SdelphijThe context output format shows several lines of context around the 598170754Sdelphijlines that differ. It is the standard format for distributing updates 599170754Sdelphijto source code. 600170754Sdelphij 601170754SdelphijTo select this output format, use the @option{-C @var{lines}}, 602170754Sdelphij@option{--context@r{[}=@var{lines}@r{]}}, or @option{-c} option. The 603170754Sdelphijargument @var{lines} that some of these options take is the number of 604170754Sdelphijlines of context to show. If you do not specify @var{lines}, it 605170754Sdelphijdefaults to three. For proper operation, @command{patch} typically needs 606170754Sdelphijat least two lines of context. 607170754Sdelphij 608170754Sdelphij@menu 609170754Sdelphij* Example Context:: Sample output in context format. 610170754Sdelphij* Less Context:: Another sample with less context. 611170754Sdelphij* Detailed Context:: A detailed description of the context output format. 612170754Sdelphij@end menu 613170754Sdelphij 614170754Sdelphij@node Example Context 615170754Sdelphij@subsubsection An Example of Context Format 616170754Sdelphij 617170754SdelphijHere is the output of @samp{diff -c lao tzu} (@pxref{Sample diff Input}, 618170754Sdelphijfor the complete contents of the two files). Notice that up to three 619170754Sdelphijlines that are not different are shown around each line that is 620170754Sdelphijdifferent; they are the context lines. Also notice that the first two 621170754Sdelphijhunks have run together, because their contents overlap. 622170754Sdelphij 623170754Sdelphij@example 624170754Sdelphij*** lao 2002-02-21 23:30:39.942229878 -0800 625170754Sdelphij--- tzu 2002-02-21 23:30:50.442260588 -0800 626170754Sdelphij*************** 627170754Sdelphij*** 1,7 **** 628170754Sdelphij- The Way that can be told of is not the eternal Way; 629170754Sdelphij- The name that can be named is not the eternal name. 630170754Sdelphij The Nameless is the origin of Heaven and Earth; 631170754Sdelphij! The Named is the mother of all things. 632170754Sdelphij Therefore let there always be non-being, 633170754Sdelphij so we may see their subtlety, 634170754Sdelphij And let there always be being, 635170754Sdelphij--- 1,6 ---- 636170754Sdelphij The Nameless is the origin of Heaven and Earth; 637170754Sdelphij! The named is the mother of all things. 638170754Sdelphij! 639170754Sdelphij Therefore let there always be non-being, 640170754Sdelphij so we may see their subtlety, 641170754Sdelphij And let there always be being, 642170754Sdelphij*************** 643170754Sdelphij*** 9,11 **** 644170754Sdelphij--- 8,13 ---- 645170754Sdelphij The two are the same, 646170754Sdelphij But after they are produced, 647170754Sdelphij they have different names. 648170754Sdelphij+ They both may be called deep and profound. 649170754Sdelphij+ Deeper and more profound, 650170754Sdelphij+ The door of all subtleties! 651170754Sdelphij@end example 652170754Sdelphij 653170754Sdelphij@node Less Context 654170754Sdelphij@subsubsection An Example of Context Format with Less Context 655170754Sdelphij 656170754SdelphijHere is the output of @samp{diff -C 1 lao tzu} (@pxref{Sample diff 657170754SdelphijInput}, for the complete contents of the two files). Notice that at 658170754Sdelphijmost one context line is reported here. 659170754Sdelphij 660170754Sdelphij@example 661170754Sdelphij*** lao 2002-02-21 23:30:39.942229878 -0800 662170754Sdelphij--- tzu 2002-02-21 23:30:50.442260588 -0800 663170754Sdelphij*************** 664170754Sdelphij*** 1,5 **** 665170754Sdelphij- The Way that can be told of is not the eternal Way; 666170754Sdelphij- The name that can be named is not the eternal name. 667170754Sdelphij The Nameless is the origin of Heaven and Earth; 668170754Sdelphij! The Named is the mother of all things. 669170754Sdelphij Therefore let there always be non-being, 670170754Sdelphij--- 1,4 ---- 671170754Sdelphij The Nameless is the origin of Heaven and Earth; 672170754Sdelphij! The named is the mother of all things. 673170754Sdelphij! 674170754Sdelphij Therefore let there always be non-being, 675170754Sdelphij*************** 676170754Sdelphij*** 11 **** 677170754Sdelphij--- 10,13 ---- 678170754Sdelphij they have different names. 679170754Sdelphij+ They both may be called deep and profound. 680170754Sdelphij+ Deeper and more profound, 681170754Sdelphij+ The door of all subtleties! 682170754Sdelphij@end example 683170754Sdelphij 684170754Sdelphij@node Detailed Context 685170754Sdelphij@subsubsection Detailed Description of Context Format 686170754Sdelphij 687170754SdelphijThe context output format starts with a two-line header, which looks 688170754Sdelphijlike this: 689170754Sdelphij 690170754Sdelphij@example 691170754Sdelphij*** @var{from-file} @var{from-file-modification-time} 692170754Sdelphij--- @var{to-file} @var{to-file-modification time} 693170754Sdelphij@end example 694170754Sdelphij 695170754Sdelphij@noindent 696170754Sdelphij@vindex LC_TIME 697170754Sdelphij@cindex time stamp format, context diffs 698170754SdelphijThe time stamp normally looks like @samp{2002-02-21 23:30:39.942229878 699170754Sdelphij-0800} to indicate the date, time with fractional seconds, and time 700170754Sdelphijzone in @uref{ftp://ftp.isi.edu/in-notes/rfc2822.txt, Internet RFC 701170754Sdelphij2822 format}. (The fractional seconds are omitted on hosts that do 702170754Sdelphijnot support fractional time stamps.) However, a traditional time 703170754Sdelphijstamp like @samp{Thu Feb 21 23:30:39 2002} is used if the 704170754Sdelphij@env{LC_TIME} locale category is either @samp{C} or @samp{POSIX}. 705170754Sdelphij 706170754SdelphijYou can change the header's content with the 707170754Sdelphij@option{--label=@var{label}} option; see @ref{Alternate Names}. 708170754Sdelphij 709170754SdelphijNext come one or more hunks of differences; each hunk shows one area 710170754Sdelphijwhere the files differ. Context format hunks look like this: 711170754Sdelphij 712170754Sdelphij@example 713170754Sdelphij*************** 714170754Sdelphij*** @var{from-file-line-numbers} **** 715170754Sdelphij @var{from-file-line} 716170754Sdelphij @var{from-file-line}@dots{} 717170754Sdelphij--- @var{to-file-line-numbers} ---- 718170754Sdelphij @var{to-file-line} 719170754Sdelphij @var{to-file-line}@dots{} 720170754Sdelphij@end example 721170754Sdelphij 722170754SdelphijIf a hunk contains two or more lines, its line numbers look like 723170754Sdelphij@samp{@var{start},@var{end}}. Otherwise only its end line number 724170754Sdelphijappears. An empty hunk is considered to end at the line that precedes 725170754Sdelphijthe hunk. 726170754Sdelphij 727170754SdelphijThe lines of context around the lines that differ start with two space 728170754Sdelphijcharacters. The lines that differ between the two files start with one 729170754Sdelphijof the following indicator characters, followed by a space character: 730170754Sdelphij 731170754Sdelphij@table @samp 732170754Sdelphij@item ! 733170754SdelphijA line that is part of a group of one or more lines that changed between 734170754Sdelphijthe two files. There is a corresponding group of lines marked with 735170754Sdelphij@samp{!} in the part of this hunk for the other file. 736170754Sdelphij 737170754Sdelphij@item + 738170754SdelphijAn ``inserted'' line in the second file that corresponds to nothing in 739170754Sdelphijthe first file. 740170754Sdelphij 741170754Sdelphij@item - 742170754SdelphijA ``deleted'' line in the first file that corresponds to nothing in the 743170754Sdelphijsecond file. 744170754Sdelphij@end table 745170754Sdelphij 746170754SdelphijIf all of the changes in a hunk are insertions, the lines of 747170754Sdelphij@var{from-file} are omitted. If all of the changes are deletions, the 748170754Sdelphijlines of @var{to-file} are omitted. 749170754Sdelphij 750170754Sdelphij@node Unified Format 751170754Sdelphij@subsection Unified Format 752170754Sdelphij@cindex unified output format 753170754Sdelphij@cindex @samp{+-} output format 754170754Sdelphij 755170754SdelphijThe unified output format is a variation on the context format that is 756170754Sdelphijmore compact because it omits redundant context lines. To select this 757170754Sdelphijoutput format, use the @option{-U @var{lines}}, 758170754Sdelphij@option{--unified@r{[}=@var{lines}@r{]}}, or @option{-u} 759170754Sdelphijoption. The argument @var{lines} is the number of lines of context to 760170754Sdelphijshow. When it is not given, it defaults to three. 761170754Sdelphij 762170754SdelphijAt present, only @acronym{GNU} @command{diff} can produce this format and 763170754Sdelphijonly @acronym{GNU} @command{patch} can automatically apply diffs in this 764170754Sdelphijformat. For proper operation, @command{patch} typically needs at 765170754Sdelphijleast three lines of context. 766170754Sdelphij 767170754Sdelphij@menu 768170754Sdelphij* Example Unified:: Sample output in unified format. 769170754Sdelphij* Detailed Unified:: A detailed description of unified format. 770170754Sdelphij@end menu 771170754Sdelphij 772170754Sdelphij@node Example Unified 773170754Sdelphij@subsubsection An Example of Unified Format 774170754Sdelphij 775170754SdelphijHere is the output of the command @samp{diff -u lao tzu} 776170754Sdelphij(@pxref{Sample diff Input}, for the complete contents of the two files): 777170754Sdelphij 778170754Sdelphij@example 779170754Sdelphij--- lao 2002-02-21 23:30:39.942229878 -0800 780170754Sdelphij+++ tzu 2002-02-21 23:30:50.442260588 -0800 781170754Sdelphij@@@@ -1,7 +1,6 @@@@ 782170754Sdelphij-The Way that can be told of is not the eternal Way; 783170754Sdelphij-The name that can be named is not the eternal name. 784170754Sdelphij The Nameless is the origin of Heaven and Earth; 785170754Sdelphij-The Named is the mother of all things. 786170754Sdelphij+The named is the mother of all things. 787170754Sdelphij+ 788170754Sdelphij Therefore let there always be non-being, 789170754Sdelphij so we may see their subtlety, 790170754Sdelphij And let there always be being, 791170754Sdelphij@@@@ -9,3 +8,6 @@@@ 792170754Sdelphij The two are the same, 793170754Sdelphij But after they are produced, 794170754Sdelphij they have different names. 795170754Sdelphij+They both may be called deep and profound. 796170754Sdelphij+Deeper and more profound, 797170754Sdelphij+The door of all subtleties! 798170754Sdelphij@end example 799170754Sdelphij 800170754Sdelphij@node Detailed Unified 801170754Sdelphij@subsubsection Detailed Description of Unified Format 802170754Sdelphij 803170754SdelphijThe unified output format starts with a two-line header, which looks 804170754Sdelphijlike this: 805170754Sdelphij 806170754Sdelphij@example 807170754Sdelphij--- @var{from-file} @var{from-file-modification-time} 808170754Sdelphij+++ @var{to-file} @var{to-file-modification-time} 809170754Sdelphij@end example 810170754Sdelphij 811170754Sdelphij@noindent 812170754Sdelphij@cindex time stamp format, unified diffs 813170754SdelphijThe time stamp looks like @samp{2002-02-21 23:30:39.942229878 -0800} 814170754Sdelphijto indicate the date, time with fractional seconds, and time zone. 815170754SdelphijThe fractional seconds are omitted on hosts that do not support 816170754Sdelphijfractional time stamps. 817170754Sdelphij 818170754SdelphijYou can change the header's content with the 819170754Sdelphij@option{--label=@var{label}} option; see @xref{Alternate Names}. 820170754Sdelphij 821170754SdelphijNext come one or more hunks of differences; each hunk shows one area 822170754Sdelphijwhere the files differ. Unified format hunks look like this: 823170754Sdelphij 824170754Sdelphij@example 825170754Sdelphij@@@@ @var{from-file-line-numbers} @var{to-file-line-numbers} @@@@ 826170754Sdelphij @var{line-from-either-file} 827170754Sdelphij @var{line-from-either-file}@dots{} 828170754Sdelphij@end example 829170754Sdelphij 830170754SdelphijIf a hunk contains just one line, only its start line number appears. 831170754SdelphijOtherwise its line numbers look like @samp{@var{start},@var{count}}. 832170754SdelphijAn empty hunk is considered to start at the line that follows the hunk. 833170754Sdelphij 834170754SdelphijIf a hunk and its context contain two or more lines, its 835170754Sdelphijline numbers look like @samp{@var{start},@var{count}}. Otherwise only 836170754Sdelphijits end line number appears. An empty hunk is considered to end at 837170754Sdelphijthe line that precedes the hunk. 838170754Sdelphij 839170754SdelphijThe lines common to both files begin with a space character. The lines 840170754Sdelphijthat actually differ between the two files have one of the following 841170754Sdelphijindicator characters in the left print column: 842170754Sdelphij 843170754Sdelphij@table @samp 844170754Sdelphij@item + 845170754SdelphijA line was added here to the first file. 846170754Sdelphij 847170754Sdelphij@item - 848170754SdelphijA line was removed here from the first file. 849170754Sdelphij@end table 850170754Sdelphij 851170754Sdelphij@node Sections 852170754Sdelphij@subsection Showing Which Sections Differences Are in 853170754Sdelphij@cindex headings 854170754Sdelphij@cindex section headings 855170754Sdelphij 856170754SdelphijSometimes you might want to know which part of the files each change 857170754Sdelphijfalls in. If the files are source code, this could mean which 858170754Sdelphijfunction was changed. If the files are documents, it could mean which 859170754Sdelphijchapter or appendix was changed. @acronym{GNU} @command{diff} can 860170754Sdelphijshow this by displaying the nearest section heading line that precedes 861170754Sdelphijthe differing lines. Which lines are ``section headings'' is 862170754Sdelphijdetermined by a regular expression. 863170754Sdelphij 864170754Sdelphij@menu 865170754Sdelphij* Specified Headings:: Showing headings that match regular expressions. 866170754Sdelphij* C Function Headings:: Showing headings of C functions. 867170754Sdelphij@end menu 868170754Sdelphij 869170754Sdelphij@node Specified Headings 870170754Sdelphij@subsubsection Showing Lines That Match Regular Expressions 871170754Sdelphij@cindex specified headings 872170754Sdelphij@cindex regular expression matching headings 873170754Sdelphij 874170754SdelphijTo show in which sections differences occur for files that are not 875170754Sdelphijsource code for C or similar languages, use the @option{-F @var{regexp}} 876170754Sdelphijor @option{--show-function-line=@var{regexp}} option. @command{diff} 877170754Sdelphijconsiders lines that match the @command{grep}-style regular expression 878170754Sdelphij@var{regexp} to be the beginning 879170754Sdelphijof a section of the file. Here are suggested regular expressions for 880170754Sdelphijsome common languages: 881170754Sdelphij 882170754Sdelphij@c Please add to this list, e.g. Fortran, Pascal, Perl, Python. 883170754Sdelphij@table @samp 884170754Sdelphij@item ^[[:alpha:]$_] 885170754SdelphijC, C++, Prolog 886170754Sdelphij@item ^( 887170754SdelphijLisp 888170754Sdelphij@item ^@@node 889170754SdelphijTexinfo 890170754Sdelphij@end table 891170754Sdelphij 892170754SdelphijThis option does not automatically select an output format; in order to 893170754Sdelphijuse it, you must select the context format (@pxref{Context Format}) or 894170754Sdelphijunified format (@pxref{Unified Format}). In other output formats it 895170754Sdelphijhas no effect. 896170754Sdelphij 897170754SdelphijThe @option{-F} or @option{--show-function-line} option finds the nearest 898170754Sdelphijunchanged line that precedes each hunk of differences and matches the 899170754Sdelphijgiven regular expression. Then it adds that line to the end of the 900170754Sdelphijline of asterisks in the context format, or to the @samp{@@@@} line in 901170754Sdelphijunified format. If no matching line exists, this option leaves the output for 902170754Sdelphijthat hunk unchanged. If that line is more than 40 characters long, it 903170754Sdelphijoutputs only the first 40 characters. You can specify more than one 904170754Sdelphijregular expression for such lines; @command{diff} tries to match each line 905170754Sdelphijagainst each regular expression, starting with the last one given. This 906170754Sdelphijmeans that you can use @option{-p} and @option{-F} together, if you wish. 907170754Sdelphij 908170754Sdelphij@node C Function Headings 909170754Sdelphij@subsubsection Showing C Function Headings 910170754Sdelphij@cindex C function headings 911170754Sdelphij@cindex function headings, C 912170754Sdelphij 913170754SdelphijTo show in which functions differences occur for C and similar 914170754Sdelphijlanguages, you can use the @option{-p} or @option{--show-c-function} option. 915170754SdelphijThis option automatically defaults to the context output format 916170754Sdelphij(@pxref{Context Format}), with the default number of lines of context. 917170754SdelphijYou can override that number with @option{-C @var{lines}} elsewhere in the 918170754Sdelphijcommand line. You can override both the format and the number with 919170754Sdelphij@option{-U @var{lines}} elsewhere in the command line. 920170754Sdelphij 921170754SdelphijThe @option{-p} or @option{--show-c-function} option is equivalent to 922170754Sdelphij@option{-F '^[[:alpha:]$_]'} if the unified format is specified, otherwise 923170754Sdelphij@option{-c -F '^[[:alpha:]$_]'} (@pxref{Specified Headings}). @acronym{GNU} 924170754Sdelphij@command{diff} provides this option for the sake of convenience. 925170754Sdelphij 926170754Sdelphij@node Alternate Names 927170754Sdelphij@subsection Showing Alternate File Names 928170754Sdelphij@cindex alternate file names 929170754Sdelphij@cindex file name alternates 930170754Sdelphij 931170754SdelphijIf you are comparing two files that have meaningless or uninformative 932170754Sdelphijnames, you might want @command{diff} to show alternate names in the header 933170754Sdelphijof the context and unified output formats. To do this, use the 934170754Sdelphij@option{--label=@var{label}} option. The first time 935170754Sdelphijyou give this option, its argument replaces the name and date of the 936170754Sdelphijfirst file in the header; the second time, its argument replaces the 937170754Sdelphijname and date of the second file. If you give this option more than 938170754Sdelphijtwice, @command{diff} reports an error. The @option{--label} option does not 939170754Sdelphijaffect the file names in the @command{pr} header when the @option{-l} or 940170754Sdelphij@option{--paginate} option is used (@pxref{Pagination}). 941170754Sdelphij 942170754SdelphijHere are the first two lines of the output from @samp{diff -C 2 943170754Sdelphij--label=original --label=modified lao tzu}: 944170754Sdelphij 945170754Sdelphij@example 946170754Sdelphij*** original 947170754Sdelphij--- modified 948170754Sdelphij@end example 949170754Sdelphij 950170754Sdelphij@node Side by Side 951170754Sdelphij@section Showing Differences Side by Side 952170754Sdelphij@cindex side by side 953170754Sdelphij@cindex two-column output 954170754Sdelphij@cindex columnar output 955170754Sdelphij 956170754Sdelphij@command{diff} can produce a side by side difference listing of two files. 957170754SdelphijThe files are listed in two columns with a gutter between them. The 958170754Sdelphijgutter contains one of the following markers: 959170754Sdelphij 960170754Sdelphij@table @asis 961170754Sdelphij@item white space 962170754SdelphijThe corresponding lines are in common. That is, either the lines are 963170754Sdelphijidentical, or the difference is ignored because of one of the 964170754Sdelphij@option{--ignore} options (@pxref{White Space}). 965170754Sdelphij 966170754Sdelphij@item @samp{|} 967170754SdelphijThe corresponding lines differ, and they are either both complete 968170754Sdelphijor both incomplete. 969170754Sdelphij 970170754Sdelphij@item @samp{<} 971170754SdelphijThe files differ and only the first file contains the line. 972170754Sdelphij 973170754Sdelphij@item @samp{>} 974170754SdelphijThe files differ and only the second file contains the line. 975170754Sdelphij 976170754Sdelphij@item @samp{(} 977170754SdelphijOnly the first file contains the line, but the difference is ignored. 978170754Sdelphij 979170754Sdelphij@item @samp{)} 980170754SdelphijOnly the second file contains the line, but the difference is ignored. 981170754Sdelphij 982170754Sdelphij@item @samp{\} 983170754SdelphijThe corresponding lines differ, and only the first line is incomplete. 984170754Sdelphij 985170754Sdelphij@item @samp{/} 986170754SdelphijThe corresponding lines differ, and only the second line is incomplete. 987170754Sdelphij@end table 988170754Sdelphij 989170754SdelphijNormally, an output line is incomplete if and only if the lines that it 990170754Sdelphijcontains are incomplete; @xref{Incomplete Lines}. However, when an 991170754Sdelphijoutput line represents two differing lines, one might be incomplete 992170754Sdelphijwhile the other is not. In this case, the output line is complete, 993170754Sdelphijbut its the gutter is marked @samp{\} if the first line is incomplete, 994170754Sdelphij@samp{/} if the second line is. 995170754Sdelphij 996170754SdelphijSide by side format is sometimes easiest to read, but it has limitations. 997170754SdelphijIt generates much wider output than usual, and truncates lines that are 998170754Sdelphijtoo long to fit. Also, it relies on lining up output more heavily than 999170754Sdelphijusual, so its output looks particularly bad if you use varying 1000170754Sdelphijwidth fonts, nonstandard tab stops, or nonprinting characters. 1001170754Sdelphij 1002170754SdelphijYou can use the @command{sdiff} command to interactively merge side by side 1003170754Sdelphijdifferences. @xref{Interactive Merging}, for more information on merging files. 1004170754Sdelphij 1005170754Sdelphij@menu 1006170754Sdelphij* Side by Side Format:: Controlling side by side output format. 1007170754Sdelphij* Example Side by Side:: Sample side by side output. 1008170754Sdelphij@end menu 1009170754Sdelphij 1010170754Sdelphij@node Side by Side Format 1011170754Sdelphij@subsection Controlling Side by Side Format 1012170754Sdelphij@cindex side by side format 1013170754Sdelphij 1014170754SdelphijThe @option{-y} or @option{--side-by-side} option selects side by side 1015170754Sdelphijformat. Because side by side output lines contain two input lines, the 1016170754Sdelphijoutput is wider than usual: normally 130 print columns, which can fit 1017170754Sdelphijonto a traditional printer line. You can set the width of the output 1018170754Sdelphijwith the @option{-W @var{columns}} or @option{--width=@var{columns}} 1019170754Sdelphijoption. The output is split into two halves of equal width, separated by a 1020170754Sdelphijsmall gutter to mark differences; the right half is aligned to a tab 1021170754Sdelphijstop so that tabs line up. Input lines that are too long to fit in half 1022170754Sdelphijof an output line are truncated for output. 1023170754Sdelphij 1024170754SdelphijThe @option{--left-column} option prints only the left column of two 1025170754Sdelphijcommon lines. The @option{--suppress-common-lines} option suppresses 1026170754Sdelphijcommon lines entirely. 1027170754Sdelphij 1028170754Sdelphij@node Example Side by Side 1029170754Sdelphij@subsection An Example of Side by Side Format 1030170754Sdelphij 1031170754SdelphijHere is the output of the command @samp{diff -y -W 72 lao tzu} 1032170754Sdelphij(@pxref{Sample diff Input}, for the complete contents of the two files). 1033170754Sdelphij 1034170754Sdelphij@example 1035170754SdelphijThe Way that can be told of is n < 1036170754SdelphijThe name that can be named is no < 1037170754SdelphijThe Nameless is the origin of He The Nameless is the origin of He 1038170754SdelphijThe Named is the mother of all t | The named is the mother of all t 1039170754Sdelphij > 1040170754SdelphijTherefore let there always be no Therefore let there always be no 1041170754Sdelphij so we may see their subtlety, so we may see their subtlety, 1042170754SdelphijAnd let there always be being, And let there always be being, 1043170754Sdelphij so we may see their outcome. so we may see their outcome. 1044170754SdelphijThe two are the same, The two are the same, 1045170754SdelphijBut after they are produced, But after they are produced, 1046170754Sdelphij they have different names. they have different names. 1047170754Sdelphij > They both may be called deep and 1048170754Sdelphij > Deeper and more profound, 1049170754Sdelphij > The door of all subtleties! 1050170754Sdelphij@end example 1051170754Sdelphij 1052170754Sdelphij@node Normal 1053170754Sdelphij@section Showing Differences Without Context 1054170754Sdelphij@cindex normal output format 1055170754Sdelphij@cindex @samp{<} output format 1056170754Sdelphij 1057170754SdelphijThe ``normal'' @command{diff} output format shows each hunk of differences 1058170754Sdelphijwithout any surrounding context. Sometimes such output is the clearest 1059170754Sdelphijway to see how lines have changed, without the clutter of nearby 1060170754Sdelphijunchanged lines (although you can get similar results with the context 1061170754Sdelphijor unified formats by using 0 lines of context). However, this format 1062170754Sdelphijis no longer widely used for sending out patches; for that purpose, the 1063170754Sdelphijcontext format (@pxref{Context Format}) and the unified format 1064170754Sdelphij(@pxref{Unified Format}) are superior. Normal format is the default for 1065170754Sdelphijcompatibility with older versions of @command{diff} and the @acronym{POSIX} 1066170754Sdelphijstandard. Use the @option{--normal} option to select this output 1067170754Sdelphijformat explicitly. 1068170754Sdelphij 1069170754Sdelphij@menu 1070170754Sdelphij* Example Normal:: Sample output in the normal format. 1071170754Sdelphij* Detailed Normal:: A detailed description of normal output format. 1072170754Sdelphij@end menu 1073170754Sdelphij 1074170754Sdelphij@node Example Normal 1075170754Sdelphij@subsection An Example of Normal Format 1076170754Sdelphij 1077170754SdelphijHere is the output of the command @samp{diff lao tzu} 1078170754Sdelphij(@pxref{Sample diff Input}, for the complete contents of the two files). 1079170754SdelphijNotice that it shows only the lines that are different between the two 1080170754Sdelphijfiles. 1081170754Sdelphij 1082170754Sdelphij@example 1083170754Sdelphij1,2d0 1084170754Sdelphij< The Way that can be told of is not the eternal Way; 1085170754Sdelphij< The name that can be named is not the eternal name. 1086170754Sdelphij4c2,3 1087170754Sdelphij< The Named is the mother of all things. 1088170754Sdelphij--- 1089170754Sdelphij> The named is the mother of all things. 1090170754Sdelphij> 1091170754Sdelphij11a11,13 1092170754Sdelphij> They both may be called deep and profound. 1093170754Sdelphij> Deeper and more profound, 1094170754Sdelphij> The door of all subtleties! 1095170754Sdelphij@end example 1096170754Sdelphij 1097170754Sdelphij@node Detailed Normal 1098170754Sdelphij@subsection Detailed Description of Normal Format 1099170754Sdelphij 1100170754SdelphijThe normal output format consists of one or more hunks of differences; 1101170754Sdelphijeach hunk shows one area where the files differ. Normal format hunks 1102170754Sdelphijlook like this: 1103170754Sdelphij 1104170754Sdelphij@example 1105170754Sdelphij@var{change-command} 1106170754Sdelphij< @var{from-file-line} 1107170754Sdelphij< @var{from-file-line}@dots{} 1108170754Sdelphij--- 1109170754Sdelphij> @var{to-file-line} 1110170754Sdelphij> @var{to-file-line}@dots{} 1111170754Sdelphij@end example 1112170754Sdelphij 1113170754SdelphijThere are three types of change commands. Each consists of a line 1114170754Sdelphijnumber or comma-separated range of lines in the first file, a single 1115170754Sdelphijcharacter indicating the kind of change to make, and a line number or 1116170754Sdelphijcomma-separated range of lines in the second file. All line numbers are 1117170754Sdelphijthe original line numbers in each file. The types of change commands 1118170754Sdelphijare: 1119170754Sdelphij 1120170754Sdelphij@table @samp 1121170754Sdelphij@item @var{l}a@var{r} 1122170754SdelphijAdd the lines in range @var{r} of the second file after line @var{l} of 1123170754Sdelphijthe first file. For example, @samp{8a12,15} means append lines 12--15 1124170754Sdelphijof file 2 after line 8 of file 1; or, if changing file 2 into file 1, 1125170754Sdelphijdelete lines 12--15 of file 2. 1126170754Sdelphij 1127170754Sdelphij@item @var{f}c@var{t} 1128170754SdelphijReplace the lines in range @var{f} of the first file with lines in range 1129170754Sdelphij@var{t} of the second file. This is like a combined add and delete, but 1130170754Sdelphijmore compact. For example, @samp{5,7c8,10} means change lines 5--7 of 1131170754Sdelphijfile 1 to read as lines 8--10 of file 2; or, if changing file 2 into 1132170754Sdelphijfile 1, change lines 8--10 of file 2 to read as lines 5--7 of file 1. 1133170754Sdelphij 1134170754Sdelphij@item @var{r}d@var{l} 1135170754SdelphijDelete the lines in range @var{r} from the first file; line @var{l} is where 1136170754Sdelphijthey would have appeared in the second file had they not been deleted. 1137170754SdelphijFor example, @samp{5,7d3} means delete lines 5--7 of file 1; or, if 1138170754Sdelphijchanging file 2 into file 1, append lines 5--7 of file 1 after line 3 of 1139170754Sdelphijfile 2. 1140170754Sdelphij@end table 1141170754Sdelphij 1142170754Sdelphij@node Scripts 1143170754Sdelphij@section Making Edit Scripts 1144170754Sdelphij@cindex script output formats 1145170754Sdelphij 1146170754SdelphijSeveral output modes produce command scripts for editing @var{from-file} 1147170754Sdelphijto produce @var{to-file}. 1148170754Sdelphij 1149170754Sdelphij@menu 1150170754Sdelphij* ed Scripts:: Using @command{diff} to produce commands for @command{ed}. 1151170754Sdelphij* Forward ed:: Making forward @command{ed} scripts. 1152170754Sdelphij* RCS:: A special @command{diff} output format used by @acronym{RCS}. 1153170754Sdelphij@end menu 1154170754Sdelphij 1155170754Sdelphij@node ed Scripts 1156170754Sdelphij@subsection @command{ed} Scripts 1157170754Sdelphij@cindex @command{ed} script output format 1158170754Sdelphij 1159170754Sdelphij@command{diff} can produce commands that direct the @command{ed} text editor 1160170754Sdelphijto change the first file into the second file. Long ago, this was the 1161170754Sdelphijonly output mode that was suitable for editing one file into another 1162170754Sdelphijautomatically; today, with @command{patch}, it is almost obsolete. Use the 1163170754Sdelphij@option{-e} or @option{--ed} option to select this output format. 1164170754Sdelphij 1165170754SdelphijLike the normal format (@pxref{Normal}), this output format does not 1166170754Sdelphijshow any context; unlike the normal format, it does not include the 1167170754Sdelphijinformation necessary to apply the diff in reverse (to produce the first 1168170754Sdelphijfile if all you have is the second file and the diff). 1169170754Sdelphij 1170170754SdelphijIf the file @file{d} contains the output of @samp{diff -e old new}, then 1171170754Sdelphijthe command @samp{(cat d && echo w) | ed - old} edits @file{old} to make 1172170754Sdelphijit a copy of @file{new}. More generally, if @file{d1}, @file{d2}, 1173170754Sdelphij@dots{}, @file{dN} contain the outputs of @samp{diff -e old new1}, 1174170754Sdelphij@samp{diff -e new1 new2}, @dots{}, @samp{diff -e newN-1 newN}, 1175170754Sdelphijrespectively, then the command @samp{(cat d1 d2 @dots{} dN && echo w) | 1176170754Sdelphijed - old} edits @file{old} to make it a copy of @file{newN}. 1177170754Sdelphij 1178170754Sdelphij@menu 1179170754Sdelphij* Example ed:: A sample @command{ed} script. 1180170754Sdelphij* Detailed ed:: A detailed description of @command{ed} format. 1181170754Sdelphij@end menu 1182170754Sdelphij 1183170754Sdelphij@node Example ed 1184170754Sdelphij@subsubsection Example @command{ed} Script 1185170754Sdelphij 1186170754SdelphijHere is the output of @samp{diff -e lao tzu} (@pxref{Sample 1187170754Sdelphijdiff Input}, for the complete contents of the two files): 1188170754Sdelphij 1189170754Sdelphij@example 1190170754Sdelphij11a 1191170754SdelphijThey both may be called deep and profound. 1192170754SdelphijDeeper and more profound, 1193170754SdelphijThe door of all subtleties! 1194170754Sdelphij. 1195170754Sdelphij4c 1196170754SdelphijThe named is the mother of all things. 1197170754Sdelphij 1198170754Sdelphij. 1199170754Sdelphij1,2d 1200170754Sdelphij@end example 1201170754Sdelphij 1202170754Sdelphij@node Detailed ed 1203170754Sdelphij@subsubsection Detailed Description of @command{ed} Format 1204170754Sdelphij 1205170754SdelphijThe @command{ed} output format consists of one or more hunks of 1206170754Sdelphijdifferences. The changes closest to the ends of the files come first so 1207170754Sdelphijthat commands that change the number of lines do not affect how 1208170754Sdelphij@command{ed} interprets line numbers in succeeding commands. @command{ed} 1209170754Sdelphijformat hunks look like this: 1210170754Sdelphij 1211170754Sdelphij@example 1212170754Sdelphij@var{change-command} 1213170754Sdelphij@var{to-file-line} 1214170754Sdelphij@var{to-file-line}@dots{} 1215170754Sdelphij. 1216170754Sdelphij@end example 1217170754Sdelphij 1218170754SdelphijBecause @command{ed} uses a single period on a line to indicate the 1219170754Sdelphijend of input, @acronym{GNU} @command{diff} protects lines of changes 1220170754Sdelphijthat contain a single period on a line by writing two periods instead, 1221170754Sdelphijthen writing a subsequent @command{ed} command to change the two 1222170754Sdelphijperiods into one. The @command{ed} format cannot represent an 1223170754Sdelphijincomplete line, so if the second file ends in a changed incomplete 1224170754Sdelphijline, @command{diff} reports an error and then pretends that a newline 1225170754Sdelphijwas appended. 1226170754Sdelphij 1227170754SdelphijThere are three types of change commands. Each consists of a line 1228170754Sdelphijnumber or comma-separated range of lines in the first file and a single 1229170754Sdelphijcharacter indicating the kind of change to make. All line numbers are 1230170754Sdelphijthe original line numbers in the file. The types of change commands 1231170754Sdelphijare: 1232170754Sdelphij 1233170754Sdelphij@table @samp 1234170754Sdelphij@item @var{l}a 1235170754SdelphijAdd text from the second file after line @var{l} in the first file. For 1236170754Sdelphijexample, @samp{8a} means to add the following lines after line 8 of file 1237170754Sdelphij1. 1238170754Sdelphij 1239170754Sdelphij@item @var{r}c 1240170754SdelphijReplace the lines in range @var{r} in the first file with the following 1241170754Sdelphijlines. Like a combined add and delete, but more compact. For example, 1242170754Sdelphij@samp{5,7c} means change lines 5--7 of file 1 to read as the text file 1243170754Sdelphij2. 1244170754Sdelphij 1245170754Sdelphij@item @var{r}d 1246170754SdelphijDelete the lines in range @var{r} from the first file. For example, 1247170754Sdelphij@samp{5,7d} means delete lines 5--7 of file 1. 1248170754Sdelphij@end table 1249170754Sdelphij 1250170754Sdelphij@node Forward ed 1251170754Sdelphij@subsection Forward @command{ed} Scripts 1252170754Sdelphij@cindex forward @command{ed} script output format 1253170754Sdelphij 1254170754Sdelphij@command{diff} can produce output that is like an @command{ed} script, but 1255170754Sdelphijwith hunks in forward (front to back) order. The format of the commands 1256170754Sdelphijis also changed slightly: command characters precede the lines they 1257170754Sdelphijmodify, spaces separate line numbers in ranges, and no attempt is made 1258170754Sdelphijto disambiguate hunk lines consisting of a single period. Like 1259170754Sdelphij@command{ed} format, forward @command{ed} format cannot represent incomplete 1260170754Sdelphijlines. 1261170754Sdelphij 1262170754SdelphijForward @command{ed} format is not very useful, because neither @command{ed} 1263170754Sdelphijnor @command{patch} can apply diffs in this format. It exists mainly for 1264170754Sdelphijcompatibility with older versions of @command{diff}. Use the @option{-f} or 1265170754Sdelphij@option{--forward-ed} option to select it. 1266170754Sdelphij 1267170754Sdelphij@node RCS 1268170754Sdelphij@subsection @acronym{RCS} Scripts 1269170754Sdelphij@cindex @acronym{RCS} script output format 1270170754Sdelphij 1271170754SdelphijThe @acronym{RCS} output format is designed specifically for use by 1272170754Sdelphijthe Revision Control System, which is a set of free programs used for 1273170754Sdelphijorganizing different versions and systems of files. Use the 1274170754Sdelphij@option{-n} or @option{--rcs} option to select this output format. It 1275170754Sdelphijis like the forward @command{ed} format (@pxref{Forward ed}), but it 1276170754Sdelphijcan represent arbitrary changes to the contents of a file because it 1277170754Sdelphijavoids the forward @command{ed} format's problems with lines 1278170754Sdelphijconsisting of a single period and with incomplete lines. Instead of 1279170754Sdelphijending text sections with a line consisting of a single period, each 1280170754Sdelphijcommand specifies the number of lines it affects; a combination of the 1281170754Sdelphij@samp{a} and @samp{d} commands are used instead of @samp{c}. Also, if 1282170754Sdelphijthe second file ends in a changed incomplete line, then the output 1283170754Sdelphijalso ends in an incomplete line. 1284170754Sdelphij 1285170754SdelphijHere is the output of @samp{diff -n lao tzu} (@pxref{Sample 1286170754Sdelphijdiff Input}, for the complete contents of the two files): 1287170754Sdelphij 1288170754Sdelphij@example 1289170754Sdelphijd1 2 1290170754Sdelphijd4 1 1291170754Sdelphija4 2 1292170754SdelphijThe named is the mother of all things. 1293170754Sdelphij 1294170754Sdelphija11 3 1295170754SdelphijThey both may be called deep and profound. 1296170754SdelphijDeeper and more profound, 1297170754SdelphijThe door of all subtleties! 1298170754Sdelphij@end example 1299170754Sdelphij 1300170754Sdelphij@node If-then-else 1301170754Sdelphij@section Merging Files with If-then-else 1302170754Sdelphij@cindex merged output format 1303170754Sdelphij@cindex if-then-else output format 1304170754Sdelphij@cindex C if-then-else output format 1305170754Sdelphij@cindex @command{ifdef} output format 1306170754Sdelphij 1307170754SdelphijYou can use @command{diff} to merge two files of C source code. The output 1308170754Sdelphijof @command{diff} in this format contains all the lines of both files. 1309170754SdelphijLines common to both files are output just once; the differing parts are 1310170754Sdelphijseparated by the C preprocessor directives @code{#ifdef @var{name}} or 1311170754Sdelphij@code{#ifndef @var{name}}, @code{#else}, and @code{#endif}. When 1312170754Sdelphijcompiling the output, you select which version to use by either defining 1313170754Sdelphijor leaving undefined the macro @var{name}. 1314170754Sdelphij 1315170754SdelphijTo merge two files, use @command{diff} with the @option{-D @var{name}} or 1316170754Sdelphij@option{--ifdef=@var{name}} option. The argument @var{name} is the C 1317170754Sdelphijpreprocessor identifier to use in the @code{#ifdef} and @code{#ifndef} 1318170754Sdelphijdirectives. 1319170754Sdelphij 1320170754SdelphijFor example, if you change an instance of @code{wait (&s)} to 1321170754Sdelphij@code{waitpid (-1, &s, 0)} and then merge the old and new files with 1322170754Sdelphijthe @option{--ifdef=HAVE_WAITPID} option, then the affected part of your code 1323170754Sdelphijmight look like this: 1324170754Sdelphij 1325170754Sdelphij@example 1326170754Sdelphij do @{ 1327170754Sdelphij#ifndef HAVE_WAITPID 1328170754Sdelphij if ((w = wait (&s)) < 0 && errno != EINTR) 1329170754Sdelphij#else /* HAVE_WAITPID */ 1330170754Sdelphij if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR) 1331170754Sdelphij#endif /* HAVE_WAITPID */ 1332170754Sdelphij return w; 1333170754Sdelphij @} while (w != child); 1334170754Sdelphij@end example 1335170754Sdelphij 1336170754SdelphijYou can specify formats for languages other than C by using line group 1337170754Sdelphijformats and line formats, as described in the next sections. 1338170754Sdelphij 1339170754Sdelphij@menu 1340170754Sdelphij* Line Group Formats:: Formats for general if-then-else line groups. 1341170754Sdelphij* Line Formats:: Formats for each line in a line group. 1342170754Sdelphij* Example If-then-else:: Sample if-then-else format output. 1343170754Sdelphij* Detailed If-then-else:: A detailed description of if-then-else format. 1344170754Sdelphij@end menu 1345170754Sdelphij 1346170754Sdelphij@node Line Group Formats 1347170754Sdelphij@subsection Line Group Formats 1348170754Sdelphij@cindex line group formats 1349170754Sdelphij@cindex formats for if-then-else line groups 1350170754Sdelphij 1351170754SdelphijLine group formats let you specify formats suitable for many 1352170754Sdelphijapplications that allow if-then-else input, including programming 1353170754Sdelphijlanguages and text formatting languages. A line group format specifies 1354170754Sdelphijthe output format for a contiguous group of similar lines. 1355170754Sdelphij 1356170754SdelphijFor example, the following command compares the TeX files @file{old} 1357170754Sdelphijand @file{new}, and outputs a merged file in which old regions are 1358170754Sdelphijsurrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 1359170754Sdelphijregions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 1360170754Sdelphij 1361170754Sdelphij@example 1362170754Sdelphijdiff \ 1363170754Sdelphij --old-group-format='\begin@{em@} 1364170754Sdelphij%<\end@{em@} 1365170754Sdelphij' \ 1366170754Sdelphij --new-group-format='\begin@{bf@} 1367170754Sdelphij%>\end@{bf@} 1368170754Sdelphij' \ 1369170754Sdelphij old new 1370170754Sdelphij@end example 1371170754Sdelphij 1372170754SdelphijThe following command is equivalent to the above example, but it is a 1373170754Sdelphijlittle more verbose, because it spells out the default line group formats. 1374170754Sdelphij 1375170754Sdelphij@example 1376170754Sdelphijdiff \ 1377170754Sdelphij --old-group-format='\begin@{em@} 1378170754Sdelphij%<\end@{em@} 1379170754Sdelphij' \ 1380170754Sdelphij --new-group-format='\begin@{bf@} 1381170754Sdelphij%>\end@{bf@} 1382170754Sdelphij' \ 1383170754Sdelphij --unchanged-group-format='%=' \ 1384170754Sdelphij --changed-group-format='\begin@{em@} 1385170754Sdelphij%<\end@{em@} 1386170754Sdelphij\begin@{bf@} 1387170754Sdelphij%>\end@{bf@} 1388170754Sdelphij' \ 1389170754Sdelphij old new 1390170754Sdelphij@end example 1391170754Sdelphij 1392170754SdelphijHere is a more advanced example, which outputs a diff listing with 1393170754Sdelphijheaders containing line numbers in a ``plain English'' style. 1394170754Sdelphij 1395170754Sdelphij@example 1396170754Sdelphijdiff \ 1397170754Sdelphij --unchanged-group-format='' \ 1398170754Sdelphij --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 1399170754Sdelphij%<' \ 1400170754Sdelphij --new-group-format='-------- %dN line%(N=1?:s) added after %de: 1401170754Sdelphij%>' \ 1402170754Sdelphij --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 1403170754Sdelphij%<-------- to: 1404170754Sdelphij%>' \ 1405170754Sdelphij old new 1406170754Sdelphij@end example 1407170754Sdelphij 1408170754SdelphijTo specify a line group format, use @command{diff} with one of the options 1409170754Sdelphijlisted below. You can specify up to four line group formats, one for 1410170754Sdelphijeach kind of line group. You should quote @var{format}, because it 1411170754Sdelphijtypically contains shell metacharacters. 1412170754Sdelphij 1413170754Sdelphij@table @option 1414170754Sdelphij@item --old-group-format=@var{format} 1415170754SdelphijThese line groups are hunks containing only lines from the first file. 1416170754SdelphijThe default old group format is the same as the changed group format if 1417170754Sdelphijit is specified; otherwise it is a format that outputs the line group as-is. 1418170754Sdelphij 1419170754Sdelphij@item --new-group-format=@var{format} 1420170754SdelphijThese line groups are hunks containing only lines from the second 1421170754Sdelphijfile. The default new group format is same as the changed group 1422170754Sdelphijformat if it is specified; otherwise it is a format that outputs the 1423170754Sdelphijline group as-is. 1424170754Sdelphij 1425170754Sdelphij@item --changed-group-format=@var{format} 1426170754SdelphijThese line groups are hunks containing lines from both files. The 1427170754Sdelphijdefault changed group format is the concatenation of the old and new 1428170754Sdelphijgroup formats. 1429170754Sdelphij 1430170754Sdelphij@item --unchanged-group-format=@var{format} 1431170754SdelphijThese line groups contain lines common to both files. The default 1432170754Sdelphijunchanged group format is a format that outputs the line group as-is. 1433170754Sdelphij@end table 1434170754Sdelphij 1435170754SdelphijIn a line group format, ordinary characters represent themselves; 1436170754Sdelphijconversion specifications start with @samp{%} and have one of the 1437170754Sdelphijfollowing forms. 1438170754Sdelphij 1439170754Sdelphij@table @samp 1440170754Sdelphij@item %< 1441170754Sdelphijstands for the lines from the first file, including the trailing newline. 1442170754SdelphijEach line is formatted according to the old line format (@pxref{Line Formats}). 1443170754Sdelphij 1444170754Sdelphij@item %> 1445170754Sdelphijstands for the lines from the second file, including the trailing newline. 1446170754SdelphijEach line is formatted according to the new line format. 1447170754Sdelphij 1448170754Sdelphij@item %= 1449170754Sdelphijstands for the lines common to both files, including the trailing newline. 1450170754SdelphijEach line is formatted according to the unchanged line format. 1451170754Sdelphij 1452170754Sdelphij@item %% 1453170754Sdelphijstands for @samp{%}. 1454170754Sdelphij 1455170754Sdelphij@item %c'@var{C}' 1456170754Sdelphijwhere @var{C} is a single character, stands for @var{C}. 1457170754Sdelphij@var{C} may not be a backslash or an apostrophe. 1458170754SdelphijFor example, @samp{%c':'} stands for a colon, even inside 1459170754Sdelphijthe then-part of an if-then-else format, which a colon would 1460170754Sdelphijnormally terminate. 1461170754Sdelphij 1462170754Sdelphij@item %c'\@var{O}' 1463170754Sdelphijwhere @var{O} is a string of 1, 2, or 3 octal digits, 1464170754Sdelphijstands for the character with octal code @var{O}. 1465170754SdelphijFor example, @samp{%c'\0'} stands for a null character. 1466170754Sdelphij 1467170754Sdelphij@item @var{F}@var{n} 1468170754Sdelphijwhere @var{F} is a @code{printf} conversion specification and @var{n} is one 1469170754Sdelphijof the following letters, stands for @var{n}'s value formatted with @var{F}. 1470170754Sdelphij 1471170754Sdelphij@table @samp 1472170754Sdelphij@item e 1473170754SdelphijThe line number of the line just before the group in the old file. 1474170754Sdelphij 1475170754Sdelphij@item f 1476170754SdelphijThe line number of the first line in the group in the old file; 1477170754Sdelphijequals @var{e} + 1. 1478170754Sdelphij 1479170754Sdelphij@item l 1480170754SdelphijThe line number of the last line in the group in the old file. 1481170754Sdelphij 1482170754Sdelphij@item m 1483170754SdelphijThe line number of the line just after the group in the old file; 1484170754Sdelphijequals @var{l} + 1. 1485170754Sdelphij 1486170754Sdelphij@item n 1487170754SdelphijThe number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 1488170754Sdelphij 1489170754Sdelphij@item E, F, L, M, N 1490170754SdelphijLikewise, for lines in the new file. 1491170754Sdelphij 1492170754Sdelphij@end table 1493170754Sdelphij 1494170754Sdelphij@vindex LC_NUMERIC 1495170754SdelphijThe @code{printf} conversion specification can be @samp{%d}, 1496170754Sdelphij@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 1497170754Sdelphijlower case hexadecimal, or upper case hexadecimal output 1498170754Sdelphijrespectively. After the @samp{%} the following options can appear in 1499170754Sdelphijsequence: a series of zero or more flags; an integer 1500170754Sdelphijspecifying the minimum field width; and a period followed by an 1501170754Sdelphijoptional integer specifying the minimum number of digits. 1502170754SdelphijThe flags are @samp{-} for left-justification, @samp{'} for separating 1503170754Sdelphijthe digit into groups as specified by the @env{LC_NUMERIC} locale category, 1504170754Sdelphijand @samp{0} for padding with zeros instead of spaces. 1505170754SdelphijFor example, @samp{%5dN} prints the number of new lines in the group 1506170754Sdelphijin a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 1507170754Sdelphij 1508170754Sdelphij@item (@var{A}=@var{B}?@var{T}:@var{E}) 1509170754SdelphijIf @var{A} equals @var{B} then @var{T} else @var{E}. 1510170754Sdelphij@var{A} and @var{B} are each either a decimal constant 1511170754Sdelphijor a single letter interpreted as above. 1512170754SdelphijThis format spec is equivalent to @var{T} if 1513170754Sdelphij@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 1514170754Sdelphij 1515170754SdelphijFor example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 1516170754Sdelphij@samp{no lines} if @var{N} (the number of lines in the group in the 1517170754Sdelphijnew file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 1518170754Sdelphijotherwise. 1519170754Sdelphij@end table 1520170754Sdelphij 1521170754Sdelphij@node Line Formats 1522170754Sdelphij@subsection Line Formats 1523170754Sdelphij@cindex line formats 1524170754Sdelphij 1525170754SdelphijLine formats control how each line taken from an input file is 1526170754Sdelphijoutput as part of a line group in if-then-else format. 1527170754Sdelphij 1528170754SdelphijFor example, the following command outputs text with a one-character 1529170754Sdelphijchange indicator to the left of the text. The first character of output 1530170754Sdelphijis @samp{-} for deleted lines, @samp{|} for added lines, and a space for 1531170754Sdelphijunchanged lines. The formats contain newline characters where newlines 1532170754Sdelphijare desired on output. 1533170754Sdelphij 1534170754Sdelphij@example 1535170754Sdelphijdiff \ 1536170754Sdelphij --old-line-format='-%l 1537170754Sdelphij' \ 1538170754Sdelphij --new-line-format='|%l 1539170754Sdelphij' \ 1540170754Sdelphij --unchanged-line-format=' %l 1541170754Sdelphij' \ 1542170754Sdelphij old new 1543170754Sdelphij@end example 1544170754Sdelphij 1545170754SdelphijTo specify a line format, use one of the following options. You should 1546170754Sdelphijquote @var{format}, since it often contains shell metacharacters. 1547170754Sdelphij 1548170754Sdelphij@table @option 1549170754Sdelphij@item --old-line-format=@var{format} 1550170754Sdelphijformats lines just from the first file. 1551170754Sdelphij 1552170754Sdelphij@item --new-line-format=@var{format} 1553170754Sdelphijformats lines just from the second file. 1554170754Sdelphij 1555170754Sdelphij@item --unchanged-line-format=@var{format} 1556170754Sdelphijformats lines common to both files. 1557170754Sdelphij 1558170754Sdelphij@item --line-format=@var{format} 1559170754Sdelphijformats all lines; in effect, it sets all three above options simultaneously. 1560170754Sdelphij@end table 1561170754Sdelphij 1562170754SdelphijIn a line format, ordinary characters represent themselves; 1563170754Sdelphijconversion specifications start with @samp{%} and have one of the 1564170754Sdelphijfollowing forms. 1565170754Sdelphij 1566170754Sdelphij@table @samp 1567170754Sdelphij@item %l 1568170754Sdelphijstands for the contents of the line, not counting its trailing 1569170754Sdelphijnewline (if any). This format ignores whether the line is incomplete; 1570170754Sdelphij@xref{Incomplete Lines}. 1571170754Sdelphij 1572170754Sdelphij@item %L 1573170754Sdelphijstands for the contents of the line, including its trailing newline 1574170754Sdelphij(if any). If a line is incomplete, this format preserves its 1575170754Sdelphijincompleteness. 1576170754Sdelphij 1577170754Sdelphij@item %% 1578170754Sdelphijstands for @samp{%}. 1579170754Sdelphij 1580170754Sdelphij@item %c'@var{C}' 1581170754Sdelphijwhere @var{C} is a single character, stands for @var{C}. 1582170754Sdelphij@var{C} may not be a backslash or an apostrophe. 1583170754SdelphijFor example, @samp{%c':'} stands for a colon. 1584170754Sdelphij 1585170754Sdelphij@item %c'\@var{O}' 1586170754Sdelphijwhere @var{O} is a string of 1, 2, or 3 octal digits, 1587170754Sdelphijstands for the character with octal code @var{O}. 1588170754SdelphijFor example, @samp{%c'\0'} stands for a null character. 1589170754Sdelphij 1590170754Sdelphij@item @var{F}n 1591170754Sdelphijwhere @var{F} is a @code{printf} conversion specification, 1592170754Sdelphijstands for the line number formatted with @var{F}. 1593170754SdelphijFor example, @samp{%.5dn} prints the line number using the 1594170754Sdelphij@code{printf} format @code{"%.5d"}. @xref{Line Group Formats}, for 1595170754Sdelphijmore about printf conversion specifications. 1596170754Sdelphij 1597170754Sdelphij@end table 1598170754Sdelphij 1599170754SdelphijThe default line format is @samp{%l} followed by a newline character. 1600170754Sdelphij 1601170754SdelphijIf the input contains tab characters and it is important that they line 1602170754Sdelphijup on output, you should ensure that @samp{%l} or @samp{%L} in a line 1603170754Sdelphijformat is just after a tab stop (e.g.@: by preceding @samp{%l} or 1604170754Sdelphij@samp{%L} with a tab character), or you should use the @option{-t} or 1605170754Sdelphij@option{--expand-tabs} option. 1606170754Sdelphij 1607170754SdelphijTaken together, the line and line group formats let you specify many 1608170754Sdelphijdifferent formats. For example, the following command uses a format 1609170754Sdelphijsimilar to normal @command{diff} format. You can tailor this command 1610170754Sdelphijto get fine control over @command{diff} output. 1611170754Sdelphij 1612170754Sdelphij@example 1613170754Sdelphijdiff \ 1614170754Sdelphij --old-line-format='< %l 1615170754Sdelphij' \ 1616170754Sdelphij --new-line-format='> %l 1617170754Sdelphij' \ 1618170754Sdelphij --old-group-format='%df%(f=l?:,%dl)d%dE 1619170754Sdelphij%<' \ 1620170754Sdelphij --new-group-format='%dea%dF%(F=L?:,%dL) 1621170754Sdelphij%>' \ 1622170754Sdelphij --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 1623170754Sdelphij%<--- 1624170754Sdelphij%>' \ 1625170754Sdelphij --unchanged-group-format='' \ 1626170754Sdelphij old new 1627170754Sdelphij@end example 1628170754Sdelphij 1629170754Sdelphij@node Example If-then-else 1630170754Sdelphij@subsection An Example of If-then-else Format 1631170754Sdelphij 1632170754SdelphijHere is the output of @samp{diff -DTWO lao tzu} (@pxref{Sample 1633170754Sdelphijdiff Input}, for the complete contents of the two files): 1634170754Sdelphij 1635170754Sdelphij@example 1636170754Sdelphij#ifndef TWO 1637170754SdelphijThe Way that can be told of is not the eternal Way; 1638170754SdelphijThe name that can be named is not the eternal name. 1639170754Sdelphij#endif /* ! TWO */ 1640170754SdelphijThe Nameless is the origin of Heaven and Earth; 1641170754Sdelphij#ifndef TWO 1642170754SdelphijThe Named is the mother of all things. 1643170754Sdelphij#else /* TWO */ 1644170754SdelphijThe named is the mother of all things. 1645170754Sdelphij 1646170754Sdelphij#endif /* TWO */ 1647170754SdelphijTherefore let there always be non-being, 1648170754Sdelphij so we may see their subtlety, 1649170754SdelphijAnd let there always be being, 1650170754Sdelphij so we may see their outcome. 1651170754SdelphijThe two are the same, 1652170754SdelphijBut after they are produced, 1653170754Sdelphij they have different names. 1654170754Sdelphij#ifdef TWO 1655170754SdelphijThey both may be called deep and profound. 1656170754SdelphijDeeper and more profound, 1657170754SdelphijThe door of all subtleties! 1658170754Sdelphij#endif /* TWO */ 1659170754Sdelphij@end example 1660170754Sdelphij 1661170754Sdelphij@node Detailed If-then-else 1662170754Sdelphij@subsection Detailed Description of If-then-else Format 1663170754Sdelphij 1664170754SdelphijFor lines common to both files, @command{diff} uses the unchanged line 1665170754Sdelphijgroup format. For each hunk of differences in the merged output 1666170754Sdelphijformat, if the hunk contains only lines from the first file, 1667170754Sdelphij@command{diff} uses the old line group format; if the hunk contains only 1668170754Sdelphijlines from the second file, @command{diff} uses the new group format; 1669170754Sdelphijotherwise, @command{diff} uses the changed group format. 1670170754Sdelphij 1671170754SdelphijThe old, new, and unchanged line formats specify the output format of 1672170754Sdelphijlines from the first file, lines from the second file, and lines common 1673170754Sdelphijto both files, respectively. 1674170754Sdelphij 1675170754SdelphijThe option @option{--ifdef=@var{name}} is equivalent to 1676170754Sdelphijthe following sequence of options using shell syntax: 1677170754Sdelphij 1678170754Sdelphij@example 1679170754Sdelphij--old-group-format='#ifndef @var{name} 1680170754Sdelphij%<#endif /* ! @var{name} */ 1681170754Sdelphij' \ 1682170754Sdelphij--new-group-format='#ifdef @var{name} 1683170754Sdelphij%>#endif /* @var{name} */ 1684170754Sdelphij' \ 1685170754Sdelphij--unchanged-group-format='%=' \ 1686170754Sdelphij--changed-group-format='#ifndef @var{name} 1687170754Sdelphij%<#else /* @var{name} */ 1688170754Sdelphij%>#endif /* @var{name} */ 1689170754Sdelphij' 1690170754Sdelphij@end example 1691170754Sdelphij 1692170754SdelphijYou should carefully check the @command{diff} output for proper nesting. 1693170754SdelphijFor example, when using the @option{-D @var{name}} or 1694170754Sdelphij@option{--ifdef=@var{name}} option, you should check that if the 1695170754Sdelphijdiffering lines contain any of the C preprocessor directives 1696170754Sdelphij@samp{#ifdef}, @samp{#ifndef}, @samp{#else}, @samp{#elif}, or 1697170754Sdelphij@samp{#endif}, they are nested properly and match. If they don't, you 1698170754Sdelphijmust make corrections manually. It is a good idea to carefully check 1699170754Sdelphijthe resulting code anyway to make sure that it really does what you 1700170754Sdelphijwant it to; depending on how the input files were produced, the output 1701170754Sdelphijmight contain duplicate or otherwise incorrect code. 1702170754Sdelphij 1703170754SdelphijThe @command{patch} @option{-D @var{name}} option behaves like 1704170754Sdelphijthe @command{diff} @option{-D @var{name}} option, except it operates on 1705170754Sdelphija file and a diff to produce a merged file; @xref{patch Options}. 1706170754Sdelphij 1707170754Sdelphij@node Incomplete Lines 1708170754Sdelphij@chapter Incomplete Lines 1709170754Sdelphij@cindex incomplete lines 1710170754Sdelphij@cindex full lines 1711170754Sdelphij@cindex newline treatment by @command{diff} 1712170754Sdelphij 1713170754SdelphijWhen an input file ends in a non-newline character, its last line is 1714170754Sdelphijcalled an @dfn{incomplete line} because its last character is not a 1715170754Sdelphijnewline. All other lines are called @dfn{full lines} and end in a 1716170754Sdelphijnewline character. Incomplete lines do not match full lines unless 1717170754Sdelphijdifferences in white space are ignored (@pxref{White Space}). 1718170754Sdelphij 1719170754SdelphijAn incomplete line is normally distinguished on output from a full 1720170754Sdelphijline by a following line that starts with @samp{\}. However, the 1721170754Sdelphij@acronym{RCS} format (@pxref{RCS}) outputs the incomplete line as-is, 1722170754Sdelphijwithout any trailing newline or following line. The side by side 1723170754Sdelphijformat normally represents incomplete lines as-is, but in some cases 1724170754Sdelphijuses a @samp{\} or @samp{/} gutter marker; @xref{Side by Side}. The 1725170754Sdelphijif-then-else line format preserves a line's incompleteness with 1726170754Sdelphij@samp{%L}, and discards the newline with @samp{%l}; @xref{Line 1727170754SdelphijFormats}. Finally, with the @command{ed} and forward @command{ed} 1728170754Sdelphijoutput formats (@pxref{Output Formats}) @command{diff} cannot 1729170754Sdelphijrepresent an incomplete line, so it pretends there was a newline and 1730170754Sdelphijreports an error. 1731170754Sdelphij 1732170754SdelphijFor example, suppose @file{F} and @file{G} are one-byte files that 1733170754Sdelphijcontain just @samp{f} and @samp{g}, respectively. Then @samp{diff F G} 1734170754Sdelphijoutputs 1735170754Sdelphij 1736170754Sdelphij@example 1737170754Sdelphij1c1 1738170754Sdelphij< f 1739170754Sdelphij\ No newline at end of file 1740170754Sdelphij--- 1741170754Sdelphij> g 1742170754Sdelphij\ No newline at end of file 1743170754Sdelphij@end example 1744170754Sdelphij 1745170754Sdelphij@noindent 1746170754Sdelphij(The exact message may differ in non-English locales.) 1747170754Sdelphij@samp{diff -n F G} outputs the following without a trailing newline: 1748170754Sdelphij 1749170754Sdelphij@example 1750170754Sdelphijd1 1 1751170754Sdelphija1 1 1752170754Sdelphijg 1753170754Sdelphij@end example 1754170754Sdelphij 1755170754Sdelphij@noindent 1756170754Sdelphij@samp{diff -e F G} reports two errors and outputs the following: 1757170754Sdelphij 1758170754Sdelphij@example 1759170754Sdelphij1c 1760170754Sdelphijg 1761170754Sdelphij. 1762170754Sdelphij@end example 1763170754Sdelphij 1764170754Sdelphij@node Comparing Directories 1765170754Sdelphij@chapter Comparing Directories 1766170754Sdelphij 1767170754Sdelphij@vindex LC_COLLATE 1768170754SdelphijYou can use @command{diff} to compare some or all of the files in two 1769170754Sdelphijdirectory trees. When both file name arguments to @command{diff} are 1770170754Sdelphijdirectories, it compares each file that is contained in both 1771170754Sdelphijdirectories, examining file names in alphabetical order as specified by 1772170754Sdelphijthe @env{LC_COLLATE} locale category. Normally 1773170754Sdelphij@command{diff} is silent about pairs of files that contain no differences, 1774170754Sdelphijbut if you use the @option{-s} or @option{--report-identical-files} option, 1775170754Sdelphijit reports pairs of identical files. Normally @command{diff} reports 1776170754Sdelphijsubdirectories common to both directories without comparing 1777170754Sdelphijsubdirectories' files, but if you use the @option{-r} or 1778170754Sdelphij@option{--recursive} option, it compares every corresponding pair of files 1779170754Sdelphijin the directory trees, as many levels deep as they go. 1780170754Sdelphij 1781170754SdelphijFor file names that are in only one of the directories, @command{diff} 1782170754Sdelphijnormally does not show the contents of the file that exists; it reports 1783170754Sdelphijonly that the file exists in that directory and not in the other. You 1784170754Sdelphijcan make @command{diff} act as though the file existed but was empty in the 1785170754Sdelphijother directory, so that it outputs the entire contents of the file that 1786170754Sdelphijactually exists. (It is output as either an insertion or a 1787170754Sdelphijdeletion, depending on whether it is in the first or the second 1788170754Sdelphijdirectory given.) To do this, use the @option{-N} or @option{--new-file} 1789170754Sdelphijoption. 1790170754Sdelphij 1791170754SdelphijIf the older directory contains one or more large files that are not in 1792170754Sdelphijthe newer directory, you can make the patch smaller by using the 1793170754Sdelphij@option{--unidirectional-new-file} option instead of @option{-N}. 1794170754SdelphijThis option is like @option{-N} except that it only inserts the contents 1795170754Sdelphijof files that appear in the second directory but not the first (that is, 1796170754Sdelphijfiles that were added). At the top of the patch, write instructions for 1797170754Sdelphijthe user applying the patch to remove the files that were deleted before 1798170754Sdelphijapplying the patch. @xref{Making Patches}, for more discussion of 1799170754Sdelphijmaking patches for distribution. 1800170754Sdelphij 1801170754SdelphijTo ignore some files while comparing directories, use the @option{-x 1802170754Sdelphij@var{pattern}} or @option{--exclude=@var{pattern}} option. This option 1803170754Sdelphijignores any files or subdirectories whose base names match the shell 1804170754Sdelphijpattern @var{pattern}. Unlike in the shell, a period at the start of 1805170754Sdelphijthe base of a file name matches a wildcard at the start of a pattern. 1806170754SdelphijYou should enclose @var{pattern} in quotes so that the shell does not 1807170754Sdelphijexpand it. For example, the option @option{-x '*.[ao]'} ignores any file 1808170754Sdelphijwhose name ends with @samp{.a} or @samp{.o}. 1809170754Sdelphij 1810170754SdelphijThis option accumulates if you specify it more than once. For example, 1811170754Sdelphijusing the options @option{-x 'RCS' -x '*,v'} ignores any file or 1812170754Sdelphijsubdirectory whose base name is @samp{RCS} or ends with @samp{,v}. 1813170754Sdelphij 1814170754SdelphijIf you need to give this option many times, you can instead put the 1815170754Sdelphijpatterns in a file, one pattern per line, and use the @option{-X 1816170754Sdelphij@var{file}} or @option{--exclude-from=@var{file}} option. Trailing 1817170754Sdelphijwhite space and empty lines are ignored in the pattern file. 1818170754Sdelphij 1819170754SdelphijIf you have been comparing two directories and stopped partway through, 1820170754Sdelphijlater you might want to continue where you left off. You can do this by 1821170754Sdelphijusing the @option{-S @var{file}} or @option{--starting-file=@var{file}} 1822170754Sdelphijoption. This compares only the file @var{file} and all alphabetically 1823170754Sdelphijlater files in the topmost directory level. 1824170754Sdelphij 1825170754SdelphijIf two directories differ only in that file names are lower case in 1826170754Sdelphijone directory and upper case in the upper, @command{diff} normally 1827170754Sdelphijreports many differences because it compares file names in a 1828170754Sdelphijcase sensitive way. With the @option{--ignore-file-name-case} option, 1829170754Sdelphij@command{diff} ignores case differences in file names, so that for example 1830170754Sdelphijthe contents of the file @file{Tao} in one directory are compared to 1831170754Sdelphijthe contents of the file @file{TAO} in the other. The 1832170754Sdelphij@option{--no-ignore-file-name-case} option cancels the effect of the 1833170754Sdelphij@option{--ignore-file-name-case} option, reverting to the default 1834170754Sdelphijbehavior. 1835170754Sdelphij 1836170754SdelphijIf an @option{-x @var{pattern}} or @option{--exclude=@var{pattern}} 1837170754Sdelphijoption, or an @option{-X @var{file}} or 1838170754Sdelphij@option{--exclude-from=@var{file}} option, 1839170754Sdelphijis specified while the @option{--ignore-file-name-case} option is in 1840170754Sdelphijeffect, case is ignored when excluding file names matching the 1841170754Sdelphijspecified patterns. 1842170754Sdelphij 1843170754Sdelphij@node Adjusting Output 1844170754Sdelphij@chapter Making @command{diff} Output Prettier 1845170754Sdelphij 1846170754Sdelphij@command{diff} provides several ways to adjust the appearance of its output. 1847170754SdelphijThese adjustments can be applied to any output format. 1848170754Sdelphij 1849170754Sdelphij@menu 1850170754Sdelphij* Tabs:: Preserving the alignment of tab stops. 1851170754Sdelphij* Pagination:: Page numbering and time-stamping @command{diff} output. 1852170754Sdelphij@end menu 1853170754Sdelphij 1854170754Sdelphij@node Tabs 1855170754Sdelphij@section Preserving Tab Stop Alignment 1856170754Sdelphij@cindex tab stop alignment 1857170754Sdelphij@cindex aligning tab stops 1858170754Sdelphij 1859170754SdelphijThe lines of text in some of the @command{diff} output formats are 1860170754Sdelphijpreceded by one or two characters that indicate whether the text is 1861170754Sdelphijinserted, deleted, or changed. The addition of those characters can 1862170754Sdelphijcause tabs to move to the next tab stop, throwing off the alignment of 1863170754Sdelphijcolumns in the line. @acronym{GNU} @command{diff} provides two ways 1864170754Sdelphijto make tab-aligned columns line up correctly. 1865170754Sdelphij 1866170754SdelphijThe first way is to have @command{diff} convert all tabs into the correct 1867170754Sdelphijnumber of spaces before outputting them; select this method with the 1868170754Sdelphij@option{-t} or @option{--expand-tabs} option. To use this form of output with 1869170754Sdelphij@command{patch}, you must give @command{patch} the @option{-l} or 1870170754Sdelphij@option{--ignore-white-space} option (@pxref{Changed White Space}, for more 1871170754Sdelphijinformation). @command{diff} normally assumes that tab stops are set 1872170754Sdelphijevery 8 print columns, but this can be altered by the 1873170754Sdelphij@option{--tabsize=@var{columns}} option. 1874170754Sdelphij 1875170754SdelphijThe other method for making tabs line up correctly is to add a tab 1876170754Sdelphijcharacter instead of a space after the indicator character at the 1877170754Sdelphijbeginning of the line. This ensures that all following tab characters 1878170754Sdelphijare in the same position relative to tab stops that they were in the 1879170754Sdelphijoriginal files, so that the output is aligned correctly. Its 1880170754Sdelphijdisadvantage is that it can make long lines too long to fit on one line 1881170754Sdelphijof the screen or the paper. It also does not work with the unified 1882170754Sdelphijoutput format, which does not have a space character after the change 1883170754Sdelphijtype indicator character. Select this method with the @option{-T} or 1884170754Sdelphij@option{--initial-tab} option. 1885170754Sdelphij 1886170754Sdelphij@node Pagination 1887170754Sdelphij@section Paginating @command{diff} Output 1888170754Sdelphij@cindex paginating @command{diff} output 1889170754Sdelphij 1890170754SdelphijIt can be convenient to have long output page-numbered and time-stamped. 1891170754SdelphijThe @option{-l} or @option{--paginate} option does this by sending the 1892170754Sdelphij@command{diff} output through the @command{pr} program. Here is what the page 1893170754Sdelphijheader might look like for @samp{diff -lc lao tzu}: 1894170754Sdelphij 1895170754Sdelphij@example 1896170754Sdelphij2002-02-22 14:20 diff -lc lao tzu Page 1 1897170754Sdelphij@end example 1898170754Sdelphij 1899170754Sdelphij@node diff Performance 1900170754Sdelphij@chapter @command{diff} Performance Tradeoffs 1901170754Sdelphij@cindex performance of @command{diff} 1902170754Sdelphij 1903170754Sdelphij@acronym{GNU} @command{diff} runs quite efficiently; however, in some 1904170754Sdelphijcircumstances you can cause it to run faster or produce a more compact 1905170754Sdelphijset of changes. 1906170754Sdelphij 1907170754SdelphijOne way to improve @command{diff} performance is to use hard or 1908170754Sdelphijsymbolic links to files instead of copies. This improves performance 1909170754Sdelphijbecause @command{diff} normally does not need to read two hard or 1910170754Sdelphijsymbolic links to the same file, since their contents must be 1911170754Sdelphijidentical. For example, suppose you copy a large directory hierarchy, 1912170754Sdelphijmake a few changes to the copy, and then often use @samp{diff -r} to 1913170754Sdelphijcompare the original to the copy. If the original files are 1914170754Sdelphijread-only, you can greatly improve performance by creating the copy 1915170754Sdelphijusing hard or symbolic links (e.g., with @acronym{GNU} @samp{cp -lR} or 1916170754Sdelphij@samp{cp -sR}). Before editing a file in the copy for the first time, 1917170754Sdelphijyou should break the link and replace it with a regular copy. 1918170754Sdelphij 1919170754SdelphijYou can also affect the performance of @acronym{GNU} @command{diff} by 1920170754Sdelphijgiving it options that change the way it compares files. 1921170754SdelphijPerformance has more than one dimension. These options improve one 1922170754Sdelphijaspect of performance at the cost of another, or they improve 1923170754Sdelphijperformance in some cases while hurting it in others. 1924170754Sdelphij 1925170754SdelphijThe way that @acronym{GNU} @command{diff} determines which lines have 1926170754Sdelphijchanged always comes up with a near-minimal set of differences. 1927170754SdelphijUsually it is good enough for practical purposes. If the 1928170754Sdelphij@command{diff} output is large, you might want @command{diff} to use a 1929170754Sdelphijmodified algorithm that sometimes produces a smaller set of 1930170754Sdelphijdifferences. The @option{-d} or @option{--minimal} option does this; 1931170754Sdelphijhowever, it can also cause @command{diff} to run more slowly than 1932170754Sdelphijusual, so it is not the default behavior. 1933170754Sdelphij 1934170754SdelphijWhen the files you are comparing are large and have small groups of 1935170754Sdelphijchanges scattered throughout them, you can use the 1936170754Sdelphij@option{--speed-large-files} option to make a different modification to 1937170754Sdelphijthe algorithm that @command{diff} uses. If the input files have a constant 1938170754Sdelphijsmall density of changes, this option speeds up the comparisons without 1939170754Sdelphijchanging the output. If not, @command{diff} might produce a larger set of 1940170754Sdelphijdifferences; however, the output will still be correct. 1941170754Sdelphij 1942170754SdelphijNormally @command{diff} discards the prefix and suffix that is common to 1943170754Sdelphijboth files before it attempts to find a minimal set of differences. 1944170754SdelphijThis makes @command{diff} run faster, but occasionally it may produce 1945170754Sdelphijnon-minimal output. The @option{--horizon-lines=@var{lines}} option 1946170754Sdelphijprevents @command{diff} from discarding the last @var{lines} lines of the 1947170754Sdelphijprefix and the first @var{lines} lines of the suffix. This gives 1948170754Sdelphij@command{diff} further opportunities to find a minimal output. 1949170754Sdelphij 1950170754SdelphijSuppose a run of changed lines includes a sequence of lines at one end 1951170754Sdelphijand there is an identical sequence of lines just outside the other end. 1952170754SdelphijThe @command{diff} command is free to choose which identical sequence is 1953170754Sdelphijincluded in the hunk. In this case, @command{diff} normally shifts the 1954170754Sdelphijhunk's boundaries when this merges adjacent hunks, or shifts a hunk's 1955170754Sdelphijlines towards the end of the file. Merging hunks can make the output 1956170754Sdelphijlook nicer in some cases. 1957170754Sdelphij 1958170754Sdelphij@node Comparing Three Files 1959170754Sdelphij@chapter Comparing Three Files 1960170754Sdelphij@cindex comparing three files 1961170754Sdelphij@cindex format of @command{diff3} output 1962170754Sdelphij 1963170754SdelphijUse the program @command{diff3} to compare three files and show any 1964170754Sdelphijdifferences among them. (@command{diff3} can also merge files; see 1965170754Sdelphij@ref{diff3 Merging}). 1966170754Sdelphij 1967170754SdelphijThe ``normal'' @command{diff3} output format shows each hunk of 1968170754Sdelphijdifferences without surrounding context. Hunks are labeled depending 1969170754Sdelphijon whether they are two-way or three-way, and lines are annotated by 1970170754Sdelphijtheir location in the input files. 1971170754Sdelphij 1972170754Sdelphij@xref{Invoking diff3}, for more information on how to run @command{diff3}. 1973170754Sdelphij 1974170754Sdelphij@menu 1975170754Sdelphij* Sample diff3 Input:: Sample @command{diff3} input for examples. 1976170754Sdelphij* Example diff3 Normal:: Sample output in the normal format. 1977170754Sdelphij* diff3 Hunks:: The format of normal output format. 1978170754Sdelphij* Detailed diff3 Normal:: A detailed description of normal output format. 1979170754Sdelphij@end menu 1980170754Sdelphij 1981170754Sdelphij@node Sample diff3 Input 1982170754Sdelphij@section A Third Sample Input File 1983170754Sdelphij@cindex @command{diff3} sample input 1984170754Sdelphij@cindex sample input for @command{diff3} 1985170754Sdelphij 1986170754SdelphijHere is a third sample file that will be used in examples to illustrate 1987170754Sdelphijthe output of @command{diff3} and how various options can change it. The 1988170754Sdelphijfirst two files are the same that we used for @command{diff} (@pxref{Sample 1989170754Sdelphijdiff Input}). This is the third sample file, called @file{tao}: 1990170754Sdelphij 1991170754Sdelphij@example 1992170754SdelphijThe Way that can be told of is not the eternal Way; 1993170754SdelphijThe name that can be named is not the eternal name. 1994170754SdelphijThe Nameless is the origin of Heaven and Earth; 1995170754SdelphijThe named is the mother of all things. 1996170754Sdelphij 1997170754SdelphijTherefore let there always be non-being, 1998170754Sdelphij so we may see their subtlety, 1999170754SdelphijAnd let there always be being, 2000170754Sdelphij so we may see their result. 2001170754SdelphijThe two are the same, 2002170754SdelphijBut after they are produced, 2003170754Sdelphij they have different names. 2004170754Sdelphij 2005170754Sdelphij -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2006170754Sdelphij@end example 2007170754Sdelphij 2008170754Sdelphij@node Example diff3 Normal 2009170754Sdelphij@section An Example of @command{diff3} Normal Format 2010170754Sdelphij 2011170754SdelphijHere is the output of the command @samp{diff3 lao tzu tao} 2012170754Sdelphij(@pxref{Sample diff3 Input}, for the complete contents of the files). 2013170754SdelphijNotice that it shows only the lines that are different among the three 2014170754Sdelphijfiles. 2015170754Sdelphij 2016170754Sdelphij@example 2017170754Sdelphij====2 2018170754Sdelphij1:1,2c 2019170754Sdelphij3:1,2c 2020170754Sdelphij The Way that can be told of is not the eternal Way; 2021170754Sdelphij The name that can be named is not the eternal name. 2022170754Sdelphij2:0a 2023170754Sdelphij====1 2024170754Sdelphij1:4c 2025170754Sdelphij The Named is the mother of all things. 2026170754Sdelphij2:2,3c 2027170754Sdelphij3:4,5c 2028170754Sdelphij The named is the mother of all things. 2029170754Sdelphij 2030170754Sdelphij====3 2031170754Sdelphij1:8c 2032170754Sdelphij2:7c 2033170754Sdelphij so we may see their outcome. 2034170754Sdelphij3:9c 2035170754Sdelphij so we may see their result. 2036170754Sdelphij==== 2037170754Sdelphij1:11a 2038170754Sdelphij2:11,13c 2039170754Sdelphij They both may be called deep and profound. 2040170754Sdelphij Deeper and more profound, 2041170754Sdelphij The door of all subtleties! 2042170754Sdelphij3:13,14c 2043170754Sdelphij 2044170754Sdelphij -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2045170754Sdelphij@end example 2046170754Sdelphij 2047170754Sdelphij@node Detailed diff3 Normal 2048170754Sdelphij@section Detailed Description of @command{diff3} Normal Format 2049170754Sdelphij 2050170754SdelphijEach hunk begins with a line marked @samp{====}. Three-way hunks have 2051170754Sdelphijplain @samp{====} lines, and two-way hunks have @samp{1}, @samp{2}, or 2052170754Sdelphij@samp{3} appended to specify which of the three input files differ in 2053170754Sdelphijthat hunk. The hunks contain copies of two or three sets of input 2054170754Sdelphijlines each preceded by one or two commands identifying where the lines 2055170754Sdelphijcame from. 2056170754Sdelphij 2057170754SdelphijNormally, two spaces precede each copy of an input line to distinguish 2058170754Sdelphijit from the commands. But with the @option{-T} or @option{--initial-tab} 2059170754Sdelphijoption, @command{diff3} uses a tab instead of two spaces; this lines up 2060170754Sdelphijtabs correctly. @xref{Tabs}, for more information. 2061170754Sdelphij 2062170754SdelphijCommands take the following forms: 2063170754Sdelphij 2064170754Sdelphij@table @samp 2065170754Sdelphij@item @var{file}:@var{l}a 2066170754SdelphijThis hunk appears after line @var{l} of file @var{file}, and 2067170754Sdelphijcontains no lines in that file. To edit this file to yield the other 2068170754Sdelphijfiles, one must append hunk lines taken from the other files. For 2069170754Sdelphijexample, @samp{1:11a} means that the hunk follows line 11 in the first 2070170754Sdelphijfile and contains no lines from that file. 2071170754Sdelphij 2072170754Sdelphij@item @var{file}:@var{r}c 2073170754SdelphijThis hunk contains the lines in the range @var{r} of file @var{file}. 2074170754SdelphijThe range @var{r} is a comma-separated pair of line numbers, or just one 2075170754Sdelphijnumber if the range is a singleton. To edit this file to yield the 2076170754Sdelphijother files, one must change the specified lines to be the lines taken 2077170754Sdelphijfrom the other files. For example, @samp{2:11,13c} means that the hunk 2078170754Sdelphijcontains lines 11 through 13 from the second file. 2079170754Sdelphij@end table 2080170754Sdelphij 2081170754SdelphijIf the last line in a set of input lines is incomplete 2082170754Sdelphij(@pxref{Incomplete Lines}), it is distinguished on output from a full 2083170754Sdelphijline by a following line that starts with @samp{\}. 2084170754Sdelphij 2085170754Sdelphij@node diff3 Hunks 2086170754Sdelphij@section @command{diff3} Hunks 2087170754Sdelphij@cindex hunks for @command{diff3} 2088170754Sdelphij@cindex @command{diff3} hunks 2089170754Sdelphij 2090170754SdelphijGroups of lines that differ in two or three of the input files are 2091170754Sdelphijcalled @dfn{diff3 hunks}, by analogy with @command{diff} hunks 2092170754Sdelphij(@pxref{Hunks}). If all three input files differ in a @command{diff3} 2093170754Sdelphijhunk, the hunk is called a @dfn{three-way hunk}; if just two input files 2094170754Sdelphijdiffer, it is a @dfn{two-way hunk}. 2095170754Sdelphij 2096170754SdelphijAs with @command{diff}, several solutions are possible. When comparing the 2097170754Sdelphijfiles @samp{A}, @samp{B}, and @samp{C}, @command{diff3} normally finds 2098170754Sdelphij@command{diff3} hunks by merging the two-way hunks output by the two 2099170754Sdelphijcommands @samp{diff A B} and @samp{diff A C}. This does not necessarily 2100170754Sdelphijminimize the size of the output, but exceptions should be rare. 2101170754Sdelphij 2102170754SdelphijFor example, suppose @file{F} contains the three lines @samp{a}, 2103170754Sdelphij@samp{b}, @samp{f}, @file{G} contains the lines @samp{g}, @samp{b}, 2104170754Sdelphij@samp{g}, and @file{H} contains the lines @samp{a}, @samp{b}, 2105170754Sdelphij@samp{h}. @samp{diff3 F G H} might output the following: 2106170754Sdelphij 2107170754Sdelphij@example 2108170754Sdelphij====2 2109170754Sdelphij1:1c 2110170754Sdelphij3:1c 2111170754Sdelphij a 2112170754Sdelphij2:1c 2113170754Sdelphij g 2114170754Sdelphij==== 2115170754Sdelphij1:3c 2116170754Sdelphij f 2117170754Sdelphij2:3c 2118170754Sdelphij g 2119170754Sdelphij3:3c 2120170754Sdelphij h 2121170754Sdelphij@end example 2122170754Sdelphij 2123170754Sdelphij@noindent 2124170754Sdelphijbecause it found a two-way hunk containing @samp{a} in the first and 2125170754Sdelphijthird files and @samp{g} in the second file, then the single line 2126170754Sdelphij@samp{b} common to all three files, then a three-way hunk containing 2127170754Sdelphijthe last line of each file. 2128170754Sdelphij 2129170754Sdelphij@node diff3 Merging 2130170754Sdelphij@chapter Merging From a Common Ancestor 2131170754Sdelphij@cindex merging from a common ancestor 2132170754Sdelphij 2133170754SdelphijWhen two people have made changes to copies of the same file, 2134170754Sdelphij@command{diff3} can produce a merged output that contains both sets of 2135170754Sdelphijchanges together with warnings about conflicts. 2136170754Sdelphij 2137170754SdelphijOne might imagine programs with names like @command{diff4} and @command{diff5} 2138170754Sdelphijto compare more than three files simultaneously, but in practice the 2139170754Sdelphijneed rarely arises. You can use @command{diff3} to merge three or more 2140170754Sdelphijsets of changes to a file by merging two change sets at a time. 2141170754Sdelphij 2142170754Sdelphij@command{diff3} can incorporate changes from two modified versions into a 2143170754Sdelphijcommon preceding version. This lets you merge the sets of changes 2144170754Sdelphijrepresented by the two newer files. Specify the common ancestor version 2145170754Sdelphijas the second argument and the two newer versions as the first and third 2146170754Sdelphijarguments, like this: 2147170754Sdelphij 2148170754Sdelphij@example 2149170754Sdelphijdiff3 @var{mine} @var{older} @var{yours} 2150170754Sdelphij@end example 2151170754Sdelphij 2152170754Sdelphij@noindent 2153170754SdelphijYou can remember the order of the arguments by noting that they are in 2154170754Sdelphijalphabetical order. 2155170754Sdelphij 2156170754Sdelphij@cindex conflict 2157170754Sdelphij@cindex overlap 2158170754SdelphijYou can think of this as subtracting @var{older} from @var{yours} and 2159170754Sdelphijadding the result to @var{mine}, or as merging into @var{mine} the 2160170754Sdelphijchanges that would turn @var{older} into @var{yours}. This merging is 2161170754Sdelphijwell-defined as long as @var{mine} and @var{older} match in the 2162170754Sdelphijneighborhood of each such change. This fails to be true when all three 2163170754Sdelphijinput files differ or when only @var{older} differs; we call this 2164170754Sdelphija @dfn{conflict}. When all three input files differ, we call the 2165170754Sdelphijconflict an @dfn{overlap}. 2166170754Sdelphij 2167170754Sdelphij@command{diff3} gives you several ways to handle overlaps and conflicts. 2168170754SdelphijYou can omit overlaps or conflicts, or select only overlaps, 2169170754Sdelphijor mark conflicts with special @samp{<<<<<<<} and @samp{>>>>>>>} lines. 2170170754Sdelphij 2171170754Sdelphij@command{diff3} can output the merge results as an @command{ed} script that 2172170754Sdelphijthat can be applied to the first file to yield the merged output. 2173170754SdelphijHowever, it is usually better to have @command{diff3} generate the merged 2174170754Sdelphijoutput directly; this bypasses some problems with @command{ed}. 2175170754Sdelphij 2176170754Sdelphij@menu 2177170754Sdelphij* Which Changes:: Selecting changes to incorporate. 2178170754Sdelphij* Marking Conflicts:: Marking conflicts. 2179170754Sdelphij* Bypassing ed:: Generating merged output directly. 2180170754Sdelphij* Merging Incomplete Lines:: How @command{diff3} merges incomplete lines. 2181170754Sdelphij* Saving the Changed File:: Emulating System V behavior. 2182170754Sdelphij@end menu 2183170754Sdelphij 2184170754Sdelphij@node Which Changes 2185170754Sdelphij@section Selecting Which Changes to Incorporate 2186170754Sdelphij@cindex overlapping change, selection of 2187170754Sdelphij@cindex unmerged change 2188170754Sdelphij 2189170754SdelphijYou can select all unmerged changes from @var{older} to @var{yours} for merging 2190170754Sdelphijinto @var{mine} with the @option{-e} or @option{--ed} option. You can 2191170754Sdelphijselect only the nonoverlapping unmerged changes with @option{-3} or 2192170754Sdelphij@option{--easy-only}, and you can select only the overlapping changes with 2193170754Sdelphij@option{-x} or @option{--overlap-only}. 2194170754Sdelphij 2195170754SdelphijThe @option{-e}, @option{-3} and @option{-x} options select only 2196170754Sdelphij@dfn{unmerged changes}, i.e.@: changes where @var{mine} and @var{yours} 2197170754Sdelphijdiffer; they ignore changes from @var{older} to @var{yours} where 2198170754Sdelphij@var{mine} and @var{yours} are identical, because they assume that such 2199170754Sdelphijchanges have already been merged. If this assumption is not a safe 2200170754Sdelphijone, you can use the @option{-A} or @option{--show-all} option 2201170754Sdelphij(@pxref{Marking Conflicts}). 2202170754Sdelphij 2203170754SdelphijHere is the output of the command @command{diff3} with each of these three 2204170754Sdelphijoptions (@pxref{Sample diff3 Input}, for the complete contents of the files). 2205170754SdelphijNotice that @option{-e} outputs the union of the disjoint sets of changes 2206170754Sdelphijoutput by @option{-3} and @option{-x}. 2207170754Sdelphij 2208170754SdelphijOutput of @samp{diff3 -e lao tzu tao}: 2209170754Sdelphij@example 2210170754Sdelphij11a 2211170754Sdelphij 2212170754Sdelphij -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2213170754Sdelphij. 2214170754Sdelphij8c 2215170754Sdelphij so we may see their result. 2216170754Sdelphij. 2217170754Sdelphij@end example 2218170754Sdelphij 2219170754SdelphijOutput of @samp{diff3 -3 lao tzu tao}: 2220170754Sdelphij@example 2221170754Sdelphij8c 2222170754Sdelphij so we may see their result. 2223170754Sdelphij. 2224170754Sdelphij@end example 2225170754Sdelphij 2226170754SdelphijOutput of @samp{diff3 -x lao tzu tao}: 2227170754Sdelphij@example 2228170754Sdelphij11a 2229170754Sdelphij 2230170754Sdelphij -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2231170754Sdelphij. 2232170754Sdelphij@end example 2233170754Sdelphij 2234170754Sdelphij@node Marking Conflicts 2235170754Sdelphij@section Marking Conflicts 2236170754Sdelphij@cindex conflict marking 2237170754Sdelphij@cindex @samp{<<<<<<<} for marking conflicts 2238170754Sdelphij 2239170754Sdelphij@command{diff3} can mark conflicts in the merged output by 2240170754Sdelphijbracketing them with special marker lines. A conflict 2241170754Sdelphijthat comes from two files @var{A} and @var{B} is marked as follows: 2242170754Sdelphij 2243170754Sdelphij@example 2244170754Sdelphij<<<<<<< @var{A} 2245170754Sdelphij@r{lines from @var{A}} 2246170754Sdelphij======= 2247170754Sdelphij@r{lines from @var{B}} 2248170754Sdelphij>>>>>>> @var{B} 2249170754Sdelphij@end example 2250170754Sdelphij 2251170754SdelphijA conflict that comes from three files @var{A}, @var{B} and @var{C} is 2252170754Sdelphijmarked as follows: 2253170754Sdelphij 2254170754Sdelphij@example 2255170754Sdelphij<<<<<<< @var{A} 2256170754Sdelphij@r{lines from @var{A}} 2257170754Sdelphij||||||| @var{B} 2258170754Sdelphij@r{lines from @var{B}} 2259170754Sdelphij======= 2260170754Sdelphij@r{lines from @var{C}} 2261170754Sdelphij>>>>>>> @var{C} 2262170754Sdelphij@end example 2263170754Sdelphij 2264170754SdelphijThe @option{-A} or @option{--show-all} option acts like the @option{-e} 2265170754Sdelphijoption, except that it brackets conflicts, and it outputs all changes 2266170754Sdelphijfrom @var{older} to @var{yours}, not just the unmerged changes. Thus, 2267170754Sdelphijgiven the sample input files (@pxref{Sample diff3 Input}), @samp{diff3 2268170754Sdelphij-A lao tzu tao} puts brackets around the conflict where only @file{tzu} 2269170754Sdelphijdiffers: 2270170754Sdelphij 2271170754Sdelphij@example 2272170754Sdelphij<<<<<<< tzu 2273170754Sdelphij======= 2274170754SdelphijThe Way that can be told of is not the eternal Way; 2275170754SdelphijThe name that can be named is not the eternal name. 2276170754Sdelphij>>>>>>> tao 2277170754Sdelphij@end example 2278170754Sdelphij 2279170754SdelphijAnd it outputs the three-way conflict as follows: 2280170754Sdelphij 2281170754Sdelphij@example 2282170754Sdelphij<<<<<<< lao 2283170754Sdelphij||||||| tzu 2284170754SdelphijThey both may be called deep and profound. 2285170754SdelphijDeeper and more profound, 2286170754SdelphijThe door of all subtleties! 2287170754Sdelphij======= 2288170754Sdelphij 2289170754Sdelphij -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2290170754Sdelphij>>>>>>> tao 2291170754Sdelphij@end example 2292170754Sdelphij 2293170754SdelphijThe @option{-E} or @option{--show-overlap} option outputs less information 2294170754Sdelphijthan the @option{-A} or @option{--show-all} option, because it outputs only 2295170754Sdelphijunmerged changes, and it never outputs the contents of the second 2296170754Sdelphijfile. Thus the @option{-E} option acts like the @option{-e} option, 2297170754Sdelphijexcept that it brackets the first and third files from three-way 2298170754Sdelphijoverlapping changes. Similarly, @option{-X} acts like @option{-x}, except 2299170754Sdelphijit brackets all its (necessarily overlapping) changes. For example, 2300170754Sdelphijfor the three-way overlapping change above, the @option{-E} and @option{-X} 2301170754Sdelphijoptions output the following: 2302170754Sdelphij 2303170754Sdelphij@example 2304170754Sdelphij<<<<<<< lao 2305170754Sdelphij======= 2306170754Sdelphij 2307170754Sdelphij -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2308170754Sdelphij>>>>>>> tao 2309170754Sdelphij@end example 2310170754Sdelphij 2311170754SdelphijIf you are comparing files that have meaningless or uninformative names, 2312170754Sdelphijyou can use the @option{--label=@var{label}} 2313170754Sdelphijoption to show alternate names in the @samp{<<<<<<<}, @samp{|||||||} 2314170754Sdelphijand @samp{>>>>>>>} brackets. This option can be given up to three 2315170754Sdelphijtimes, once for each input file. Thus @samp{diff3 -A --label X 2316170754Sdelphij--label Y --label Z A 2317170754SdelphijB C} acts like @samp{diff3 -A A B C}, except that the output looks like 2318170754Sdelphijit came from files named @samp{X}, @samp{Y} and @samp{Z} rather than 2319170754Sdelphijfrom files named @samp{A}, @samp{B} and @samp{C}. 2320170754Sdelphij 2321170754Sdelphij@node Bypassing ed 2322170754Sdelphij@section Generating the Merged Output Directly 2323170754Sdelphij@cindex merged @command{diff3} format 2324170754Sdelphij 2325170754SdelphijWith the @option{-m} or @option{--merge} option, @command{diff3} outputs the 2326170754Sdelphijmerged file directly. This is more efficient than using @command{ed} to 2327170754Sdelphijgenerate it, and works even with non-text files that @command{ed} would 2328170754Sdelphijreject. If you specify @option{-m} without an @command{ed} script option, 2329170754Sdelphij@option{-A} is assumed. 2330170754Sdelphij 2331170754SdelphijFor example, the command @samp{diff3 -m lao tzu tao} 2332170754Sdelphij(@pxref{Sample diff3 Input} for a copy of the input files) would output 2333170754Sdelphijthe following: 2334170754Sdelphij 2335170754Sdelphij@example 2336170754Sdelphij<<<<<<< tzu 2337170754Sdelphij======= 2338170754SdelphijThe Way that can be told of is not the eternal Way; 2339170754SdelphijThe name that can be named is not the eternal name. 2340170754Sdelphij>>>>>>> tao 2341170754SdelphijThe Nameless is the origin of Heaven and Earth; 2342170754SdelphijThe Named is the mother of all things. 2343170754SdelphijTherefore let there always be non-being, 2344170754Sdelphij so we may see their subtlety, 2345170754SdelphijAnd let there always be being, 2346170754Sdelphij so we may see their result. 2347170754SdelphijThe two are the same, 2348170754SdelphijBut after they are produced, 2349170754Sdelphij they have different names. 2350170754Sdelphij<<<<<<< lao 2351170754Sdelphij||||||| tzu 2352170754SdelphijThey both may be called deep and profound. 2353170754SdelphijDeeper and more profound, 2354170754SdelphijThe door of all subtleties! 2355170754Sdelphij======= 2356170754Sdelphij 2357170754Sdelphij -- The Way of Lao-Tzu, tr. Wing-tsit Chan 2358170754Sdelphij>>>>>>> tao 2359170754Sdelphij@end example 2360170754Sdelphij 2361170754Sdelphij@node Merging Incomplete Lines 2362170754Sdelphij@section How @command{diff3} Merges Incomplete Lines 2363170754Sdelphij@cindex incomplete line merging 2364170754Sdelphij 2365170754SdelphijWith @option{-m}, incomplete lines (@pxref{Incomplete Lines}) are simply 2366170754Sdelphijcopied to the output as they are found; if the merged output ends in an 2367170754Sdelphijconflict and one of the input files ends in an incomplete 2368170754Sdelphijline, succeeding @samp{|||||||}, @samp{=======} or @samp{>>>>>>>} 2369170754Sdelphijbrackets appear somewhere other than the start of a line because 2370170754Sdelphijthey are appended to the incomplete line. 2371170754Sdelphij 2372170754SdelphijWithout @option{-m}, if an @command{ed} script option is specified and an 2373170754Sdelphijincomplete line is found, @command{diff3} generates a warning and acts as 2374170754Sdelphijif a newline had been present. 2375170754Sdelphij 2376170754Sdelphij@node Saving the Changed File 2377170754Sdelphij@section Saving the Changed File 2378170754Sdelphij@cindex System V @command{diff3} compatibility 2379170754Sdelphij 2380170754SdelphijTraditional Unix @command{diff3} generates an @command{ed} script without the 2381170754Sdelphijtrailing @samp{w} and @samp{q} commands that save the changes. 2382170754SdelphijSystem V @command{diff3} generates these extra commands. @acronym{GNU} 2383170754Sdelphij@command{diff3} normally behaves like traditional Unix 2384170754Sdelphij@command{diff3}, but with the @option{-i} option it behaves like 2385170754SdelphijSystem V @command{diff3} and appends the @samp{w} and @samp{q} 2386170754Sdelphijcommands. 2387170754Sdelphij 2388170754SdelphijThe @option{-i} option requires one of the @command{ed} script options 2389170754Sdelphij@option{-AeExX3}, and is incompatible with the merged output option 2390170754Sdelphij@option{-m}. 2391170754Sdelphij 2392170754Sdelphij@node Interactive Merging 2393170754Sdelphij@chapter Interactive Merging with @command{sdiff} 2394170754Sdelphij@cindex diff merging 2395170754Sdelphij@cindex interactive merging 2396170754Sdelphij 2397170754SdelphijWith @command{sdiff}, you can merge two files interactively based on a 2398170754Sdelphijside-by-side @option{-y} format comparison (@pxref{Side by Side}). Use 2399170754Sdelphij@option{-o @var{file}} or @option{--output=@var{file}} to specify where to 2400170754Sdelphijput the merged text. @xref{Invoking sdiff}, for more details on the 2401170754Sdelphijoptions to @command{sdiff}. 2402170754Sdelphij 2403170754SdelphijAnother way to merge files interactively is to use the Emacs Lisp 2404170754Sdelphijpackage @command{emerge}. @xref{emerge, , emerge, emacs, The 2405170754Sdelphij@acronym{GNU} Emacs Manual}, for more information. 2406170754Sdelphij 2407170754Sdelphij@menu 2408170754Sdelphij* sdiff Option Summary:: Summary of @command{sdiff} options. 2409170754Sdelphij* Merge Commands:: Merging two files interactively. 2410170754Sdelphij@end menu 2411170754Sdelphij 2412170754Sdelphij@node sdiff Option Summary 2413170754Sdelphij@section Specifying @command{diff} Options to @command{sdiff} 2414170754Sdelphij@cindex @command{sdiff} output format 2415170754Sdelphij 2416170754SdelphijThe following @command{sdiff} options have the same meaning as for 2417170754Sdelphij@command{diff}. @xref{diff Options}, for the use of these options. 2418170754Sdelphij 2419170754Sdelphij@example 2420170754Sdelphij-a -b -d -i -t -v 2421170754Sdelphij-B -E -I @var{regexp} 2422170754Sdelphij 2423170754Sdelphij--expand-tabs 2424170754Sdelphij--ignore-blank-lines --ignore-case 2425170754Sdelphij--ignore-matching-lines=@var{regexp} --ignore-space-change 2426170754Sdelphij--ignore-tab-expansion 2427170754Sdelphij--left-column --minimal --speed-large-files 2428170754Sdelphij--strip-trailing-cr --suppress-common-lines 2429170754Sdelphij--tabsize=@var{columns} --text --version --width=@var{columns} 2430170754Sdelphij@end example 2431170754Sdelphij 2432170754SdelphijFor historical reasons, @command{sdiff} has alternate names for some 2433170754Sdelphijoptions. The @option{-l} option is equivalent to the 2434170754Sdelphij@option{--left-column} option, and similarly @option{-s} is equivalent 2435170754Sdelphijto @option{--suppress-common-lines}. The meaning of the @command{sdiff} 2436170754Sdelphij@option{-w} and @option{-W} options is interchanged from that of 2437170754Sdelphij@command{diff}: with @command{sdiff}, @option{-w @var{columns}} is 2438170754Sdelphijequivalent to @option{--width=@var{columns}}, and @option{-W} is 2439170754Sdelphijequivalent to @option{--ignore-all-space}. @command{sdiff} without the 2440170754Sdelphij@option{-o} option is equivalent to @command{diff} with the @option{-y} 2441170754Sdelphijor @option{--side-by-side} option (@pxref{Side by Side}). 2442170754Sdelphij 2443170754Sdelphij@node Merge Commands 2444170754Sdelphij@section Merge Commands 2445170754Sdelphij@cindex merge commands 2446170754Sdelphij@cindex merging interactively 2447170754Sdelphij 2448170754SdelphijGroups of common lines, with a blank gutter, are copied from the first 2449170754Sdelphijfile to the output. After each group of differing lines, @command{sdiff} 2450170754Sdelphijprompts with @samp{%} and pauses, waiting for one of the following 2451170754Sdelphijcommands. Follow each command with @key{RET}. 2452170754Sdelphij 2453170754Sdelphij@table @samp 2454170754Sdelphij@item e 2455170754SdelphijDiscard both versions. 2456170754SdelphijInvoke a text editor on an empty temporary file, 2457170754Sdelphijthen copy the resulting file to the output. 2458170754Sdelphij 2459170754Sdelphij@item eb 2460170754SdelphijConcatenate the two versions, edit the result in a temporary file, 2461170754Sdelphijthen copy the edited result to the output. 2462170754Sdelphij 2463170754Sdelphij@item ed 2464170754SdelphijLike @samp{eb}, except precede each version with a header that 2465170754Sdelphijshows what file and lines the version came from. 2466170754Sdelphij 2467170754Sdelphij@item el 2468170754SdelphijEdit a copy of the left version, then copy the result to the output. 2469170754Sdelphij 2470170754Sdelphij@item er 2471170754SdelphijEdit a copy of the right version, then copy the result to the output. 2472170754Sdelphij 2473170754Sdelphij@item l 2474170754SdelphijCopy the left version to the output. 2475170754Sdelphij 2476170754Sdelphij@item q 2477170754SdelphijQuit. 2478170754Sdelphij 2479170754Sdelphij@item r 2480170754SdelphijCopy the right version to the output. 2481170754Sdelphij 2482170754Sdelphij@item s 2483170754SdelphijSilently copy common lines. 2484170754Sdelphij 2485170754Sdelphij@item v 2486170754SdelphijVerbosely copy common lines. This is the default. 2487170754Sdelphij@end table 2488170754Sdelphij 2489170754Sdelphij@vindex EDITOR 2490170754SdelphijThe text editor invoked is specified by the @env{EDITOR} environment 2491170754Sdelphijvariable if it is set. The default is system-dependent. 2492170754Sdelphij 2493170754Sdelphij@node Merging with patch 2494170754Sdelphij@chapter Merging with @command{patch} 2495170754Sdelphij 2496170754Sdelphij@command{patch} takes comparison output produced by @command{diff} and applies 2497170754Sdelphijthe differences to a copy of the original file, producing a patched 2498170754Sdelphijversion. With @command{patch}, you can distribute just the changes to a 2499170754Sdelphijset of files instead of distributing the entire file set; your 2500170754Sdelphijcorrespondents can apply @command{patch} to update their copy of the files 2501170754Sdelphijwith your changes. @command{patch} automatically determines the diff 2502170754Sdelphijformat, skips any leading or trailing headers, and uses the headers to 2503170754Sdelphijdetermine which file to patch. This lets your correspondents feed a 2504170754Sdelphijmail message containing a difference listing directly to 2505170754Sdelphij@command{patch}. 2506170754Sdelphij 2507170754Sdelphij@command{patch} detects and warns about common problems like forward 2508170754Sdelphijpatches. It saves any patches that it could not apply. It can also maintain a 2509170754Sdelphij@code{patchlevel.h} file to ensure that your correspondents apply 2510170754Sdelphijdiffs in the proper order. 2511170754Sdelphij 2512170754Sdelphij@command{patch} accepts a series of diffs in its standard input, usually 2513170754Sdelphijseparated by headers that specify which file to patch. It applies 2514170754Sdelphij@command{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not 2515170754Sdelphijexactly match the original file, @command{patch} uses heuristics to try to 2516170754Sdelphijpatch the file as well as it can. If no approximate match can be found, 2517170754Sdelphij@command{patch} rejects the hunk and skips to the next hunk. @command{patch} 2518170754Sdelphijnormally replaces each file @var{f} with its new version, putting reject 2519170754Sdelphijhunks (if any) into @samp{@var{f}.rej}. 2520170754Sdelphij 2521170754Sdelphij@xref{Invoking patch}, for detailed information on the options to 2522170754Sdelphij@command{patch}. 2523170754Sdelphij 2524170754Sdelphij@menu 2525170754Sdelphij* patch Input:: Selecting the type of @command{patch} input. 2526170754Sdelphij* Revision Control:: Getting files from @acronym{RCS}, @acronym{SCCS}, etc. 2527170754Sdelphij* Imperfect:: Dealing with imperfect patches. 2528170754Sdelphij* Creating and Removing:: Creating and removing files with a patch. 2529170754Sdelphij* Patching Time Stamps:: Updating time stamps on patched files. 2530170754Sdelphij* Multiple Patches:: Handling multiple patches in a file. 2531170754Sdelphij* patch Directories:: Changing directory and stripping directories. 2532170754Sdelphij* Backups:: Whether backup files are made. 2533170754Sdelphij* Backup Names:: Backup file names. 2534170754Sdelphij* Reject Names:: Reject file names. 2535170754Sdelphij* patch Messages:: Messages and questions @command{patch} can produce. 2536170754Sdelphij* patch and POSIX:: Conformance to the @acronym{POSIX} standard. 2537170754Sdelphij* patch and Tradition:: @acronym{GNU} versus traditional @command{patch}. 2538170754Sdelphij@end menu 2539170754Sdelphij 2540170754Sdelphij@node patch Input 2541170754Sdelphij@section Selecting the @command{patch} Input Format 2542170754Sdelphij@cindex @command{patch} input format 2543170754Sdelphij 2544170754Sdelphij@command{patch} normally determines which @command{diff} format the patch 2545170754Sdelphijfile uses by examining its contents. For patch files that contain 2546170754Sdelphijparticularly confusing leading text, you might need to use one of the 2547170754Sdelphijfollowing options to force @command{patch} to interpret the patch file as a 2548170754Sdelphijcertain format of diff. The output formats listed here are the only 2549170754Sdelphijones that @command{patch} can understand. 2550170754Sdelphij 2551170754Sdelphij@table @option 2552170754Sdelphij@item -c 2553170754Sdelphij@itemx --context 2554170754Sdelphijcontext diff. 2555170754Sdelphij 2556170754Sdelphij@item -e 2557170754Sdelphij@itemx --ed 2558170754Sdelphij@command{ed} script. 2559170754Sdelphij 2560170754Sdelphij@item -n 2561170754Sdelphij@itemx --normal 2562170754Sdelphijnormal diff. 2563170754Sdelphij 2564170754Sdelphij@item -u 2565170754Sdelphij@itemx --unified 2566170754Sdelphijunified diff. 2567170754Sdelphij@end table 2568170754Sdelphij 2569170754Sdelphij@node Revision Control 2570170754Sdelphij@section Revision Control 2571170754Sdelphij@cindex revision control 2572170754Sdelphij@cindex version control 2573170754Sdelphij@cindex @acronym{RCS} 2574170754Sdelphij@cindex ClearCase 2575170754Sdelphij@cindex @acronym{SCCS} 2576170754Sdelphij 2577170754SdelphijIf a nonexistent input file is under a revision control system 2578170754Sdelphijsupported by @command{patch}, @command{patch} normally asks the user 2579170754Sdelphijwhether to get (or check out) the file from the revision control 2580170754Sdelphijsystem. Patch currently supports @acronym{RCS}, ClearCase and 2581170754Sdelphij@acronym{SCCS}. Under @acronym{RCS} and @acronym{SCCS}, 2582170754Sdelphij@command{patch} also asks when the input file is read-only and matches 2583170754Sdelphijthe default version in the revision control system. 2584170754Sdelphij 2585170754Sdelphij@vindex PATCH_GET 2586170754SdelphijThe @option{-g @var{num}} or @option{--get=@var{num}} option affects access 2587170754Sdelphijto files under supported revision control systems. If @var{num} is 2588170754Sdelphijpositive, @command{patch} gets the file without asking the user; if 2589170754Sdelphijzero, @command{patch} neither asks the user nor gets the file; and if 2590170754Sdelphijnegative, @command{patch} asks the user before getting the file. The 2591170754Sdelphijdefault value of @var{num} is given by the value of the 2592170754Sdelphij@env{PATCH_GET} environment variable if it is set; if not, the default 2593170754Sdelphijvalue is zero if @command{patch} is conforming to @acronym{POSIX}, negative 2594170754Sdelphijotherwise. @xref{patch and POSIX}. 2595170754Sdelphij 2596170754Sdelphij@vindex VERSION_CONTROL 2597170754SdelphijThe choice of revision control system is unaffected by the 2598170754Sdelphij@env{VERSION_CONTROL} environment variable (@pxref{Backup Names}). 2599170754Sdelphij 2600170754Sdelphij@node Imperfect 2601170754Sdelphij@section Applying Imperfect Patches 2602170754Sdelphij@cindex imperfect patch application 2603170754Sdelphij 2604170754Sdelphij@command{patch} tries to skip any leading text in the patch file, 2605170754Sdelphijapply the diff, and then skip any trailing text. Thus you can feed a 2606170754Sdelphijmail message directly to @command{patch}, and it should work. If the 2607170754Sdelphijentire diff is indented by a constant amount of white space, 2608170754Sdelphij@command{patch} automatically ignores the indentation. If a context 2609170754Sdelphijdiff contains trailing carriage return on each line, @command{patch} 2610170754Sdelphijautomatically ignores the carriage return. If a context diff has been 2611170754Sdelphijencapsulated by prepending @w{@samp{- }} to lines beginning with @samp{-} 2612170754Sdelphijas per @uref{ftp://ftp.isi.edu/in-notes/rfc934.txt, Internet RFC 934}, 2613170754Sdelphij@command{patch} automatically unencapsulates the input. 2614170754Sdelphij 2615170754SdelphijHowever, certain other types of imperfect input require user 2616170754Sdelphijintervention or testing. 2617170754Sdelphij 2618170754Sdelphij@menu 2619170754Sdelphij* Changed White Space:: When tabs and spaces don't match exactly. 2620170754Sdelphij* Reversed Patches:: Applying reversed patches correctly. 2621170754Sdelphij* Inexact:: Helping @command{patch} find close matches. 2622170754Sdelphij* Dry Runs:: Predicting what @command{patch} will do. 2623170754Sdelphij@end menu 2624170754Sdelphij 2625170754Sdelphij@node Changed White Space 2626170754Sdelphij@subsection Applying Patches with Changed White Space 2627170754Sdelphij@cindex white space in patches 2628170754Sdelphij 2629170754SdelphijSometimes mailers, editors, or other programs change spaces into tabs, 2630170754Sdelphijor vice versa. If this happens to a patch file or an input file, the 2631170754Sdelphijfiles might look the same, but @command{patch} will not be able to match 2632170754Sdelphijthem properly. If this problem occurs, use the @option{-l} or 2633170754Sdelphij@option{--ignore-white-space} option, which makes @command{patch} compare 2634170754Sdelphijblank characters (i.e.@: spaces and tabs) loosely so that any nonempty 2635170754Sdelphijsequence of blanks in the patch file matches any nonempty sequence of 2636170754Sdelphijblanks in the input files. Non-blank 2637170754Sdelphijcharacters must still match exactly. Each line of the context must 2638170754Sdelphijstill match a line in the input file. 2639170754Sdelphij 2640170754Sdelphij@node Reversed Patches 2641170754Sdelphij@subsection Applying Reversed Patches 2642170754Sdelphij@cindex reversed patches 2643170754Sdelphij 2644170754SdelphijSometimes people run @command{diff} with the new file first instead of 2645170754Sdelphijsecond. This creates a diff that is ``reversed''. To apply such 2646170754Sdelphijpatches, give @command{patch} the @option{-R} or @option{--reverse} option. 2647170754Sdelphij@command{patch} then attempts to swap each hunk around before applying it. 2648170754SdelphijRejects come out in the swapped format. 2649170754Sdelphij 2650170754SdelphijOften @command{patch} can guess that the patch is reversed. If the first 2651170754Sdelphijhunk of a patch fails, @command{patch} reverses the hunk to see if it can 2652170754Sdelphijapply it that way. If it can, @command{patch} asks you if you want to have 2653170754Sdelphijthe @option{-R} option set; if it can't, @command{patch} continues to apply 2654170754Sdelphijthe patch normally. This method cannot detect a reversed patch if it is 2655170754Sdelphija normal diff and the first command is an append (which should have been 2656170754Sdelphija delete) since appends always succeed, because a null context matches 2657170754Sdelphijanywhere. But most patches add or change lines rather than delete them, 2658170754Sdelphijso most reversed normal diffs begin with a delete, which fails, and 2659170754Sdelphij@command{patch} notices. 2660170754Sdelphij 2661170754SdelphijIf you apply a patch that you have already applied, @command{patch} thinks 2662170754Sdelphijit is a reversed patch and offers to un-apply the patch. This could be 2663170754Sdelphijconstrued as a feature. If you did this inadvertently and you don't 2664170754Sdelphijwant to un-apply the patch, just answer @samp{n} to this offer and to 2665170754Sdelphijthe subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the 2666170754Sdelphij@command{patch} process. 2667170754Sdelphij 2668170754Sdelphij@node Inexact 2669170754Sdelphij@subsection Helping @command{patch} Find Inexact Matches 2670170754Sdelphij@cindex inexact patches 2671170754Sdelphij@cindex fuzz factor when patching 2672170754Sdelphij 2673170754SdelphijFor context diffs, and to a lesser extent normal diffs, @command{patch} can 2674170754Sdelphijdetect when the line numbers mentioned in the patch are incorrect, and 2675170754Sdelphijit attempts to find the correct place to apply each hunk of the patch. 2676170754SdelphijAs a first guess, it takes the line number mentioned in the hunk, plus 2677170754Sdelphijor minus any offset used in applying the previous hunk. If that is not 2678170754Sdelphijthe correct place, @command{patch} scans both forward and backward for a 2679170754Sdelphijset of lines matching the context given in the hunk. 2680170754Sdelphij 2681170754SdelphijFirst @command{patch} looks for a place where all lines of the context 2682170754Sdelphijmatch. If it cannot find such a place, and it is reading a context or 2683170754Sdelphijunified diff, and the maximum fuzz factor is set to 1 or more, then 2684170754Sdelphij@command{patch} makes another scan, ignoring the first and last line of 2685170754Sdelphijcontext. If that fails, and the maximum fuzz factor is set to 2 or 2686170754Sdelphijmore, it makes another scan, ignoring the first two and last two lines 2687170754Sdelphijof context are ignored. It continues similarly if the maximum fuzz 2688170754Sdelphijfactor is larger. 2689170754Sdelphij 2690170754SdelphijThe @option{-F @var{lines}} or @option{--fuzz=@var{lines}} option sets the 2691170754Sdelphijmaximum fuzz factor to @var{lines}. This option only applies to context 2692170754Sdelphijand unified diffs; it ignores up to @var{lines} lines while looking for 2693170754Sdelphijthe place to install a hunk. Note that a larger fuzz factor increases 2694170754Sdelphijthe odds of making a faulty patch. The default fuzz factor is 2; there 2695170754Sdelphijis no point to setting it to more than the number of lines of context 2696170754Sdelphijin the diff, ordinarily 3. 2697170754Sdelphij 2698170754SdelphijIf @command{patch} cannot find a place to install a hunk of the patch, it 2699170754Sdelphijwrites the hunk out to a reject file (@pxref{Reject Names}, for information 2700170754Sdelphijon how reject files are named). It writes out rejected hunks in context 2701170754Sdelphijformat no matter what form the input patch is in. If the input is a 2702170754Sdelphijnormal or @command{ed} diff, many of the contexts are simply null. The 2703170754Sdelphijline numbers on the hunks in the reject file may be different from those 2704170754Sdelphijin the patch file: they show the approximate location where @command{patch} 2705170754Sdelphijthinks the failed hunks belong in the new file rather than in the old 2706170754Sdelphijone. 2707170754Sdelphij 2708170754SdelphijIf the @option{--verbose} option is given, then 2709170754Sdelphijas it completes each hunk @command{patch} tells you whether the hunk 2710170754Sdelphijsucceeded or failed, and if it failed, on which line (in the new file) 2711170754Sdelphij@command{patch} thinks the hunk should go. If this is different from the 2712170754Sdelphijline number specified in the diff, it tells you the offset. A single 2713170754Sdelphijlarge offset @emph{may} indicate that @command{patch} installed a hunk in 2714170754Sdelphijthe wrong place. @command{patch} also tells you if it used a fuzz factor 2715170754Sdelphijto make the match, in which case you should also be slightly suspicious. 2716170754Sdelphij 2717170754Sdelphij@command{patch} cannot tell if the line numbers are off in an @command{ed} 2718170754Sdelphijscript, and can only detect wrong line numbers in a normal diff when it 2719170754Sdelphijfinds a change or delete command. It may have the same problem with a 2720170754Sdelphijcontext diff using a fuzz factor equal to or greater than the number of 2721170754Sdelphijlines of context shown in the diff (typically 3). In these cases, you 2722170754Sdelphijshould probably look at a context diff between your original and patched 2723170754Sdelphijinput files to see if the changes make sense. Compiling without errors 2724170754Sdelphijis a pretty good indication that the patch worked, but not a guarantee. 2725170754Sdelphij 2726170754SdelphijA patch against an empty file applies to a nonexistent file, and vice 2727170754Sdelphijversa. @xref{Creating and Removing}. 2728170754Sdelphij 2729170754Sdelphij@command{patch} usually produces the correct results, even when it must 2730170754Sdelphijmake many guesses. However, the results are guaranteed only when 2731170754Sdelphijthe patch is applied to an exact copy of the file that the patch was 2732170754Sdelphijgenerated from. 2733170754Sdelphij 2734170754Sdelphij@node Dry Runs 2735170754Sdelphij@subsection Predicting what @command{patch} will do 2736170754Sdelphij@cindex testing @command{patch} 2737170754Sdelphij@cindex dry runs for @command{patch} 2738170754Sdelphij 2739170754SdelphijIt may not be obvious in advance what @command{patch} will do with a 2740170754Sdelphijcomplicated or poorly formatted patch. If you are concerned that the 2741170754Sdelphijinput might cause @command{patch} to modify the wrong files, you can 2742170754Sdelphijuse the @option{--dry-run} option, which causes @command{patch} to 2743170754Sdelphijprint the results of applying patches without actually changing any 2744170754Sdelphijfiles. You can then inspect the diagnostics generated by the dry run 2745170754Sdelphijto see whether @command{patch} will modify the files that you expect. 2746170754SdelphijIf the patch does not do what you want, you can modify the patch (or 2747170754Sdelphijthe other options to @command{patch}) and try another dry run. Once 2748170754Sdelphijyou are satisfied with the proposed patch you can apply it by invoking 2749170754Sdelphij@command{patch} as before, but this time without the 2750170754Sdelphij@option{--dry-run} option. 2751170754Sdelphij 2752170754Sdelphij@node Creating and Removing 2753170754Sdelphij@section Creating and Removing Files 2754170754Sdelphij@cindex creating files 2755170754Sdelphij@cindex empty files, removing 2756170754Sdelphij@cindex removing empty files 2757170754Sdelphij 2758170754SdelphijSometimes when comparing two directories, a file may exist in one 2759170754Sdelphijdirectory but not the other. If you give @command{diff} the 2760170754Sdelphij@option{-N} or @option{--new-file} option, or if you supply an old or 2761170754Sdelphijnew file that is named @file{/dev/null} or is empty and is dated the 2762170754SdelphijEpoch (1970-01-01 00:00:00 UTC), @command{diff} outputs a patch that 2763170754Sdelphijadds or deletes the contents of this file. When given such a patch, 2764170754Sdelphij@command{patch} normally creates a new file or removes the old file. 2765170754SdelphijHowever, when conforming to @acronym{POSIX} (@pxref{patch and POSIX}), 2766170754Sdelphij@command{patch} does not remove the old file, but leaves it empty. 2767170754SdelphijThe @option{-E} or @option{--remove-empty-files} option causes 2768170754Sdelphij@command{patch} to remove output files that are empty after applying a 2769170754Sdelphijpatch, even if the patch does not appear to be one that removed the 2770170754Sdelphijfile. 2771170754Sdelphij 2772170754SdelphijIf the patch appears to create a file that already exists, 2773170754Sdelphij@command{patch} asks for confirmation before applying the patch. 2774170754Sdelphij 2775170754Sdelphij@node Patching Time Stamps 2776170754Sdelphij@section Updating Time Stamps on Patched Files 2777170754Sdelphij@cindex time stamps on patched files 2778170754Sdelphij 2779170754SdelphijWhen @command{patch} updates a file, it normally sets the file's 2780170754Sdelphijlast-modified time stamp to the current time of day. If you are using 2781170754Sdelphij@command{patch} to track a software distribution, this can cause 2782170754Sdelphij@command{make} to incorrectly conclude that a patched file is out of 2783170754Sdelphijdate. For example, if @file{syntax.c} depends on @file{syntax.y}, and 2784170754Sdelphij@command{patch} updates @file{syntax.c} and then @file{syntax.y}, then 2785170754Sdelphij@file{syntax.c} will normally appear to be out of date with respect to 2786170754Sdelphij@file{syntax.y} even though its contents are actually up to date. 2787170754Sdelphij 2788170754SdelphijThe @option{-Z} or @option{--set-utc} option causes @command{patch} to 2789170754Sdelphijset a patched file's modification and access times to the time stamps 2790170754Sdelphijgiven in context diff headers. If the context diff headers do not 2791170754Sdelphijspecify a time zone, they are assumed to use Coordinated Universal 2792170754SdelphijTime (@acronym{UTC}, often known as @acronym{GMT}). 2793170754Sdelphij 2794170754SdelphijThe @option{-T} or @option{--set-time} option acts like @option{-Z} or 2795170754Sdelphij@option{--set-utc}, except that it assumes that the context diff 2796170754Sdelphijheaders' time stamps use local time instead of @acronym{UTC}. This option 2797170754Sdelphijis not recommended, because patches using local time cannot easily be 2798170754Sdelphijused by people in other time zones, and because local time stamps are 2799170754Sdelphijambiguous when local clocks move backwards during daylight-saving time 2800170754Sdelphijadjustments. If the context diff headers specify a time zone, this 2801170754Sdelphijoption is equivalent to @option{-Z} or @option{--set-utc}. 2802170754Sdelphij 2803170754Sdelphij@command{patch} normally refrains from setting a file's time stamps if 2804170754Sdelphijthe file's original last-modified time stamp does not match the time 2805170754Sdelphijgiven in the diff header, of if the file's contents do not exactly 2806170754Sdelphijmatch the patch. However, if the @option{-f} or @option{--force} 2807170754Sdelphijoption is given, the file's time stamps are set regardless. 2808170754Sdelphij 2809170754SdelphijDue to the limitations of the current @command{diff} format, 2810170754Sdelphij@command{patch} cannot update the times of files whose contents have 2811170754Sdelphijnot changed. Also, if you set file time stamps to values other than 2812170754Sdelphijthe current time of day, you should also remove (e.g., with @samp{make 2813170754Sdelphijclean}) all files that depend on the patched files, so that later 2814170754Sdelphijinvocations of @command{make} do not get confused by the patched 2815170754Sdelphijfiles' times. 2816170754Sdelphij 2817170754Sdelphij@node Multiple Patches 2818170754Sdelphij@section Multiple Patches in a File 2819170754Sdelphij@cindex multiple patches 2820170754Sdelphij@cindex intuiting file names from patches 2821170754Sdelphij 2822170754SdelphijIf the patch file contains more than one patch, and if you do not 2823170754Sdelphijspecify an input file on the command line, @command{patch} tries to 2824170754Sdelphijapply each patch as if they came from separate patch files. This 2825170754Sdelphijmeans that it determines the name of the file to patch for each patch, 2826170754Sdelphijand that it examines the leading text before each patch for file names 2827170754Sdelphijand prerequisite revision level (@pxref{Making Patches}, for more on 2828170754Sdelphijthat topic). 2829170754Sdelphij 2830170754Sdelphij@command{patch} uses the following rules to intuit a file name from 2831170754Sdelphijthe leading text before a patch. First, @command{patch} takes an 2832170754Sdelphijordered list of candidate file names as follows: 2833170754Sdelphij 2834170754Sdelphij@itemize @bullet 2835170754Sdelphij@item 2836170754SdelphijIf the header is that of a context diff, @command{patch} takes the old 2837170754Sdelphijand new file names in the header. A name is ignored if it does not 2838170754Sdelphijhave enough slashes to satisfy the @option{-p@var{num}} or 2839170754Sdelphij@option{--strip=@var{num}} option. The name @file{/dev/null} is also 2840170754Sdelphijignored. 2841170754Sdelphij 2842170754Sdelphij@item 2843170754SdelphijIf there is an @samp{Index:} line in the leading garbage and if either 2844170754Sdelphijthe old and new names are both absent or if @command{patch} is 2845170754Sdelphijconforming to @acronym{POSIX}, @command{patch} takes the name in the 2846170754Sdelphij@samp{Index:} line. 2847170754Sdelphij 2848170754Sdelphij@item 2849170754SdelphijFor the purpose of the following rules, the candidate file names are 2850170754Sdelphijconsidered to be in the order (old, new, index), regardless of the 2851170754Sdelphijorder that they appear in the header. 2852170754Sdelphij@end itemize 2853170754Sdelphij 2854170754Sdelphij@noindent 2855170754SdelphijThen @command{patch} selects a file name from the candidate list as 2856170754Sdelphijfollows: 2857170754Sdelphij 2858170754Sdelphij@itemize @bullet 2859170754Sdelphij@item 2860170754SdelphijIf some of the named files exist, @command{patch} selects the first 2861170754Sdelphijname if conforming to @acronym{POSIX}, and the best name otherwise. 2862170754Sdelphij 2863170754Sdelphij@item 2864170754SdelphijIf @command{patch} is not ignoring @acronym{RCS}, ClearCase, and @acronym{SCCS} 2865170754Sdelphij(@pxref{Revision Control}), and no named files exist but an @acronym{RCS}, 2866170754SdelphijClearCase, or @acronym{SCCS} master is found, @command{patch} selects the 2867170754Sdelphijfirst named file with an @acronym{RCS}, ClearCase, or @acronym{SCCS} master. 2868170754Sdelphij 2869170754Sdelphij@item 2870170754SdelphijIf no named files exist, no @acronym{RCS}, ClearCase, or @acronym{SCCS} master 2871170754Sdelphijwas found, some names are given, @command{patch} is not conforming to 2872170754Sdelphij@acronym{POSIX}, and the patch appears to create a file, @command{patch} 2873170754Sdelphijselects the best name requiring the creation of the fewest 2874170754Sdelphijdirectories. 2875170754Sdelphij 2876170754Sdelphij@item 2877170754SdelphijIf no file name results from the above heuristics, you are asked for 2878170754Sdelphijthe name of the file to patch, and @command{patch} selects that name. 2879170754Sdelphij@end itemize 2880170754Sdelphij 2881170754SdelphijTo determine the @dfn{best} of a nonempty list of file names, 2882170754Sdelphij@command{patch} first takes all the names with the fewest path name 2883170754Sdelphijcomponents; of those, it then takes all the names with the shortest 2884170754Sdelphijbasename; of those, it then takes all the shortest names; finally, it 2885170754Sdelphijtakes the first remaining name. 2886170754Sdelphij 2887170754Sdelphij@xref{patch and POSIX}, to see whether @command{patch} is conforming 2888170754Sdelphijto @acronym{POSIX}. 2889170754Sdelphij 2890170754Sdelphij@node patch Directories 2891170754Sdelphij@section Applying Patches in Other Directories 2892170754Sdelphij@cindex directories and patch 2893170754Sdelphij@cindex patching directories 2894170754Sdelphij 2895170754SdelphijThe @option{-d @var{directory}} or @option{--directory=@var{directory}} 2896170754Sdelphijoption to @command{patch} makes directory @var{directory} the current 2897170754Sdelphijdirectory for interpreting both file names in the patch file, and file 2898170754Sdelphijnames given as arguments to other options (such as @option{-B} and 2899170754Sdelphij@option{-o}). For example, while in a mail reading program, you can patch 2900170754Sdelphija file in the @file{/usr/src/emacs} directory directly from a message 2901170754Sdelphijcontaining the patch like this: 2902170754Sdelphij 2903170754Sdelphij@example 2904170754Sdelphij| patch -d /usr/src/emacs 2905170754Sdelphij@end example 2906170754Sdelphij 2907170754SdelphijSometimes the file names given in a patch contain leading directories, 2908170754Sdelphijbut you keep your files in a directory different from the one given in 2909170754Sdelphijthe patch. In those cases, you can use the 2910170754Sdelphij@option{-p@var{number}} or @option{--strip=@var{number}} 2911170754Sdelphijoption to set the file name strip count to @var{number}. The strip 2912170754Sdelphijcount tells @command{patch} how many slashes, along with the directory 2913170754Sdelphijnames between them, to strip from the front of file names. A sequence 2914170754Sdelphijof one or more adjacent slashes is counted as a single slash. By 2915170754Sdelphijdefault, @command{patch} strips off all leading directories, leaving 2916170754Sdelphijjust the base file names. 2917170754Sdelphij 2918170754SdelphijFor example, suppose the file name in the patch file is 2919170754Sdelphij@file{/gnu/src/emacs/etc/NEWS}. Using @option{-p0} gives the 2920170754Sdelphijentire file name unmodified, @option{-p1} gives 2921170754Sdelphij@file{gnu/src/emacs/etc/NEWS} (no leading slash), @option{-p4} gives 2922170754Sdelphij@file{etc/NEWS}, and not specifying @option{-p} at all gives @file{NEWS}. 2923170754Sdelphij 2924170754Sdelphij@command{patch} looks for each file (after any slashes have been stripped) 2925170754Sdelphijin the current directory, or if you used the @option{-d @var{directory}} 2926170754Sdelphijoption, in that directory. 2927170754Sdelphij 2928170754Sdelphij@node Backups 2929170754Sdelphij@section Backup Files 2930170754Sdelphij@cindex backup file strategy 2931170754Sdelphij 2932170754SdelphijNormally, @command{patch} creates a backup file if the patch does not 2933170754Sdelphijexactly match the original input file, because in that case the 2934170754Sdelphijoriginal data might not be recovered if you undo the patch with 2935170754Sdelphij@samp{patch -R} (@pxref{Reversed Patches}). However, when conforming 2936170754Sdelphijto @acronym{POSIX}, @command{patch} does not create backup files by 2937170754Sdelphijdefault. @xref{patch and POSIX}. 2938170754Sdelphij 2939170754SdelphijThe @option{-b} or @option{--backup} option causes @command{patch} to 2940170754Sdelphijmake a backup file regardless of whether the patch matches the 2941170754Sdelphijoriginal input. The @option{--backup-if-mismatch} option causes 2942170754Sdelphij@command{patch} to create backup files for mismatches files; this is 2943170754Sdelphijthe default when not conforming to @acronym{POSIX}. The 2944170754Sdelphij@option{--no-backup-if-mismatch} option causes @command{patch} to not 2945170754Sdelphijcreate backup files, even for mismatched patches; this is the default 2946170754Sdelphijwhen conforming to @acronym{POSIX}. 2947170754Sdelphij 2948170754SdelphijWhen backing up a file that does not exist, an empty, unreadable 2949170754Sdelphijbackup file is created as a placeholder to represent the nonexistent 2950170754Sdelphijfile. 2951170754Sdelphij 2952170754Sdelphij@node Backup Names 2953170754Sdelphij@section Backup File Names 2954170754Sdelphij@cindex backup file names 2955170754Sdelphij 2956170754SdelphijNormally, @command{patch} renames an original input file into a backup 2957170754Sdelphijfile by appending to its name the extension @samp{.orig}, or @samp{~} 2958170754Sdelphijif using @samp{.orig} would make the backup file name too 2959170754Sdelphijlong.@footnote{A coding error in @acronym{GNU} @command{patch} version 2960170754Sdelphij2.5.4 causes it to always use @samp{~}, but this should be fixed in 2961170754Sdelphijthe next release.} The @option{-z @var{backup-suffix}} or 2962170754Sdelphij@option{--suffix=@var{backup-suffix}} option causes @command{patch} to 2963170754Sdelphijuse @var{backup-suffix} as the backup extension instead. 2964170754Sdelphij 2965170754Sdelphij@vindex SIMPLE_BACKUP_SUFFIX 2966170754SdelphijAlternately, you can specify the extension for backup files with the 2967170754Sdelphij@env{SIMPLE_BACKUP_SUFFIX} environment variable, which the options 2968170754Sdelphijoverride. 2969170754Sdelphij 2970170754Sdelphij@command{patch} can also create numbered backup files the way 2971170754Sdelphij@acronym{GNU} Emacs does. With this method, instead of having a 2972170754Sdelphijsingle backup of each file, @command{patch} makes a new backup file 2973170754Sdelphijname each time it patches a file. For example, the backups of a file 2974170754Sdelphijnamed @file{sink} would be called, successively, @file{sink.~1~}, 2975170754Sdelphij@file{sink.~2~}, @file{sink.~3~}, etc. 2976170754Sdelphij 2977170754Sdelphij@vindex PATCH_VERSION_CONTROL 2978170754Sdelphij@vindex VERSION_CONTROL 2979170754SdelphijThe @option{-V @var{backup-style}} or 2980170754Sdelphij@option{--version-control=@var{backup-style}} option takes as an 2981170754Sdelphijargument a method for creating backup file names. You can alternately 2982170754Sdelphijcontrol the type of backups that @command{patch} makes with the 2983170754Sdelphij@env{PATCH_VERSION_CONTROL} environment variable, which the 2984170754Sdelphij@option{-V} option overrides. If @env{PATCH_VERSION_CONTROL} is not 2985170754Sdelphijset, the @env{VERSION_CONTROL} environment variable is used instead. 2986170754SdelphijPlease note that these options and variables control backup file 2987170754Sdelphijnames; they do not affect the choice of revision control system 2988170754Sdelphij(@pxref{Revision Control}). 2989170754Sdelphij 2990170754SdelphijThe values of these environment variables and the argument to the 2991170754Sdelphij@option{-V} option are like the @acronym{GNU} Emacs @code{version-control} 2992170754Sdelphijvariable (@pxref{Backup Names, , , emacs, The @acronym{GNU} Emacs Manual}, 2993170754Sdelphijfor more information on backup versions in Emacs). They also 2994170754Sdelphijrecognize synonyms that are more descriptive. The valid values are 2995170754Sdelphijlisted below; unique abbreviations are acceptable. 2996170754Sdelphij 2997170754Sdelphij@table @option 2998170754Sdelphij@item t 2999170754Sdelphij@itemx numbered 3000170754SdelphijAlways make numbered backups. 3001170754Sdelphij 3002170754Sdelphij@item nil 3003170754Sdelphij@itemx existing 3004170754SdelphijMake numbered backups of files that already have them, simple backups of 3005170754Sdelphijthe others. This is the default. 3006170754Sdelphij 3007170754Sdelphij@item never 3008170754Sdelphij@itemx simple 3009170754SdelphijAlways make simple backups. 3010170754Sdelphij@end table 3011170754Sdelphij 3012170754SdelphijYou can also tell @command{patch} to prepend a prefix, such as a 3013170754Sdelphijdirectory name, to produce backup file names. The @option{-B 3014170754Sdelphij@var{prefix}} or @option{--prefix=@var{prefix}} option makes backup 3015170754Sdelphijfiles by prepending @var{prefix} to them. The @option{-Y 3016170754Sdelphij@var{prefix}} or @option{--basename-prefix=@var{prefix}} prepends 3017170754Sdelphij@var{prefix} to the last file name component of backup file names 3018170754Sdelphijinstead; for example, @option{-Y ~} causes the backup name for 3019170754Sdelphij@file{dir/file.c} to be @file{dir/~file.c}. If you use either of 3020170754Sdelphijthese prefix options, the suffix-based options are ignored. 3021170754Sdelphij 3022170754SdelphijIf you specify the output file with the @option{-o} option, that file is 3023170754Sdelphijthe one that is backed up, not the input file. 3024170754Sdelphij 3025170754SdelphijOptions that affect the names of backup files do not affect whether 3026170754Sdelphijbackups are made. For example, if you specify the 3027170754Sdelphij@option{--no-backup-if-mismatch} option, none of the options described 3028170754Sdelphijin this section have any affect, because no backups are made. 3029170754Sdelphij 3030170754Sdelphij@node Reject Names 3031170754Sdelphij@section Reject File Names 3032170754Sdelphij@cindex reject file names 3033170754Sdelphij 3034170754SdelphijThe names for reject files (files containing patches that 3035170754Sdelphij@command{patch} could not find a place to apply) are normally the name 3036170754Sdelphijof the output file with @samp{.rej} appended (or @samp{#} if using 3037170754Sdelphij@samp{.rej} would make the backup file name too long). 3038170754Sdelphij 3039170754SdelphijAlternatively, you can tell @command{patch} to place all of the rejected 3040170754Sdelphijpatches in a single file. The @option{-r @var{reject-file}} or 3041170754Sdelphij@option{--reject-file=@var{reject-file}} option uses @var{reject-file} as 3042170754Sdelphijthe reject file name. 3043170754Sdelphij 3044170754Sdelphij@node patch Messages 3045170754Sdelphij@section Messages and Questions from @command{patch} 3046170754Sdelphij@cindex @command{patch} messages and questions 3047170754Sdelphij@cindex diagnostics from @command{patch} 3048170754Sdelphij@cindex messages from @command{patch} 3049170754Sdelphij 3050170754Sdelphij@command{patch} can produce a variety of messages, especially if it 3051170754Sdelphijhas trouble decoding its input. In a few situations where it's not 3052170754Sdelphijsure how to proceed, @command{patch} normally prompts you for more 3053170754Sdelphijinformation from the keyboard. There are options to produce more or 3054170754Sdelphijfewer messages, to have it not ask for keyboard input, and to 3055170754Sdelphijaffect the way that file names are quoted in messages. 3056170754Sdelphij 3057170754Sdelphij@menu 3058170754Sdelphij* More or Fewer Messages:: Controlling the verbosity of @command{patch}. 3059170754Sdelphij* patch and Keyboard Input:: Inhibiting keyboard input. 3060170754Sdelphij* patch Quoting Style:: Quoting file names in diagnostics. 3061170754Sdelphij@end menu 3062170754Sdelphij 3063170754Sdelphij@command{patch} exits with status 0 if all hunks are applied successfully, 3064170754Sdelphij1 if some hunks cannot be applied, and 2 if there is more serious trouble. 3065170754SdelphijWhen applying a set of patches in a loop, you should check the 3066170754Sdelphijexit status, so you don't apply a later patch to a partially patched 3067170754Sdelphijfile. 3068170754Sdelphij 3069170754Sdelphij@node More or Fewer Messages 3070170754Sdelphij@subsection Controlling the Verbosity of @command{patch} 3071170754Sdelphij@cindex verbose messages from @command{patch} 3072170754Sdelphij@cindex inhibit messages from @command{patch} 3073170754Sdelphij 3074170754SdelphijYou can cause @command{patch} to produce more messages by using the 3075170754Sdelphij@option{--verbose} option. For example, when you give this option, 3076170754Sdelphijthe message @samp{Hmm...} indicates that @command{patch} is reading text in 3077170754Sdelphijthe patch file, attempting to determine whether there is a patch in that 3078170754Sdelphijtext, and if so, what kind of patch it is. 3079170754Sdelphij 3080170754SdelphijYou can inhibit all terminal output from @command{patch}, unless an error 3081170754Sdelphijoccurs, by using the @option{-s}, @option{--quiet}, or @option{--silent} 3082170754Sdelphijoption. 3083170754Sdelphij 3084170754Sdelphij@node patch and Keyboard Input 3085170754Sdelphij@subsection Inhibiting Keyboard Input 3086170754Sdelphij@cindex keyboard input to @command{patch} 3087170754Sdelphij 3088170754SdelphijThere are two ways you can prevent @command{patch} from asking you any 3089170754Sdelphijquestions. The @option{-f} or @option{--force} option assumes that you know 3090170754Sdelphijwhat you are doing. It causes @command{patch} to do the following: 3091170754Sdelphij 3092170754Sdelphij@itemize @bullet 3093170754Sdelphij@item 3094170754SdelphijSkip patches that do not contain file names in their headers. 3095170754Sdelphij 3096170754Sdelphij@item 3097170754SdelphijPatch files even though they have the wrong version for the 3098170754Sdelphij@samp{Prereq:} line in the patch; 3099170754Sdelphij 3100170754Sdelphij@item 3101170754SdelphijAssume that patches are not reversed even if they look like they are. 3102170754Sdelphij@end itemize 3103170754Sdelphij 3104170754Sdelphij@noindent 3105170754SdelphijThe @option{-t} or @option{--batch} option is similar to @option{-f}, in that 3106170754Sdelphijit suppresses questions, but it makes somewhat different assumptions: 3107170754Sdelphij 3108170754Sdelphij@itemize @bullet 3109170754Sdelphij@item 3110170754SdelphijSkip patches that do not contain file names in their headers 3111170754Sdelphij(the same as @option{-f}). 3112170754Sdelphij 3113170754Sdelphij@item 3114170754SdelphijSkip patches for which the file has the wrong version for the 3115170754Sdelphij@samp{Prereq:} line in the patch; 3116170754Sdelphij 3117170754Sdelphij@item 3118170754SdelphijAssume that patches are reversed if they look like they are. 3119170754Sdelphij@end itemize 3120170754Sdelphij 3121170754Sdelphij@node patch Quoting Style 3122170754Sdelphij@subsection @command{patch} Quoting Style 3123170754Sdelphij@cindex quoting style 3124170754Sdelphij 3125170754SdelphijWhen @command{patch} outputs a file name in a diagnostic message, it 3126170754Sdelphijcan format the name in any of several ways. This can be useful to 3127170754Sdelphijoutput file names unambiguously, even if they contain punctuation or 3128170754Sdelphijspecial characters like newlines. The 3129170754Sdelphij@option{--quoting-style=@var{word}} option controls how names are 3130170754Sdelphijoutput. The @var{word} should be one of the following: 3131170754Sdelphij 3132170754Sdelphij@table @samp 3133170754Sdelphij@item literal 3134170754SdelphijOutput names as-is. 3135170754Sdelphij@item shell 3136170754SdelphijQuote names for the shell if they contain shell metacharacters or would 3137170754Sdelphijcause ambiguous output. 3138170754Sdelphij@item shell-always 3139170754SdelphijQuote names for the shell, even if they would normally not require quoting. 3140170754Sdelphij@item c 3141170754SdelphijQuote names as for a C language string. 3142170754Sdelphij@item escape 3143170754SdelphijQuote as with @samp{c} except omit the surrounding double-quote 3144170754Sdelphijcharacters. 3145170754Sdelphij@c The following are not yet implemented in patch 2.5.4. 3146170754Sdelphij@c @item clocale 3147170754Sdelphij@c Quote as with @samp{c} except use quotation marks appropriate for the 3148170754Sdelphij@c locale. 3149170754Sdelphij@c @item locale 3150170754Sdelphij@c @c Use @t instead of @samp to avoid duplicate quoting in some output styles. 3151170754Sdelphij@c Like @samp{clocale}, but quote @t{`like this'} instead of @t{"like 3152170754Sdelphij@c this"} in the default C locale. This looks nicer on many displays. 3153170754Sdelphij@end table 3154170754Sdelphij 3155170754Sdelphij@vindex QUOTING_STYLE 3156170754SdelphijYou can specify the default value of the @option{--quoting-style} 3157170754Sdelphijoption with the environment variable @env{QUOTING_STYLE}. If that 3158170754Sdelphijenvironment variable is not set, the default value is @samp{shell}, 3159170754Sdelphijbut this default may change in a future version of @command{patch}. 3160170754Sdelphij 3161170754Sdelphij@node patch and POSIX 3162170754Sdelphij@section @command{patch} and the @acronym{POSIX} Standard 3163170754Sdelphij@cindex @acronym{POSIX} 3164170754Sdelphij 3165170754Sdelphij@vindex POSIXLY_CORRECT 3166170754SdelphijIf you specify the @option{--posix} option, or set the 3167170754Sdelphij@env{POSIXLY_CORRECT} environment variable, @command{patch} conforms 3168170754Sdelphijmore strictly to the @acronym{POSIX} standard, as follows: 3169170754Sdelphij 3170170754Sdelphij@itemize @bullet 3171170754Sdelphij@item 3172170754SdelphijTake the first existing file from the list (old, new, index) 3173170754Sdelphijwhen intuiting file names from diff headers. @xref{Multiple Patches}. 3174170754Sdelphij 3175170754Sdelphij@item 3176170754SdelphijDo not remove files that are removed by a diff. 3177170754Sdelphij@xref{Creating and Removing}. 3178170754Sdelphij 3179170754Sdelphij@item 3180170754SdelphijDo not ask whether to get files from @acronym{RCS}, ClearCase, or 3181170754Sdelphij@acronym{SCCS}. @xref{Revision Control}. 3182170754Sdelphij 3183170754Sdelphij@item 3184170754SdelphijRequire that all options precede the files in the command line. 3185170754Sdelphij 3186170754Sdelphij@item 3187170754SdelphijDo not backup files, even when there is a mismatch. @xref{Backups}. 3188170754Sdelphij 3189170754Sdelphij@end itemize 3190170754Sdelphij 3191170754Sdelphij@node patch and Tradition 3192170754Sdelphij@section @acronym{GNU} @command{patch} and Traditional @command{patch} 3193170754Sdelphij@cindex traditional @command{patch} 3194170754Sdelphij 3195170754SdelphijThe current version of @acronym{GNU} @command{patch} normally follows the 3196170754Sdelphij@acronym{POSIX} standard. @xref{patch and POSIX}, for the few exceptions 3197170754Sdelphijto this general rule. 3198170754Sdelphij 3199170754SdelphijUnfortunately, @acronym{POSIX} redefined the behavior of @command{patch} in 3200170754Sdelphijseveral important ways. You should be aware of the following 3201170754Sdelphijdifferences if you must interoperate with traditional @command{patch}, 3202170754Sdelphijor with @acronym{GNU} @command{patch} version 2.1 and earlier. 3203170754Sdelphij 3204170754Sdelphij@itemize @bullet 3205170754Sdelphij@item 3206170754SdelphijIn traditional @command{patch}, the @option{-p} option's operand was 3207170754Sdelphijoptional, and a bare @option{-p} was equivalent to @option{-p0}. The 3208170754Sdelphij@option{-p} option now requires an operand, and @option{-p@ 0} is now 3209170754Sdelphijequivalent to @option{-p0}. For maximum compatibility, use options 3210170754Sdelphijlike @option{-p0} and @option{-p1}. 3211170754Sdelphij 3212170754SdelphijAlso, traditional @command{patch} simply counted slashes when 3213170754Sdelphijstripping path prefixes; @command{patch} now counts pathname 3214170754Sdelphijcomponents. That is, a sequence of one or more adjacent slashes now 3215170754Sdelphijcounts as a single slash. For maximum portability, avoid sending 3216170754Sdelphijpatches containing @file{//} in file names. 3217170754Sdelphij 3218170754Sdelphij@item 3219170754SdelphijIn traditional @command{patch}, backups were enabled by default. This 3220170754Sdelphijbehavior is now enabled with the @option{-b} or @option{--backup} 3221170754Sdelphijoption. 3222170754Sdelphij 3223170754SdelphijConversely, in @acronym{POSIX} @command{patch}, backups are never made, 3224170754Sdelphijeven when there is a mismatch. In @acronym{GNU} @command{patch}, this 3225170754Sdelphijbehavior is enabled with the @option{--no-backup-if-mismatch} option, 3226170754Sdelphijor by conforming to @acronym{POSIX}. 3227170754Sdelphij 3228170754SdelphijThe @option{-b@ @var{suffix}} option of traditional @command{patch} is 3229170754Sdelphijequivalent to the @samp{-b -z@ @var{suffix}} options of @acronym{GNU} 3230170754Sdelphij@command{patch}. 3231170754Sdelphij 3232170754Sdelphij@item 3233170754SdelphijTraditional @command{patch} used a complicated (and incompletely 3234170754Sdelphijdocumented) method to intuit the name of the file to be patched from 3235170754Sdelphijthe patch header. This method did not conform to @acronym{POSIX}, and had 3236170754Sdelphija few gotchas. Now @command{patch} uses a different, equally 3237170754Sdelphijcomplicated (but better documented) method that is optionally 3238170754Sdelphij@acronym{POSIX}-conforming; we hope it has fewer gotchas. The two methods 3239170754Sdelphijare compatible if the file names in the context diff header and the 3240170754Sdelphij@samp{Index:} line are all identical after prefix-stripping. Your 3241170754Sdelphijpatch is normally compatible if each header's file names all contain 3242170754Sdelphijthe same number of slashes. 3243170754Sdelphij 3244170754Sdelphij@item 3245170754SdelphijWhen traditional @command{patch} asked the user a question, it sent 3246170754Sdelphijthe question to standard error and looked for an answer from the first 3247170754Sdelphijfile in the following list that was a terminal: standard error, 3248170754Sdelphijstandard output, @file{/dev/tty}, and standard input. Now 3249170754Sdelphij@command{patch} sends questions to standard output and gets answers 3250170754Sdelphijfrom @file{/dev/tty}. Defaults for some answers have been changed so 3251170754Sdelphijthat @command{patch} never goes into an infinite loop when using 3252170754Sdelphijdefault answers. 3253170754Sdelphij 3254170754Sdelphij@item 3255170754SdelphijTraditional @command{patch} exited with a status value that counted 3256170754Sdelphijthe number of bad hunks, or with status 1 if there was real trouble. 3257170754SdelphijNow @command{patch} exits with status 1 if some hunks failed, or with 3258170754Sdelphij2 if there was real trouble. 3259170754Sdelphij 3260170754Sdelphij@item 3261170754SdelphijLimit yourself to the following options when sending instructions 3262170754Sdelphijmeant to be executed by anyone running @acronym{GNU} @command{patch}, 3263170754Sdelphijtraditional @command{patch}, or a @command{patch} that conforms to 3264170754Sdelphij@acronym{POSIX}. Spaces are significant in the following list, and 3265170754Sdelphijoperands are required. 3266170754Sdelphij 3267170754Sdelphij@example 3268170754Sdelphij@option{-c} 3269170754Sdelphij@option{-d @var{dir}} 3270170754Sdelphij@option{-D @var{define}} 3271170754Sdelphij@option{-e} 3272170754Sdelphij@option{-l} 3273170754Sdelphij@option{-n} 3274170754Sdelphij@option{-N} 3275170754Sdelphij@option{-o @var{outfile}} 3276170754Sdelphij@option{-p@var{num}} 3277170754Sdelphij@option{-R} 3278170754Sdelphij@option{-r @var{rejectfile}} 3279170754Sdelphij@end example 3280170754Sdelphij 3281170754Sdelphij@end itemize 3282170754Sdelphij 3283170754Sdelphij@node Making Patches 3284170754Sdelphij@chapter Tips for Making and Using Patches 3285170754Sdelphij 3286170754SdelphijUse some common sense when making and using patches. For example, 3287170754Sdelphijwhen sending bug fixes to a program's maintainer, send several small 3288170754Sdelphijpatches, one per independent subject, instead of one large, 3289170754Sdelphijharder-to-digest patch that covers all the subjects. 3290170754Sdelphij 3291170754SdelphijHere are some other things you should keep in mind if you are going to 3292170754Sdelphijdistribute patches for updating a software package. 3293170754Sdelphij 3294170754Sdelphij@menu 3295170754Sdelphij* Tips for Patch Producers:: Advice for making patches. 3296170754Sdelphij* Tips for Patch Consumers:: Advice for using patches. 3297170754Sdelphij* Avoiding Common Mistakes:: Avoiding common mistakes when using @command{patch}. 3298170754Sdelphij* Generating Smaller Patches:: How to generate smaller patches. 3299170754Sdelphij@end menu 3300170754Sdelphij 3301170754Sdelphij@node Tips for Patch Producers 3302170754Sdelphij@section Tips for Patch Producers 3303170754Sdelphij@cindex patch producer tips 3304170754Sdelphij 3305170754SdelphijTo create a patch that changes an older version of a package into a 3306170754Sdelphijnewer version, first make a copy of the older and newer versions in 3307170754Sdelphijadjacent subdirectories. It is common to do that by unpacking 3308170754Sdelphij@command{tar} archives of the two versions. 3309170754Sdelphij 3310170754SdelphijTo generate the patch, use the command @samp{diff -Naur @var{old} 3311170754Sdelphij@var{new}} where @var{old} and @var{new} identify the old and new 3312170754Sdelphijdirectories. The names @var{old} and @var{new} should not contain any 3313170754Sdelphijslashes. The @option{-N} option lets the patch create and remove 3314170754Sdelphijfiles; @option{-a} lets the patch update non-text files; @option{-u} 3315170754Sdelphijgenerates useful time stamps and enough context; and @option{-r} lets 3316170754Sdelphijthe patch update subdirectories. Here is an example command, using 3317170754SdelphijBourne shell syntax: 3318170754Sdelphij 3319170754Sdelphij@example 3320170754Sdelphijdiff -Naur gcc-3.0.3 gcc-3.0.4 3321170754Sdelphij@end example 3322170754Sdelphij 3323170754SdelphijTell your recipients how to apply the patches. This should include 3324170754Sdelphijwhich working directory to use, and which @command{patch} options to 3325170754Sdelphijuse; the option @samp{-p1} is recommended. Test your procedure by 3326170754Sdelphijpretending to be a recipient and applying your patches to a copy of 3327170754Sdelphijthe original files. 3328170754Sdelphij 3329170754Sdelphij@xref{Avoiding Common Mistakes}, for how to avoid common mistakes when 3330170754Sdelphijgenerating a patch. 3331170754Sdelphij 3332170754Sdelphij@node Tips for Patch Consumers 3333170754Sdelphij@section Tips for Patch Consumers 3334170754Sdelphij@cindex patch consumer tips 3335170754Sdelphij 3336170754SdelphijA patch producer should tell recipients how to apply the patches, so 3337170754Sdelphijthe first rule of thumb for a patch consumer is to follow the 3338170754Sdelphijinstructions supplied with the patch. 3339170754Sdelphij 3340170754Sdelphij@acronym{GNU} @command{diff} can analyze files with arbitrarily long lines 3341170754Sdelphijand files that end in incomplete lines. However, older versions of 3342170754Sdelphij@command{patch} cannot patch such files. If you are having trouble 3343170754Sdelphijapplying such patches, try upgrading to a recent version of @acronym{GNU} 3344170754Sdelphij@command{patch}. 3345170754Sdelphij 3346170754Sdelphij@node Avoiding Common Mistakes 3347170754Sdelphij@section Avoiding Common Mistakes 3348170754Sdelphij@cindex common mistakes with patches 3349170754Sdelphij@cindex patch, common mistakes 3350170754Sdelphij 3351170754SdelphijWhen producing a patch for multiple files, apply @command{diff} to 3352170754Sdelphijdirectories whose names do not have slashes. This reduces confusion 3353170754Sdelphijwhen the patch consumer specifies the @option{-p@var{number}} option, 3354170754Sdelphijsince this option can have surprising results when the old and new 3355170754Sdelphijfile names have different numbers of slashes. For example, do not 3356170754Sdelphijsend a patch with a header that looks like this: 3357170754Sdelphij 3358170754Sdelphij@example 3359170754Sdelphijdiff -Naur v2.0.29/prog/README prog/README 3360170754Sdelphij--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 3361170754Sdelphij+++ prog/README 2002-03-17 20:49:32.442260588 -0800 3362170754Sdelphij@end example 3363170754Sdelphij 3364170754Sdelphij@noindent 3365170754Sdelphijbecause the two file names have different numbers of slashes, and 3366170754Sdelphijdifferent versions of @command{patch} interpret the file names 3367170754Sdelphijdifferently. To avoid confusion, send output that looks like this 3368170754Sdelphijinstead: 3369170754Sdelphij 3370170754Sdelphij@example 3371170754Sdelphijdiff -Naur v2.0.29/prog/README v2.0.30/prog/README 3372170754Sdelphij--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 3373170754Sdelphij+++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800 3374170754Sdelphij@end example 3375170754Sdelphij 3376170754SdelphijMake sure you have specified the file names correctly, either in a 3377170754Sdelphijcontext diff header or with an @samp{Index:} line. Take care to not send out 3378170754Sdelphijreversed patches, since these make people wonder whether they have 3379170754Sdelphijalready applied the patch. 3380170754Sdelphij 3381170754SdelphijAvoid sending patches that compare backup file names like 3382170754Sdelphij@file{README.orig} or @file{README~}, since this might confuse 3383170754Sdelphij@command{patch} into patching a backup file instead of the real file. 3384170754SdelphijInstead, send patches that compare the same base file names in 3385170754Sdelphijdifferent directories, e.g.@: @file{old/README} and @file{new/README}. 3386170754Sdelphij 3387170754SdelphijTo save people from partially applying a patch before other patches that 3388170754Sdelphijshould have gone before it, you can make the first patch in the patch 3389170754Sdelphijfile update a file with a name like @file{patchlevel.h} or 3390170754Sdelphij@file{version.c}, which contains a patch level or version number. If 3391170754Sdelphijthe input file contains the wrong version number, @command{patch} will 3392170754Sdelphijcomplain immediately. 3393170754Sdelphij 3394170754SdelphijAn even clearer way to prevent this problem is to put a @samp{Prereq:} 3395170754Sdelphijline before the patch. If the leading text in the patch file contains a 3396170754Sdelphijline that starts with @samp{Prereq:}, @command{patch} takes the next word 3397170754Sdelphijfrom that line (normally a version number) and checks whether the next 3398170754Sdelphijinput file contains that word, preceded and followed by either 3399170754Sdelphijwhite space or a newline. If not, @command{patch} prompts you for 3400170754Sdelphijconfirmation before proceeding. This makes it difficult to accidentally 3401170754Sdelphijapply patches in the wrong order. 3402170754Sdelphij 3403170754Sdelphij@node Generating Smaller Patches 3404170754Sdelphij@section Generating Smaller Patches 3405170754Sdelphij@cindex patches, shrinking 3406170754Sdelphij 3407170754SdelphijThe simplest way to generate a patch is to use @samp{diff -Naur} 3408170754Sdelphij(@pxref{Tips for Patch Producers}), but you might be able to reduce 3409170754Sdelphijthe size of the patch by renaming or removing some files before making 3410170754Sdelphijthe patch. If the older version of the package contains any files 3411170754Sdelphijthat the newer version does not, or if any files have been renamed 3412170754Sdelphijbetween the two versions, make a list of @command{rm} and @command{mv} 3413170754Sdelphijcommands for the user to execute in the old version directory before 3414170754Sdelphijapplying the patch. Then run those commands yourself in the scratch 3415170754Sdelphijdirectory. 3416170754Sdelphij 3417170754SdelphijIf there are any files that you don't need to include in the patch 3418170754Sdelphijbecause they can easily be rebuilt from other files (for example, 3419170754Sdelphij@file{TAGS} and output from @command{yacc} and @command{makeinfo}), 3420170754Sdelphijexclude them from the patch by giving @command{diff} the @option{-x 3421170754Sdelphij@var{pattern}} option (@pxref{Comparing Directories}). If you want 3422170754Sdelphijyour patch to modify a derived file because your recipients lack tools 3423170754Sdelphijto build it, make sure that the patch for the derived file follows any 3424170754Sdelphijpatches for files that it depends on, so that the recipients' time 3425170754Sdelphijstamps will not confuse @command{make}. 3426170754Sdelphij 3427170754SdelphijNow you can create the patch using @samp{diff -Naur}. Make sure to 3428170754Sdelphijspecify the scratch directory first and the newer directory second. 3429170754Sdelphij 3430170754SdelphijAdd to the top of the patch a note telling the user any @command{rm} and 3431170754Sdelphij@command{mv} commands to run before applying the patch. Then you can 3432170754Sdelphijremove the scratch directory. 3433170754Sdelphij 3434170754SdelphijYou can also shrink the patch size by using fewer lines of context, 3435170754Sdelphijbut bear in mind that @command{patch} typically needs at least two 3436170754Sdelphijlines for proper operation when patches do not exactly match the input 3437170754Sdelphijfiles. 3438170754Sdelphij 3439170754Sdelphij@node Invoking cmp 3440170754Sdelphij@chapter Invoking @command{cmp} 3441170754Sdelphij@cindex invoking @command{cmp} 3442170754Sdelphij@cindex @command{cmp} invocation 3443170754Sdelphij 3444170754SdelphijThe @command{cmp} command compares two files, and if they differ, 3445170754Sdelphijtells the first byte and line number where they differ or reports 3446170754Sdelphijthat one file is a prefix of the other. Bytes and 3447170754Sdelphijlines are numbered starting with 1. The arguments of @command{cmp} 3448170754Sdelphijare as follows: 3449170754Sdelphij 3450170754Sdelphij@example 3451170754Sdelphijcmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file} @r{[}@var{from-skip} @r{[}@var{to-skip}@r{]}@r{]}@r{]} 3452170754Sdelphij@end example 3453170754Sdelphij 3454170754SdelphijThe file name @file{-} is always the standard input. @command{cmp} 3455170754Sdelphijalso uses the standard input if one file name is omitted. The 3456170754Sdelphij@var{from-skip} and @var{to-skip} operands specify how many bytes to 3457170754Sdelphijignore at the start of each file; they are equivalent to the 3458170754Sdelphij@option{--ignore-initial=@var{from-skip}:@var{to-skip}} option. 3459170754Sdelphij 3460170754SdelphijBy default, @command{cmp} outputs nothing if the two files have the 3461170754Sdelphijsame contents. If one file is a prefix of the other, @command{cmp} 3462170754Sdelphijprints to standard error a message of the following form: 3463170754Sdelphij 3464170754Sdelphij@example 3465170754Sdelphijcmp: EOF on @var{shorter-file} 3466170754Sdelphij@end example 3467170754Sdelphij 3468170754SdelphijOtherwise, @command{cmp} prints to standard output a message of the 3469170754Sdelphijfollowing form: 3470170754Sdelphij 3471170754Sdelphij@example 3472170754Sdelphij@var{from-file} @var{to-file} differ: char @var{byte-number}, line @var{line-number} 3473170754Sdelphij@end example 3474170754Sdelphij 3475170754SdelphijThe message formats can differ outside the @acronym{POSIX} locale. 3476170754SdelphijAlso, @acronym{POSIX} allows the @acronym{EOF} message to be followed 3477170754Sdelphijby a blank and some additional information. 3478170754Sdelphij 3479170754SdelphijAn exit status of 0 means no differences were found, 1 means some 3480170754Sdelphijdifferences were found, and 2 means trouble. 3481170754Sdelphij 3482170754Sdelphij@menu 3483170754Sdelphij* cmp Options:: Summary of options to @command{cmp}. 3484170754Sdelphij@end menu 3485170754Sdelphij 3486170754Sdelphij@node cmp Options 3487170754Sdelphij@section Options to @command{cmp} 3488170754Sdelphij@cindex @command{cmp} options 3489170754Sdelphij@cindex options for @command{cmp} 3490170754Sdelphij 3491170754SdelphijBelow is a summary of all of the options that @acronym{GNU} 3492170754Sdelphij@command{cmp} accepts. Most options have two equivalent names, one of 3493170754Sdelphijwhich is a single letter preceded by @samp{-}, and the other of which 3494170754Sdelphijis a long name preceded by @samp{--}. Multiple single letter options 3495170754Sdelphij(unless they take an argument) can be combined into a single command 3496170754Sdelphijline word: @option{-bl} is equivalent to @option{-b -l}. 3497170754Sdelphij 3498170754Sdelphij@table @option 3499170754Sdelphij@item -b 3500170754Sdelphij@itemx --print-bytes 3501170754SdelphijPrint the differing bytes. Display control bytes as a 3502170754Sdelphij@samp{^} followed by a letter of the alphabet and precede bytes 3503170754Sdelphijthat have the high bit set with @samp{M-} (which stands for ``meta''). 3504170754Sdelphij 3505170754Sdelphij@item --help 3506170754SdelphijOutput a summary of usage and then exit. 3507170754Sdelphij 3508170754Sdelphij@item -i @var{skip} 3509170754Sdelphij@itemx --ignore-initial=@var{skip} 3510170754SdelphijIgnore any differences in the first @var{skip} bytes of the input 3511170754Sdelphijfiles. Treat files with fewer than @var{skip} bytes as if they are 3512170754Sdelphijempty. If @var{skip} is of the form 3513170754Sdelphij@option{@var{from-skip}:@var{to-skip}}, skip the first @var{from-skip} 3514170754Sdelphijbytes of the first input file and the first @var{to-skip} bytes of the 3515170754Sdelphijsecond. 3516170754Sdelphij 3517170754Sdelphij@item -l 3518170754Sdelphij@itemx --verbose 3519170754SdelphijOutput the (decimal) byte numbers and (octal) values of all differing bytes, 3520170754Sdelphijinstead of the default standard output. 3521170754Sdelphij 3522170754Sdelphij@item -n @var{count} 3523170754Sdelphij@itemx --bytes=@var{count} 3524170754SdelphijCompare at most @var{count} input bytes. 3525170754Sdelphij 3526170754Sdelphij@item -s 3527170754Sdelphij@itemx --quiet 3528170754Sdelphij@itemx --silent 3529170754SdelphijDo not print anything; only return an exit status indicating whether 3530170754Sdelphijthe files differ. 3531170754Sdelphij 3532170754Sdelphij@item -v 3533170754Sdelphij@itemx --version 3534170754SdelphijOutput version information and then exit. 3535170754Sdelphij@end table 3536170754Sdelphij 3537170754SdelphijIn the above table, operands that are byte counts are normally 3538170754Sdelphijdecimal, but may be preceded by @samp{0} for octal and @samp{0x} for 3539170754Sdelphijhexadecimal. 3540170754Sdelphij 3541170754SdelphijA byte count can be followed by a suffix to specify a multiple of that 3542170754Sdelphijcount; in this case an omitted integer is understood to be 1. A bare 3543170754Sdelphijsize letter, or one followed by @samp{iB}, specifies a multiple using 3544170754Sdelphijpowers of 1024. A size letter followed by @samp{B} specifies powers 3545170754Sdelphijof 1000 instead. For example, @option{-n 4M} and @option{-n 4MiB} are 3546170754Sdelphijequivalent to @option{-n 4194304}, whereas @option{-n 4MB} is 3547170754Sdelphijequivalent to @option{-n 4000000}. This notation is upward compatible 3548170754Sdelphijwith the @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI 3549170754Sdelphijprefixes} for decimal multiples and with the 3550170754Sdelphij@uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2 3551170754Sdelphijprefixes for binary multiples}. 3552170754Sdelphij 3553170754SdelphijThe following suffixes are defined. Large sizes like @code{1Y} may be 3554170754Sdelphijrejected by your computer due to limitations of its arithmetic. 3555170754Sdelphij 3556170754Sdelphij@table @samp 3557170754Sdelphij@item kB 3558170754Sdelphij@cindex kilobyte, definition of 3559170754Sdelphijkilobyte: @math{10^3 = 1000}. 3560170754Sdelphij@item k 3561170754Sdelphij@itemx K 3562170754Sdelphij@itemx KiB 3563170754Sdelphij@cindex kibibyte, definition of 3564170754Sdelphijkibibyte: @math{2^10 = 1024}. @samp{K} is special: the SI prefix is 3565170754Sdelphij@samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and 3566170754Sdelphij@acronym{POSIX} use @samp{k} to mean @samp{KiB}. 3567170754Sdelphij@item MB 3568170754Sdelphij@cindex megabyte, definition of 3569170754Sdelphijmegabyte: @math{10^6 = 1,000,000}. 3570170754Sdelphij@item M 3571170754Sdelphij@itemx MiB 3572170754Sdelphij@cindex mebibyte, definition of 3573170754Sdelphijmebibyte: @math{2^20 = 1,048,576}. 3574170754Sdelphij@item GB 3575170754Sdelphij@cindex gigabyte, definition of 3576170754Sdelphijgigabyte: @math{10^9 = 1,000,000,000}. 3577170754Sdelphij@item G 3578170754Sdelphij@itemx GiB 3579170754Sdelphij@cindex gibibyte, definition of 3580170754Sdelphijgibibyte: @math{2^30 = 1,073,741,824}. 3581170754Sdelphij@item TB 3582170754Sdelphij@cindex terabyte, definition of 3583170754Sdelphijterabyte: @math{10^12 = 1,000,000,000,000}. 3584170754Sdelphij@item T 3585170754Sdelphij@itemx TiB 3586170754Sdelphij@cindex tebibyte, definition of 3587170754Sdelphijtebibyte: @math{2^40 = 1,099,511,627,776}. 3588170754Sdelphij@item PB 3589170754Sdelphij@cindex petabyte, definition of 3590170754Sdelphijpetabyte: @math{10^15 = 1,000,000,000,000,000}. 3591170754Sdelphij@item P 3592170754Sdelphij@itemx PiB 3593170754Sdelphij@cindex pebibyte, definition of 3594170754Sdelphijpebibyte: @math{2^50 = 1,125,899,906,842,624}. 3595170754Sdelphij@item EB 3596170754Sdelphij@cindex exabyte, definition of 3597170754Sdelphijexabyte: @math{10^18 = 1,000,000,000,000,000,000}. 3598170754Sdelphij@item E 3599170754Sdelphij@itemx EiB 3600170754Sdelphij@cindex exbibyte, definition of 3601170754Sdelphijexbibyte: @math{2^60 = 1,152,921,504,606,846,976}. 3602170754Sdelphij@item ZB 3603170754Sdelphij@cindex zettabyte, definition of 3604170754Sdelphijzettabyte: @math{10^21 = 1,000,000,000,000,000,000,000} 3605170754Sdelphij@item Z 3606170754Sdelphij@itemx ZiB 3607170754Sdelphij@math{2^70 = 1,180,591,620,717,411,303,424}. 3608170754Sdelphij(@samp{Zi} is a GNU extension to IEC 60027-2.) 3609170754Sdelphij@item YB 3610170754Sdelphij@cindex yottabyte, definition of 3611170754Sdelphijyottabyte: @math{10^24 = 1,000,000,000,000,000,000,000,000}. 3612170754Sdelphij@item Y 3613170754Sdelphij@itemx YiB 3614170754Sdelphij@math{2^80 = 1,208,925,819,614,629,174,706,176}. 3615170754Sdelphij(@samp{Yi} is a GNU extension to IEC 60027-2.) 3616170754Sdelphij@end table 3617170754Sdelphij 3618170754Sdelphij@node Invoking diff 3619170754Sdelphij@chapter Invoking @command{diff} 3620170754Sdelphij@cindex invoking @command{diff} 3621170754Sdelphij@cindex @command{diff} invocation 3622170754Sdelphij 3623170754SdelphijThe format for running the @command{diff} command is: 3624170754Sdelphij 3625170754Sdelphij@example 3626170754Sdelphijdiff @var{options}@dots{} @var{files}@dots{} 3627170754Sdelphij@end example 3628170754Sdelphij 3629170754SdelphijIn the simplest case, two file names @var{from-file} and 3630170754Sdelphij@var{to-file} are given, and @command{diff} compares the contents of 3631170754Sdelphij@var{from-file} and @var{to-file}. A file name of @file{-} stands for 3632170754Sdelphijtext read from the standard input. As a special case, @samp{diff - -} 3633170754Sdelphijcompares a copy of standard input to itself. 3634170754Sdelphij 3635170754SdelphijIf one file is a directory and the other is not, @command{diff} compares 3636170754Sdelphijthe file in the directory whose name is that of the non-directory. 3637170754SdelphijThe non-directory file must not be @file{-}. 3638170754Sdelphij 3639170754SdelphijIf two file names are given and both are directories, 3640170754Sdelphij@command{diff} compares corresponding files in both directories, in 3641170754Sdelphijalphabetical order; this comparison is not recursive unless the 3642170754Sdelphij@option{-r} or @option{--recursive} option is given. @command{diff} never 3643170754Sdelphijcompares the actual contents of a directory as if it were a file. The 3644170754Sdelphijfile that is fully specified may not be standard input, because standard 3645170754Sdelphijinput is nameless and the notion of ``file with the same name'' does not 3646170754Sdelphijapply. 3647170754Sdelphij 3648170754SdelphijIf the @option{--from-file=@var{file}} option is given, the number of 3649170754Sdelphijfile names is arbitrary, and @var{file} is compared to each named file. 3650170754SdelphijSimilarly, if the @option{--to-file=@var{file}} option is given, each 3651170754Sdelphijnamed file is compared to @var{file}. 3652170754Sdelphij 3653170754Sdelphij@command{diff} options begin with @samp{-}, so normally file names 3654170754Sdelphijmay not begin with @samp{-}. However, @option{--} as an 3655170754Sdelphijargument by itself treats the remaining arguments as file names even if 3656170754Sdelphijthey begin with @samp{-}. 3657170754Sdelphij 3658170754SdelphijAn exit status of 0 means no differences were found, 1 means some 3659170754Sdelphijdifferences were found, and 2 means trouble. Normally, differing 3660170754Sdelphijbinary files count as trouble, but this can be altered by using the 3661170754Sdelphij@option{-a} or @option{--text} option, or the @option{-q} or 3662170754Sdelphij@option{--brief} option. 3663170754Sdelphij 3664170754Sdelphij@menu 3665170754Sdelphij* diff Options:: Summary of options to @command{diff}. 3666170754Sdelphij@end menu 3667170754Sdelphij 3668170754Sdelphij@node diff Options 3669170754Sdelphij@section Options to @command{diff} 3670170754Sdelphij@cindex @command{diff} options 3671170754Sdelphij@cindex options for @command{diff} 3672170754Sdelphij 3673170754SdelphijBelow is a summary of all of the options that @acronym{GNU} 3674170754Sdelphij@command{diff} accepts. Most options have two equivalent names, one 3675170754Sdelphijof which is a single letter preceded by @samp{-}, and the other of 3676170754Sdelphijwhich is a long name preceded by @samp{--}. Multiple single letter 3677170754Sdelphijoptions (unless they take an argument) can be combined into a single 3678170754Sdelphijcommand line word: @option{-ac} is equivalent to @option{-a -c}. Long 3679170754Sdelphijnamed options can be abbreviated to any unique prefix of their name. 3680170754SdelphijBrackets ([ and ]) indicate that an option takes an optional argument. 3681170754Sdelphij 3682170754Sdelphij@table @option 3683170754Sdelphij@item -a 3684170754Sdelphij@itemx --text 3685170754SdelphijTreat all files as text and compare them line-by-line, even if they 3686170754Sdelphijdo not seem to be text. @xref{Binary}. 3687170754Sdelphij 3688170754Sdelphij@item -b 3689170754Sdelphij@itemx --ignore-space-change 3690170754SdelphijIgnore changes in amount of white space. @xref{White Space}. 3691170754Sdelphij 3692170754Sdelphij@item -B 3693170754Sdelphij@itemx --ignore-blank-lines 3694170754SdelphijIgnore changes that just insert or delete blank lines. @xref{Blank 3695170754SdelphijLines}. 3696170754Sdelphij 3697170754Sdelphij@item --binary 3698170754SdelphijRead and write data in binary mode. @xref{Binary}. 3699170754Sdelphij 3700170754Sdelphij@item -c 3701170754SdelphijUse the context output format, showing three lines of context. 3702170754Sdelphij@xref{Context Format}. 3703170754Sdelphij 3704170754Sdelphij@item -C @var{lines} 3705170754Sdelphij@itemx --context@r{[}=@var{lines}@r{]} 3706170754SdelphijUse the context output format, showing @var{lines} (an integer) lines of 3707170754Sdelphijcontext, or three if @var{lines} is not given. @xref{Context Format}. 3708170754SdelphijFor proper operation, @command{patch} typically needs at least two lines of 3709170754Sdelphijcontext. 3710170754Sdelphij 3711170754SdelphijOn older systems, @command{diff} supports an obsolete option 3712170754Sdelphij@option{-@var{lines}} that has effect when combined with @option{-c} 3713170754Sdelphijor @option{-p}. @acronym{POSIX} 1003.1-2001 (@pxref{Standards 3714170754Sdelphijconformance}) does not allow this; use @option{-C @var{lines}} 3715170754Sdelphijinstead. 3716170754Sdelphij 3717170754Sdelphij@item --changed-group-format=@var{format} 3718170754SdelphijUse @var{format} to output a line group containing differing lines from 3719170754Sdelphijboth files in if-then-else format. @xref{Line Group Formats}. 3720170754Sdelphij 3721170754Sdelphij@item -d 3722170754Sdelphij@itemx --minimal 3723170754SdelphijChange the algorithm perhaps find a smaller set of changes. This makes 3724170754Sdelphij@command{diff} slower (sometimes much slower). @xref{diff Performance}. 3725170754Sdelphij 3726170754Sdelphij@item -D @var{name} 3727170754Sdelphij@itemx --ifdef=@var{name} 3728170754SdelphijMake merged @samp{#ifdef} format output, conditional on the preprocessor 3729170754Sdelphijmacro @var{name}. @xref{If-then-else}. 3730170754Sdelphij 3731170754Sdelphij@item -e 3732170754Sdelphij@itemx --ed 3733170754SdelphijMake output that is a valid @command{ed} script. @xref{ed Scripts}. 3734170754Sdelphij 3735170754Sdelphij@item -E 3736170754Sdelphij@itemx --ignore-tab-expansion 3737170754SdelphijIgnore changes due to tab expansion. 3738170754Sdelphij@xref{White Space}. 3739170754Sdelphij 3740170754Sdelphij@item -f 3741170754Sdelphij@itemx --forward-ed 3742170754SdelphijMake output that looks vaguely like an @command{ed} script but has changes 3743170754Sdelphijin the order they appear in the file. @xref{Forward ed}. 3744170754Sdelphij 3745170754Sdelphij@item -F @var{regexp} 3746170754Sdelphij@itemx --show-function-line=@var{regexp} 3747170754SdelphijIn context and unified format, for each hunk of differences, show some 3748170754Sdelphijof the last preceding line that matches @var{regexp}. @xref{Specified 3749170754SdelphijHeadings}. 3750170754Sdelphij 3751170754Sdelphij@item --from-file=@var{file} 3752170754SdelphijCompare @var{file} to each operand; @var{file} may be a directory. 3753170754Sdelphij 3754170754Sdelphij@item --help 3755170754SdelphijOutput a summary of usage and then exit. 3756170754Sdelphij 3757170754Sdelphij@item --horizon-lines=@var{lines} 3758170754SdelphijDo not discard the last @var{lines} lines of the common prefix 3759170754Sdelphijand the first @var{lines} lines of the common suffix. 3760170754Sdelphij@xref{diff Performance}. 3761170754Sdelphij 3762170754Sdelphij@item -i 3763170754Sdelphij@itemx --ignore-case 3764170754SdelphijIgnore changes in case; consider upper- and lower-case letters 3765170754Sdelphijequivalent. @xref{Case Folding}. 3766170754Sdelphij 3767170754Sdelphij@item -I @var{regexp} 3768170754Sdelphij@itemx --ignore-matching-lines=@var{regexp} 3769170754SdelphijIgnore changes that just insert or delete lines that match @var{regexp}. 3770170754Sdelphij@xref{Specified Lines}. 3771170754Sdelphij 3772170754Sdelphij@item --ignore-file-name-case 3773170754SdelphijIgnore case when comparing file names during recursive comparison. 3774170754Sdelphij@xref{Comparing Directories}. 3775170754Sdelphij 3776170754Sdelphij@item -l 3777170754Sdelphij@itemx --paginate 3778170754SdelphijPass the output through @command{pr} to paginate it. @xref{Pagination}. 3779170754Sdelphij 3780170754Sdelphij@item --label=@var{label} 3781170754SdelphijUse @var{label} instead of the file name in the context format 3782170754Sdelphij(@pxref{Context Format}) and unified format (@pxref{Unified Format}) 3783170754Sdelphijheaders. @xref{RCS}. 3784170754Sdelphij 3785170754Sdelphij@item --left-column 3786170754SdelphijPrint only the left column of two common lines in side by side format. 3787170754Sdelphij@xref{Side by Side Format}. 3788170754Sdelphij 3789170754Sdelphij@item --line-format=@var{format} 3790170754SdelphijUse @var{format} to output all input lines in if-then-else format. 3791170754Sdelphij@xref{Line Formats}. 3792170754Sdelphij 3793170754Sdelphij@item -n 3794170754Sdelphij@itemx --rcs 3795170754SdelphijOutput @acronym{RCS}-format diffs; like @option{-f} except that each command 3796170754Sdelphijspecifies the number of lines affected. @xref{RCS}. 3797170754Sdelphij 3798170754Sdelphij@item -N 3799170754Sdelphij@itemx --new-file 3800170754SdelphijIn directory comparison, if a file is found in only one directory, 3801170754Sdelphijtreat it as present but empty in the other directory. @xref{Comparing 3802170754SdelphijDirectories}. 3803170754Sdelphij 3804170754Sdelphij@item --new-group-format=@var{format} 3805170754SdelphijUse @var{format} to output a group of lines taken from just the second 3806170754Sdelphijfile in if-then-else format. @xref{Line Group Formats}. 3807170754Sdelphij 3808170754Sdelphij@item --new-line-format=@var{format} 3809170754SdelphijUse @var{format} to output a line taken from just the second file in 3810170754Sdelphijif-then-else format. @xref{Line Formats}. 3811170754Sdelphij 3812170754Sdelphij@item --old-group-format=@var{format} 3813170754SdelphijUse @var{format} to output a group of lines taken from just the first 3814170754Sdelphijfile in if-then-else format. @xref{Line Group Formats}. 3815170754Sdelphij 3816170754Sdelphij@item --old-line-format=@var{format} 3817170754SdelphijUse @var{format} to output a line taken from just the first file in 3818170754Sdelphijif-then-else format. @xref{Line Formats}. 3819170754Sdelphij 3820170754Sdelphij@item -p 3821170754Sdelphij@itemx --show-c-function 3822170754SdelphijShow which C function each change is in. @xref{C Function Headings}. 3823170754Sdelphij 3824170754Sdelphij@item -q 3825170754Sdelphij@itemx --brief 3826170754SdelphijReport only whether the files differ, not the details of the 3827170754Sdelphijdifferences. @xref{Brief}. 3828170754Sdelphij 3829170754Sdelphij@item -r 3830170754Sdelphij@itemx --recursive 3831170754SdelphijWhen comparing directories, recursively compare any subdirectories 3832170754Sdelphijfound. @xref{Comparing Directories}. 3833170754Sdelphij 3834170754Sdelphij@item -s 3835170754Sdelphij@itemx --report-identical-files 3836170754SdelphijReport when two files are the same. @xref{Comparing Directories}. 3837170754Sdelphij 3838170754Sdelphij@item -S @var{file} 3839170754Sdelphij@itemx --starting-file=@var{file} 3840170754SdelphijWhen comparing directories, start with the file @var{file}. This is 3841170754Sdelphijused for resuming an aborted comparison. @xref{Comparing Directories}. 3842170754Sdelphij 3843170754Sdelphij@item --speed-large-files 3844170754SdelphijUse heuristics to speed handling of large files that have numerous 3845170754Sdelphijscattered small changes. @xref{diff Performance}. 3846170754Sdelphij 3847170754Sdelphij@item --strip-trailing-cr 3848170754SdelphijStrip any trailing carriage return at the end of an input line. 3849170754Sdelphij@xref{Binary}. 3850170754Sdelphij 3851170754Sdelphij@item --suppress-common-lines 3852170754SdelphijDo not print common lines in side by side format. 3853170754Sdelphij@xref{Side by Side Format}. 3854170754Sdelphij 3855170754Sdelphij@item -t 3856170754Sdelphij@itemx --expand-tabs 3857170754SdelphijExpand tabs to spaces in the output, to preserve the alignment of tabs 3858170754Sdelphijin the input files. @xref{Tabs}. 3859170754Sdelphij 3860170754Sdelphij@item -T 3861170754Sdelphij@itemx --initial-tab 3862170754SdelphijOutput a tab rather than a space before the text of a line in normal or 3863170754Sdelphijcontext format. This causes the alignment of tabs in the line to look 3864170754Sdelphijnormal. @xref{Tabs}. 3865170754Sdelphij 3866170754Sdelphij@item --tabsize=@var{columns} 3867170754SdelphijAssume that tab stops are set every @var{columns} (default 8) print 3868170754Sdelphijcolumns. @xref{Tabs}. 3869170754Sdelphij 3870170754Sdelphij@item --to-file=@var{file} 3871170754SdelphijCompare each operand to @var{file}; @var{file} may be a directory. 3872170754Sdelphij 3873170754Sdelphij@item -u 3874170754SdelphijUse the unified output format, showing three lines of context. 3875170754Sdelphij@xref{Unified Format}. 3876170754Sdelphij 3877170754Sdelphij@item --unchanged-group-format=@var{format} 3878170754SdelphijUse @var{format} to output a group of common lines taken from both files 3879170754Sdelphijin if-then-else format. @xref{Line Group Formats}. 3880170754Sdelphij 3881170754Sdelphij@item --unchanged-line-format=@var{format} 3882170754SdelphijUse @var{format} to output a line common to both files in if-then-else 3883170754Sdelphijformat. @xref{Line Formats}. 3884170754Sdelphij 3885170754Sdelphij@item --unidirectional-new-file 3886170754SdelphijWhen comparing directories, if a file appears only in the second 3887170754Sdelphijdirectory of the two, treat it as present but empty in the other. 3888170754Sdelphij@xref{Comparing Directories}. 3889170754Sdelphij 3890170754Sdelphij@item -U @var{lines} 3891170754Sdelphij@itemx --unified@r{[}=@var{lines}@r{]} 3892170754SdelphijUse the unified output format, showing @var{lines} (an integer) lines of 3893170754Sdelphijcontext, or three if @var{lines} is not given. @xref{Unified Format}. 3894170754SdelphijFor proper operation, @command{patch} typically needs at least two lines of 3895170754Sdelphijcontext. 3896170754Sdelphij 3897170754SdelphijOn older systems, @command{diff} supports an obsolete option 3898170754Sdelphij@option{-@var{lines}} that has effect when combined with @option{-u}. 3899170754Sdelphij@acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not allow 3900170754Sdelphijthis; use @option{-U @var{lines}} instead. 3901170754Sdelphij 3902170754Sdelphij@item -v 3903170754Sdelphij@itemx --version 3904170754SdelphijOutput version information and then exit. 3905170754Sdelphij 3906170754Sdelphij@item -w 3907170754Sdelphij@itemx --ignore-all-space 3908170754SdelphijIgnore white space when comparing lines. @xref{White Space}. 3909170754Sdelphij 3910170754Sdelphij@item -W @var{columns} 3911170754Sdelphij@itemx --width=@var{columns} 3912170754SdelphijOutput at most @var{columns} (default 130) print columns per line in 3913170754Sdelphijside by side format. @xref{Side by Side Format}. 3914170754Sdelphij 3915170754Sdelphij@item -x @var{pattern} 3916170754Sdelphij@itemx --exclude=@var{pattern} 3917170754SdelphijWhen comparing directories, ignore files and subdirectories whose basenames 3918170754Sdelphijmatch @var{pattern}. @xref{Comparing Directories}. 3919170754Sdelphij 3920170754Sdelphij@item -X @var{file} 3921170754Sdelphij@itemx --exclude-from=@var{file} 3922170754SdelphijWhen comparing directories, ignore files and subdirectories whose basenames 3923170754Sdelphijmatch any pattern contained in @var{file}. @xref{Comparing Directories}. 3924170754Sdelphij 3925170754Sdelphij@item -y 3926170754Sdelphij@itemx --side-by-side 3927170754SdelphijUse the side by side output format. @xref{Side by Side Format}. 3928170754Sdelphij@end table 3929170754Sdelphij 3930170754Sdelphij@node Invoking diff3 3931170754Sdelphij@chapter Invoking @command{diff3} 3932170754Sdelphij@cindex invoking @command{diff3} 3933170754Sdelphij@cindex @command{diff3} invocation 3934170754Sdelphij 3935170754SdelphijThe @command{diff3} command compares three files and outputs descriptions 3936170754Sdelphijof their differences. Its arguments are as follows: 3937170754Sdelphij 3938170754Sdelphij@example 3939170754Sdelphijdiff3 @var{options}@dots{} @var{mine} @var{older} @var{yours} 3940170754Sdelphij@end example 3941170754Sdelphij 3942170754SdelphijThe files to compare are @var{mine}, @var{older}, and @var{yours}. 3943170754SdelphijAt most one of these three file names may be @file{-}, 3944170754Sdelphijwhich tells @command{diff3} to read the standard input for that file. 3945170754Sdelphij 3946170754SdelphijAn exit status of 0 means @command{diff3} was successful, 1 means some 3947170754Sdelphijconflicts were found, and 2 means trouble. 3948170754Sdelphij 3949170754Sdelphij@menu 3950170754Sdelphij* diff3 Options:: Summary of options to @command{diff3}. 3951170754Sdelphij@end menu 3952170754Sdelphij 3953170754Sdelphij@node diff3 Options 3954170754Sdelphij@section Options to @command{diff3} 3955170754Sdelphij@cindex @command{diff3} options 3956170754Sdelphij@cindex options for @command{diff3} 3957170754Sdelphij 3958170754SdelphijBelow is a summary of all of the options that @acronym{GNU} @command{diff3} 3959170754Sdelphijaccepts. Multiple single letter options (unless they take an argument) 3960170754Sdelphijcan be combined into a single command line argument. 3961170754Sdelphij 3962170754Sdelphij@table @option 3963170754Sdelphij@item -a 3964170754Sdelphij@itemx --text 3965170754SdelphijTreat all files as text and compare them line-by-line, even if they 3966170754Sdelphijdo not appear to be text. @xref{Binary}. 3967170754Sdelphij 3968170754Sdelphij@item -A 3969170754Sdelphij@itemx --show-all 3970170754SdelphijIncorporate all unmerged changes from @var{older} to @var{yours} into 3971170754Sdelphij@var{mine}, surrounding conflicts with bracket lines. 3972170754Sdelphij@xref{Marking Conflicts}. 3973170754Sdelphij 3974170754Sdelphij@item --diff-program=@var{program} 3975170754SdelphijUse the compatible comparison program @var{program} to compare files 3976170754Sdelphijinstead of @command{diff}. 3977170754Sdelphij 3978170754Sdelphij@item -e 3979170754Sdelphij@itemx --ed 3980170754SdelphijGenerate an @command{ed} script that incorporates all the changes from 3981170754Sdelphij@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}. 3982170754Sdelphij 3983170754Sdelphij@item -E 3984170754Sdelphij@itemx --show-overlap 3985170754SdelphijLike @option{-e}, except bracket lines from overlapping changes' first 3986170754Sdelphijand third files. 3987170754Sdelphij@xref{Marking Conflicts}. 3988170754SdelphijWith @option{-E}, an overlapping change looks like this: 3989170754Sdelphij 3990170754Sdelphij@example 3991170754Sdelphij<<<<<<< @var{mine} 3992170754Sdelphij@r{lines from @var{mine}} 3993170754Sdelphij======= 3994170754Sdelphij@r{lines from @var{yours}} 3995170754Sdelphij>>>>>>> @var{yours} 3996170754Sdelphij@end example 3997170754Sdelphij 3998170754Sdelphij@item --help 3999170754SdelphijOutput a summary of usage and then exit. 4000170754Sdelphij 4001170754Sdelphij@item -i 4002170754SdelphijGenerate @samp{w} and @samp{q} commands at the end of the @command{ed} 4003170754Sdelphijscript for System V compatibility. This option must be combined with 4004170754Sdelphijone of the @option{-AeExX3} options, and may not be combined with @option{-m}. 4005170754Sdelphij@xref{Saving the Changed File}. 4006170754Sdelphij 4007170754Sdelphij@item --label=@var{label} 4008170754SdelphijUse the label @var{label} for the brackets output by the @option{-A}, 4009170754Sdelphij@option{-E} and @option{-X} options. This option may be given up to three 4010170754Sdelphijtimes, one for each input file. The default labels are the names of 4011170754Sdelphijthe input files. Thus @samp{diff3 --label X --label Y --label Z -m A 4012170754SdelphijB C} acts like 4013170754Sdelphij@samp{diff3 -m A B C}, except that the output looks like it came from 4014170754Sdelphijfiles named @samp{X}, @samp{Y} and @samp{Z} rather than from files 4015170754Sdelphijnamed @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}. 4016170754Sdelphij 4017170754Sdelphij@item -m 4018170754Sdelphij@itemx --merge 4019170754SdelphijApply the edit script to the first file and send the result to standard 4020170754Sdelphijoutput. Unlike piping the output from @command{diff3} to @command{ed}, this 4021170754Sdelphijworks even for binary files and incomplete lines. @option{-A} is assumed 4022170754Sdelphijif no edit script option is specified. @xref{Bypassing ed}. 4023170754Sdelphij 4024170754Sdelphij@item --strip-trailing-cr 4025170754SdelphijStrip any trailing carriage return at the end of an input line. 4026170754Sdelphij@xref{Binary}. 4027170754Sdelphij 4028170754Sdelphij@item -T 4029170754Sdelphij@itemx --initial-tab 4030170754SdelphijOutput a tab rather than two spaces before the text of a line in normal format. 4031170754SdelphijThis causes the alignment of tabs in the line to look normal. @xref{Tabs}. 4032170754Sdelphij 4033170754Sdelphij@item -v 4034170754Sdelphij@itemx --version 4035170754SdelphijOutput version information and then exit. 4036170754Sdelphij 4037170754Sdelphij@item -x 4038170754Sdelphij@itemx --overlap-only 4039170754SdelphijLike @option{-e}, except output only the overlapping changes. 4040170754Sdelphij@xref{Which Changes}. 4041170754Sdelphij 4042170754Sdelphij@item -X 4043170754SdelphijLike @option{-E}, except output only the overlapping changes. 4044170754SdelphijIn other words, like @option{-x}, except bracket changes as in @option{-E}. 4045170754Sdelphij@xref{Marking Conflicts}. 4046170754Sdelphij 4047170754Sdelphij@item -3 4048170754Sdelphij@itemx --easy-only 4049170754SdelphijLike @option{-e}, except output only the nonoverlapping changes. 4050170754Sdelphij@xref{Which Changes}. 4051170754Sdelphij@end table 4052170754Sdelphij 4053170754Sdelphij@node Invoking patch 4054170754Sdelphij@chapter Invoking @command{patch} 4055170754Sdelphij@cindex invoking @command{patch} 4056170754Sdelphij@cindex @command{patch} invocation 4057170754Sdelphij 4058170754SdelphijNormally @command{patch} is invoked like this: 4059170754Sdelphij 4060170754Sdelphij@example 4061170754Sdelphijpatch <@var{patchfile} 4062170754Sdelphij@end example 4063170754Sdelphij 4064170754SdelphijThe full format for invoking @command{patch} is: 4065170754Sdelphij 4066170754Sdelphij@example 4067170754Sdelphijpatch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]} 4068170754Sdelphij@end example 4069170754Sdelphij 4070170754SdelphijYou can also specify where to read the patch from with the @option{-i 4071170754Sdelphij@var{patchfile}} or @option{--input=@var{patchfile}} option. 4072170754SdelphijIf you do not specify @var{patchfile}, or if @var{patchfile} is 4073170754Sdelphij@file{-}, @command{patch} reads the patch (that is, the @command{diff} output) 4074170754Sdelphijfrom the standard input. 4075170754Sdelphij 4076170754SdelphijIf you do not specify an input file on the command line, @command{patch} 4077170754Sdelphijtries to intuit from the @dfn{leading text} (any text in the patch 4078170754Sdelphijthat comes before the @command{diff} output) which file to edit. 4079170754Sdelphij@xref{Multiple Patches}. 4080170754Sdelphij 4081170754SdelphijBy default, @command{patch} replaces the original input file with the 4082170754Sdelphijpatched version, possibly after renaming the original file into a 4083170754Sdelphijbackup file (@pxref{Backup Names}, for a description of how 4084170754Sdelphij@command{patch} names backup files). You can also specify where to 4085170754Sdelphijput the output with the @option{-o @var{file}} or 4086170754Sdelphij@option{--output=@var{file}} option; however, do not use this option 4087170754Sdelphijif @var{file} is one of the input files. 4088170754Sdelphij 4089170754Sdelphij@menu 4090170754Sdelphij* patch Options:: Summary table of options to @command{patch}. 4091170754Sdelphij@end menu 4092170754Sdelphij 4093170754Sdelphij@node patch Options 4094170754Sdelphij@section Options to @command{patch} 4095170754Sdelphij@cindex @command{patch} options 4096170754Sdelphij@cindex options for @command{patch} 4097170754Sdelphij 4098170754SdelphijHere is a summary of all of the options that @acronym{GNU} @command{patch} 4099170754Sdelphijaccepts. @xref{patch and Tradition}, for which of these options are 4100170754Sdelphijsafe to use in older versions of @command{patch}. 4101170754Sdelphij 4102170754SdelphijMultiple single-letter options that do not take an argument can be 4103170754Sdelphijcombined into a single command line argument with only one dash. 4104170754Sdelphij 4105170754Sdelphij@table @option 4106170754Sdelphij@item -b 4107170754Sdelphij@itemx --backup 4108170754SdelphijBack up the original contents of each file, even if backups would 4109170754Sdelphijnormally not be made. @xref{Backups}. 4110170754Sdelphij 4111170754Sdelphij@item -B @var{prefix} 4112170754Sdelphij@itemx --prefix=@var{prefix} 4113170754SdelphijPrepend @var{prefix} to backup file names. @xref{Backup Names}. 4114170754Sdelphij 4115170754Sdelphij@item --backup-if-mismatch 4116170754SdelphijBack up the original contents of each file if the patch does not 4117170754Sdelphijexactly match the file. This is the default behavior when not 4118170754Sdelphijconforming to @acronym{POSIX}. @xref{Backups}. 4119170754Sdelphij 4120170754Sdelphij@item --binary 4121170754SdelphijRead and write all files in binary mode, except for standard output 4122170754Sdelphijand @file{/dev/tty}. This option has no effect on 4123170754Sdelphij@acronym{POSIX}-conforming systems like @acronym{GNU}/Linux. On systems where 4124170754Sdelphijthis option makes a difference, the patch should be generated by 4125170754Sdelphij@samp{diff -a --binary}. @xref{Binary}. 4126170754Sdelphij 4127170754Sdelphij@item -c 4128170754Sdelphij@itemx --context 4129170754SdelphijInterpret the patch file as a context diff. @xref{patch Input}. 4130170754Sdelphij 4131170754Sdelphij@item -d @var{directory} 4132170754Sdelphij@itemx --directory=@var{directory} 4133170754SdelphijMake directory @var{directory} the current directory for interpreting 4134170754Sdelphijboth file names in the patch file, and file names given as arguments to 4135170754Sdelphijother options. @xref{patch Directories}. 4136170754Sdelphij 4137170754Sdelphij@item -D @var{name} 4138170754Sdelphij@itemx --ifdef=@var{name} 4139170754SdelphijMake merged if-then-else output using @var{name}. @xref{If-then-else}. 4140170754Sdelphij 4141170754Sdelphij@item --dry-run 4142170754SdelphijPrint the results of applying the patches without actually changing 4143170754Sdelphijany files. @xref{Dry Runs}. 4144170754Sdelphij 4145170754Sdelphij@item -e 4146170754Sdelphij@itemx --ed 4147170754SdelphijInterpret the patch file as an @command{ed} script. @xref{patch Input}. 4148170754Sdelphij 4149170754Sdelphij@item -E 4150170754Sdelphij@itemx --remove-empty-files 4151170754SdelphijRemove output files that are empty after the patches have been applied. 4152170754Sdelphij@xref{Creating and Removing}. 4153170754Sdelphij 4154170754Sdelphij@item -f 4155170754Sdelphij@itemx --force 4156170754SdelphijAssume that the user knows exactly what he or she is doing, and do not 4157170754Sdelphijask any questions. @xref{patch Messages}. 4158170754Sdelphij 4159170754Sdelphij@item -F @var{lines} 4160170754Sdelphij@itemx --fuzz=@var{lines} 4161170754SdelphijSet the maximum fuzz factor to @var{lines}. @xref{Inexact}. 4162170754Sdelphij 4163170754Sdelphij@item -g @var{num} 4164170754Sdelphij@itemx --get=@var{num} 4165170754SdelphijIf @var{num} is positive, get input files from a revision control 4166170754Sdelphijsystem as necessary; if zero, do not get the files; if negative, ask 4167170754Sdelphijthe user whether to get the files. @xref{Revision Control}. 4168170754Sdelphij 4169170754Sdelphij@item --help 4170170754SdelphijOutput a summary of usage and then exit. 4171170754Sdelphij 4172170754Sdelphij@item -i @var{patchfile} 4173170754Sdelphij@itemx --input=@var{patchfile} 4174170754SdelphijRead the patch from @var{patchfile} rather than from standard input. 4175170754Sdelphij@xref{patch Options}. 4176170754Sdelphij 4177170754Sdelphij@item -l 4178170754Sdelphij@itemx --ignore-white-space 4179170754SdelphijLet any sequence of blanks (spaces or tabs) in the patch file match 4180170754Sdelphijany sequence of blanks in the input file. @xref{Changed White Space}. 4181170754Sdelphij 4182170754Sdelphij@item -n 4183170754Sdelphij@itemx --normal 4184170754SdelphijInterpret the patch file as a normal diff. @xref{patch Input}. 4185170754Sdelphij 4186170754Sdelphij@item -N 4187170754Sdelphij@itemx --forward 4188170754SdelphijIgnore patches that @command{patch} thinks are reversed or already applied. 4189170754SdelphijSee also @option{-R}. @xref{Reversed Patches}. 4190170754Sdelphij 4191170754Sdelphij@item --no-backup-if-mismatch 4192170754SdelphijDo not back up the original contents of files. This is the default 4193170754Sdelphijbehavior when conforming to @acronym{POSIX}. @xref{Backups}. 4194170754Sdelphij 4195170754Sdelphij@item -o @var{file} 4196170754Sdelphij@itemx --output=@var{file} 4197170754SdelphijUse @var{file} as the output file name. @xref{patch Options}. 4198170754Sdelphij 4199170754Sdelphij@item -p@var{number} 4200170754Sdelphij@itemx --strip=@var{number} 4201170754SdelphijSet the file name strip count to @var{number}. @xref{patch Directories}. 4202170754Sdelphij 4203170754Sdelphij@item --posix 4204170754SdelphijConform to @acronym{POSIX}, as if the @env{POSIXLY_CORRECT} environment 4205170754Sdelphijvariable had been set. @xref{patch and POSIX}. 4206170754Sdelphij 4207170754Sdelphij@item --quoting-style=@var{word} 4208170754SdelphijUse style @var{word} to quote names in diagnostics, as if the 4209170754Sdelphij@env{QUOTING_STYLE} environment variable had been set to @var{word}. 4210170754Sdelphij@xref{patch Quoting Style}. 4211170754Sdelphij 4212170754Sdelphij@item -r @var{reject-file} 4213170754Sdelphij@itemx --reject-file=@var{reject-file} 4214170754SdelphijUse @var{reject-file} as the reject file name. @xref{Reject Names}. 4215170754Sdelphij 4216170754Sdelphij@item -R 4217170754Sdelphij@itemx --reverse 4218170754SdelphijAssume that this patch was created with the old and new files swapped. 4219170754Sdelphij@xref{Reversed Patches}. 4220170754Sdelphij 4221170754Sdelphij@item -s 4222170754Sdelphij@itemx --quiet 4223170754Sdelphij@itemx --silent 4224170754SdelphijWork silently unless an error occurs. @xref{patch Messages}. 4225170754Sdelphij 4226170754Sdelphij@item -t 4227170754Sdelphij@itemx --batch 4228170754SdelphijDo not ask any questions. @xref{patch Messages}. 4229170754Sdelphij 4230170754Sdelphij@item -T 4231170754Sdelphij@itemx --set-time 4232170754SdelphijSet the modification and access times of patched files from time 4233170754Sdelphijstamps given in context diff headers, assuming that the context diff 4234170754Sdelphijheaders use local time. @xref{Patching Time Stamps}. 4235170754Sdelphij 4236170754Sdelphij@item -u 4237170754Sdelphij@itemx --unified 4238170754SdelphijInterpret the patch file as a unified diff. @xref{patch Input}. 4239170754Sdelphij 4240170754Sdelphij@item -v 4241170754Sdelphij@itemx --version 4242170754SdelphijOutput version information and then exit. 4243170754Sdelphij 4244170754Sdelphij@item -V @var{backup-style} 4245170754Sdelphij@itemx --version=control=@var{backup-style} 4246170754SdelphijSelect the naming convention for backup file names. @xref{Backup Names}. 4247170754Sdelphij 4248170754Sdelphij@item --verbose 4249170754SdelphijPrint more diagnostics than usual. @xref{patch Messages}. 4250170754Sdelphij 4251170754Sdelphij@item -x @var{number} 4252170754Sdelphij@itemx --debug=@var{number} 4253170754SdelphijSet internal debugging flags. Of interest only to @command{patch} 4254170754Sdelphijpatchers. 4255170754Sdelphij 4256170754Sdelphij@item -Y @var{prefix} 4257170754Sdelphij@itemx --basename-prefix=@var{prefix} 4258170754SdelphijPrepend @var{prefix} to base names of backup files. @xref{Backup Names}. 4259170754Sdelphij 4260170754Sdelphij@item -z @var{suffix} 4261170754Sdelphij@itemx --suffix=@var{suffix} 4262170754SdelphijUse @var{suffix} as the backup extension instead of @samp{.orig} or 4263170754Sdelphij@samp{~}. @xref{Backup Names}. 4264170754Sdelphij 4265170754Sdelphij@item -Z 4266170754Sdelphij@itemx --set-utc 4267170754SdelphijSet the modification and access times of patched files from time 4268170754Sdelphijstamps given in context diff headers, assuming that the context diff 4269170754Sdelphijheaders use @acronym{UTC}. @xref{Patching Time Stamps}. 4270170754Sdelphij 4271170754Sdelphij@end table 4272170754Sdelphij 4273170754Sdelphij@node Invoking sdiff 4274170754Sdelphij@chapter Invoking @command{sdiff} 4275170754Sdelphij@cindex invoking @command{sdiff} 4276170754Sdelphij@cindex @command{sdiff} invocation 4277170754Sdelphij 4278170754SdelphijThe @command{sdiff} command merges two files and interactively outputs the 4279170754Sdelphijresults. Its arguments are as follows: 4280170754Sdelphij 4281170754Sdelphij@example 4282170754Sdelphijsdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file} 4283170754Sdelphij@end example 4284170754Sdelphij 4285170754SdelphijThis merges @var{from-file} with @var{to-file}, with output to @var{outfile}. 4286170754SdelphijIf @var{from-file} is a directory and @var{to-file} is not, @command{sdiff} 4287170754Sdelphijcompares the file in @var{from-file} whose file name is that of @var{to-file}, 4288170754Sdelphijand vice versa. @var{from-file} and @var{to-file} may not both be 4289170754Sdelphijdirectories. 4290170754Sdelphij 4291170754Sdelphij@command{sdiff} options begin with @samp{-}, so normally @var{from-file} 4292170754Sdelphijand @var{to-file} may not begin with @samp{-}. However, @option{--} as an 4293170754Sdelphijargument by itself treats the remaining arguments as file names even if 4294170754Sdelphijthey begin with @samp{-}. You may not use @file{-} as an input file. 4295170754Sdelphij 4296170754Sdelphij@command{sdiff} without @option{-o} (or @option{--output}) produces a 4297170754Sdelphijside-by-side difference. This usage is obsolete; use the @option{-y} 4298170754Sdelphijor @option{--side-by-side} option of @command{diff} instead. 4299170754Sdelphij 4300170754SdelphijAn exit status of 0 means no differences were found, 1 means some 4301170754Sdelphijdifferences were found, and 2 means trouble. 4302170754Sdelphij 4303170754Sdelphij@menu 4304170754Sdelphij* sdiff Options:: Summary of options to @command{diff}. 4305170754Sdelphij@end menu 4306170754Sdelphij 4307170754Sdelphij@node sdiff Options 4308170754Sdelphij@section Options to @command{sdiff} 4309170754Sdelphij@cindex @command{sdiff} options 4310170754Sdelphij@cindex options for @command{sdiff} 4311170754Sdelphij 4312170754SdelphijBelow is a summary of all of the options that @acronym{GNU} 4313170754Sdelphij@command{sdiff} accepts. Each option has two equivalent names, one of 4314170754Sdelphijwhich is a single letter preceded by @samp{-}, and the other of which 4315170754Sdelphijis a long name preceded by @samp{--}. Multiple single letter options 4316170754Sdelphij(unless they take an argument) can be combined into a single command 4317170754Sdelphijline argument. Long named options can be abbreviated to any unique 4318170754Sdelphijprefix of their name. 4319170754Sdelphij 4320170754Sdelphij@table @option 4321170754Sdelphij@item -a 4322170754Sdelphij@itemx --text 4323170754SdelphijTreat all files as text and compare them line-by-line, even if they 4324170754Sdelphijdo not appear to be text. @xref{Binary}. 4325170754Sdelphij 4326170754Sdelphij@item -b 4327170754Sdelphij@itemx --ignore-space-change 4328170754SdelphijIgnore changes in amount of white space. @xref{White Space}. 4329170754Sdelphij 4330170754Sdelphij@item -B 4331170754Sdelphij@itemx --ignore-blank-lines 4332170754SdelphijIgnore changes that just insert or delete blank lines. @xref{Blank 4333170754SdelphijLines}. 4334170754Sdelphij 4335170754Sdelphij@item -d 4336170754Sdelphij@itemx --minimal 4337170754SdelphijChange the algorithm to perhaps find a smaller set of changes. This 4338170754Sdelphijmakes @command{sdiff} slower (sometimes much slower). @xref{diff 4339170754SdelphijPerformance}. 4340170754Sdelphij 4341170754Sdelphij@item --diff-program=@var{program} 4342170754SdelphijUse the compatible comparison program @var{program} to compare files 4343170754Sdelphijinstead of @command{diff}. 4344170754Sdelphij 4345170754Sdelphij@item -E 4346170754Sdelphij@itemx --ignore-tab-expansion 4347170754SdelphijIgnore changes due to tab expansion. 4348170754Sdelphij@xref{White Space}. 4349170754Sdelphij 4350170754Sdelphij@item --help 4351170754SdelphijOutput a summary of usage and then exit. 4352170754Sdelphij 4353170754Sdelphij@item -i 4354170754Sdelphij@itemx --ignore-case 4355170754SdelphijIgnore changes in case; consider upper- and lower-case to be the same. 4356170754Sdelphij@xref{Case Folding}. 4357170754Sdelphij 4358170754Sdelphij@item -I @var{regexp} 4359170754Sdelphij@itemx --ignore-matching-lines=@var{regexp} 4360170754SdelphijIgnore changes that just insert or delete lines that match @var{regexp}. 4361170754Sdelphij@xref{Specified Lines}. 4362170754Sdelphij 4363170754Sdelphij@item -l 4364170754Sdelphij@itemx --left-column 4365170754SdelphijPrint only the left column of two common lines. 4366170754Sdelphij@xref{Side by Side Format}. 4367170754Sdelphij 4368170754Sdelphij@item -o @var{file} 4369170754Sdelphij@itemx --output=@var{file} 4370170754SdelphijPut merged output into @var{file}. This option is required for merging. 4371170754Sdelphij 4372170754Sdelphij@item -s 4373170754Sdelphij@itemx --suppress-common-lines 4374170754SdelphijDo not print common lines. @xref{Side by Side Format}. 4375170754Sdelphij 4376170754Sdelphij@item --speed-large-files 4377170754SdelphijUse heuristics to speed handling of large files that have numerous 4378170754Sdelphijscattered small changes. @xref{diff Performance}. 4379170754Sdelphij 4380170754Sdelphij@item --strip-trailing-cr 4381170754SdelphijStrip any trailing carriage return at the end of an input line. 4382170754Sdelphij@xref{Binary}. 4383170754Sdelphij 4384170754Sdelphij@item -t 4385170754Sdelphij@itemx --expand-tabs 4386170754SdelphijExpand tabs to spaces in the output, to preserve the alignment of tabs 4387170754Sdelphijin the input files. @xref{Tabs}. 4388170754Sdelphij 4389170754Sdelphij@item --tabsize=@var{columns} 4390170754SdelphijAssume that tab stops are set every @var{columns} (default 8) print 4391170754Sdelphijcolumns. @xref{Tabs}. 4392170754Sdelphij 4393170754Sdelphij@item -v 4394170754Sdelphij@itemx --version 4395170754SdelphijOutput version information and then exit. 4396170754Sdelphij 4397170754Sdelphij@item -w @var{columns} 4398170754Sdelphij@itemx --width=@var{columns} 4399170754SdelphijOutput at most @var{columns} (default 130) print columns per line. 4400170754Sdelphij@xref{Side by Side Format}. Note that for historical reasons, this 4401170754Sdelphijoption is @option{-W} in @command{diff}, @option{-w} in @command{sdiff}. 4402170754Sdelphij 4403170754Sdelphij@item -W 4404170754Sdelphij@itemx --ignore-all-space 4405170754SdelphijIgnore white space when comparing lines. @xref{White Space}. 4406170754SdelphijNote that for historical reasons, this option is @option{-w} in @command{diff}, 4407170754Sdelphij@option{-W} in @command{sdiff}. 4408170754Sdelphij@end table 4409170754Sdelphij 4410170754Sdelphij@node Standards conformance 4411170754Sdelphij@chapter Standards conformance 4412170754Sdelphij@cindex @acronym{POSIX} 4413170754Sdelphij 4414170754Sdelphij@vindex POSIXLY_CORRECT 4415170754SdelphijIn a few cases, the @acronym{GNU} utilities' default behavior is 4416170754Sdelphijincompatible with the @acronym{POSIX} standard. To suppress these 4417170754Sdelphijincompatibilities, define the @env{POSIXLY_CORRECT} environment 4418170754Sdelphijvariable. Unless you are checking for @acronym{POSIX} conformance, you 4419170754Sdelphijprobably do not need to define @env{POSIXLY_CORRECT}. 4420170754Sdelphij 4421170754SdelphijNormally options and operands can appear in any order, and programs act 4422170754Sdelphijas if all the options appear before any operands. For example, 4423170754Sdelphij@samp{diff lao tzu -C 2} acts like @samp{diff -C 2 lao tzu}, since 4424170754Sdelphij@samp{2} is an option-argument of @option{-C}. However, if the 4425170754Sdelphij@env{POSIXLY_CORRECT} environment variable is set, options must appear 4426170754Sdelphijbefore operands, unless otherwise specified for a particular command. 4427170754Sdelphij 4428170754SdelphijNewer versions of @acronym{POSIX} are occasionally incompatible with older 4429170754Sdelphijversions. For example, older versions of @acronym{POSIX} allowed the 4430170754Sdelphijcommand @samp{diff -c -10} to have the same meaning as @samp{diff -C 4431170754Sdelphij10}, but @acronym{POSIX} 1003.1-2001 @samp{diff} no longer allows 4432170754Sdelphijdigit-string options like @option{-10}. 4433170754Sdelphij 4434170754Sdelphij@vindex _POSIX2_VERSION 4435170754SdelphijThe @acronym{GNU} utilities normally conform to the version of @acronym{POSIX} 4436170754Sdelphijthat is standard for your system. To cause them to conform to a 4437170754Sdelphijdifferent version of @acronym{POSIX}, define the @env{_POSIX2_VERSION} 4438170754Sdelphijenvironment variable to a value of the form @var{yyyymm} specifying 4439170754Sdelphijthe year and month the standard was adopted. Two values are currently 4440170754Sdelphijsupported for @env{_POSIX2_VERSION}: @samp{199209} stands for 4441170754Sdelphij@acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX} 4442170754Sdelphij1003.1-2001. For example, if you are running older software that 4443170754Sdelphijassumes an older version of @acronym{POSIX} and uses @samp{diff -c -10}, 4444170754Sdelphijyou can work around the compatibility problems by setting 4445170754Sdelphij@samp{_POSIX2_VERSION=199209} in your environment. 4446170754Sdelphij 4447170754Sdelphij@node Projects 4448170754Sdelphij@chapter Future Projects 4449170754Sdelphij 4450170754SdelphijHere are some ideas for improving @acronym{GNU} @command{diff} and 4451170754Sdelphij@command{patch}. The @acronym{GNU} project has identified some 4452170754Sdelphijimprovements as potential programming projects for volunteers. You 4453170754Sdelphijcan also help by reporting any bugs that you find. 4454170754Sdelphij 4455170754SdelphijIf you are a programmer and would like to contribute something to the 4456170754Sdelphij@acronym{GNU} project, please consider volunteering for one of these 4457170754Sdelphijprojects. If you are seriously contemplating work, please write to 4458170754Sdelphij@email{gvc@@gnu.org} to coordinate with other volunteers. 4459170754Sdelphij 4460170754Sdelphij@menu 4461170754Sdelphij* Shortcomings:: Suggested projects for improvements. 4462170754Sdelphij* Bugs:: Reporting bugs. 4463170754Sdelphij@end menu 4464170754Sdelphij 4465170754Sdelphij@node Shortcomings 4466170754Sdelphij@section Suggested Projects for Improving @acronym{GNU} @command{diff} and @command{patch} 4467170754Sdelphij@cindex projects for directories 4468170754Sdelphij 4469170754SdelphijOne should be able to use @acronym{GNU} @command{diff} to generate a 4470170754Sdelphijpatch from any pair of directory trees, and given the patch and a copy 4471170754Sdelphijof one such tree, use @command{patch} to generate a faithful copy of 4472170754Sdelphijthe other. Unfortunately, some changes to directory trees cannot be 4473170754Sdelphijexpressed using current patch formats; also, @command{patch} does not 4474170754Sdelphijhandle some of the existing formats. These shortcomings motivate the 4475170754Sdelphijfollowing suggested projects. 4476170754Sdelphij 4477170754Sdelphij@menu 4478170754Sdelphij* Internationalization:: Handling multibyte and varying-width characters. 4479170754Sdelphij* Changing Structure:: Handling changes to the directory structure. 4480170754Sdelphij* Special Files:: Handling symbolic links, device special files, etc. 4481170754Sdelphij* Unusual File Names:: Handling file names that contain unusual characters. 4482170754Sdelphij* Time Stamp Order:: Outputting diffs in time stamp order. 4483170754Sdelphij* Ignoring Changes:: Ignoring certain changes while showing others. 4484170754Sdelphij* Speedups:: Improving performance. 4485170754Sdelphij@end menu 4486170754Sdelphij 4487170754Sdelphij@node Internationalization 4488170754Sdelphij@subsection Handling Multibyte and Varying-Width Characters 4489170754Sdelphij@cindex multibyte characters 4490170754Sdelphij@cindex varying-width characters 4491170754Sdelphij 4492170754Sdelphij@command{diff}, @command{diff3} and @command{sdiff} treat each line of 4493170754Sdelphijinput as a string of unibyte characters. This can mishandle multibyte 4494170754Sdelphijcharacters in some cases. For example, when asked to ignore spaces, 4495170754Sdelphij@command{diff} does not properly ignore a multibyte space character. 4496170754Sdelphij 4497170754SdelphijAlso, @command{diff} currently assumes that each byte is one column 4498170754Sdelphijwide, and this assumption is incorrect in some locales, e.g., locales 4499170754Sdelphijthat use UTF-8 encoding. This causes problems with the @option{-y} or 4500170754Sdelphij@option{--side-by-side} option of @command{diff}. 4501170754Sdelphij 4502170754SdelphijThese problems need to be fixed without unduly affecting the 4503170754Sdelphijperformance of the utilities in unibyte environments. 4504170754Sdelphij 4505170754SdelphijThe IBM GNU/Linux Technology Center Internationalization Team has 4506170754Sdelphijproposed 4507170754Sdelphij@uref{http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz,patches 4508170754Sdelphijto support internationalized @command{diff}}. 4509170754SdelphijUnfortunately, these patches are incomplete and are to an older 4510170754Sdelphijversion of @command{diff}, so more work needs to be done in this area. 4511170754Sdelphij 4512170754Sdelphij@node Changing Structure 4513170754Sdelphij@subsection Handling Changes to the Directory Structure 4514170754Sdelphij@cindex directory structure changes 4515170754Sdelphij 4516170754Sdelphij@command{diff} and @command{patch} do not handle some changes to directory 4517170754Sdelphijstructure. For example, suppose one directory tree contains a directory 4518170754Sdelphijnamed @samp{D} with some subsidiary files, and another contains a file 4519170754Sdelphijwith the same name @samp{D}. @samp{diff -r} does not output enough 4520170754Sdelphijinformation for @command{patch} to transform the directory subtree into 4521170754Sdelphijthe file. 4522170754Sdelphij 4523170754SdelphijThere should be a way to specify that a file has been removed without 4524170754Sdelphijhaving to include its entire contents in the patch file. There should 4525170754Sdelphijalso be a way to tell @command{patch} that a file was renamed, even if 4526170754Sdelphijthere is no way for @command{diff} to generate such information. 4527170754SdelphijThere should be a way to tell @command{patch} that a file's time stamp 4528170754Sdelphijhas changed, even if its contents have not changed. 4529170754Sdelphij 4530170754SdelphijThese problems can be fixed by extending the @command{diff} output format 4531170754Sdelphijto represent changes in directory structure, and extending @command{patch} 4532170754Sdelphijto understand these extensions. 4533170754Sdelphij 4534170754Sdelphij@node Special Files 4535170754Sdelphij@subsection Files that are Neither Directories Nor Regular Files 4536170754Sdelphij@cindex special files 4537170754Sdelphij 4538170754SdelphijSome files are neither directories nor regular files: they are unusual 4539170754Sdelphijfiles like symbolic links, device special files, named pipes, and 4540170754Sdelphijsockets. Currently, @command{diff} treats symbolic links as if they 4541170754Sdelphijwere the pointed-to files, except that a recursive @command{diff} 4542170754Sdelphijreports an error if it detects infinite loops of symbolic links (e.g., 4543170754Sdelphijsymbolic links to @file{..}). @command{diff} treats other special 4544170754Sdelphijfiles like regular files if they are specified at the top level, but 4545170754Sdelphijsimply reports their presence when comparing directories. This means 4546170754Sdelphijthat @command{patch} cannot represent changes to such files. For 4547170754Sdelphijexample, if you change which file a symbolic link points to, 4548170754Sdelphij@command{diff} outputs the difference between the two files, instead 4549170754Sdelphijof the change to the symbolic link. 4550170754Sdelphij 4551170754Sdelphij@c This might not be a good idea; is it wise for root to install devices 4552170754Sdelphij@c this way? 4553170754Sdelphij@command{diff} should optionally report changes to special files specially, 4554170754Sdelphijand @command{patch} should be extended to understand these extensions. 4555170754Sdelphij 4556170754Sdelphij@node Unusual File Names 4557170754Sdelphij@subsection File Names that Contain Unusual Characters 4558170754Sdelphij@cindex file names with unusual characters 4559170754Sdelphij 4560170754SdelphijWhen a file name contains an unusual character like a newline or 4561170754Sdelphijwhite space, @samp{diff -r} generates a patch that @command{patch} cannot 4562170754Sdelphijparse. The problem is with format of @command{diff} output, not just with 4563170754Sdelphij@command{patch}, because with odd enough file names one can cause 4564170754Sdelphij@command{diff} to generate a patch that is syntactically correct but 4565170754Sdelphijpatches the wrong files. The format of @command{diff} output should be 4566170754Sdelphijextended to handle all possible file names. 4567170754Sdelphij 4568170754Sdelphij@node Time Stamp Order 4569170754Sdelphij@subsection Outputting Diffs in Time Stamp Order 4570170754Sdelphij 4571170754SdelphijApplying @command{patch} to a multiple-file diff can result in files 4572170754Sdelphijwhose time stamps are out of order. @acronym{GNU} @command{patch} has 4573170754Sdelphijoptions to restore the time stamps of the updated files 4574170754Sdelphij(@pxref{Patching Time Stamps}), but sometimes it is useful to generate 4575170754Sdelphija patch that works even if the recipient does not have @acronym{GNU} patch, 4576170754Sdelphijor does not use these options. One way to do this would be to 4577170754Sdelphijimplement a @command{diff} option to output diffs in time stamp order. 4578170754Sdelphij 4579170754Sdelphij@node Ignoring Changes 4580170754Sdelphij@subsection Ignoring Certain Changes 4581170754Sdelphij 4582170754SdelphijIt would be nice to have a feature for specifying two strings, one in 4583170754Sdelphij@var{from-file} and one in @var{to-file}, which should be considered to 4584170754Sdelphijmatch. Thus, if the two strings are @samp{foo} and @samp{bar}, then if 4585170754Sdelphijtwo lines differ only in that @samp{foo} in file 1 corresponds to 4586170754Sdelphij@samp{bar} in file 2, the lines are treated as identical. 4587170754Sdelphij 4588170754SdelphijIt is not clear how general this feature can or should be, or 4589170754Sdelphijwhat syntax should be used for it. 4590170754Sdelphij 4591170754SdelphijA partial substitute is to filter one or both files before comparing, 4592170754Sdelphije.g.: 4593170754Sdelphij 4594170754Sdelphij@example 4595170754Sdelphijsed 's/foo/bar/g' file1 | diff - file2 4596170754Sdelphij@end example 4597170754Sdelphij 4598170754SdelphijHowever, this outputs the filtered text, not the original. 4599170754Sdelphij 4600170754Sdelphij@node Speedups 4601170754Sdelphij@subsection Improving Performance 4602170754Sdelphij 4603170754SdelphijWhen comparing two large directory structures, one of which was 4604170754Sdelphijoriginally copied from the other with time stamps preserved (e.g., 4605170754Sdelphijwith @samp{cp -pR}), it would greatly improve performance if an option 4606170754Sdelphijtold @command{diff} to assume that two files with the same size and 4607170754Sdelphijtime stamps have the same content. @xref{diff Performance}. 4608170754Sdelphij 4609170754Sdelphij@node Bugs 4610170754Sdelphij@section Reporting Bugs 4611170754Sdelphij@cindex bug reports 4612170754Sdelphij@cindex reporting bugs 4613170754Sdelphij 4614170754SdelphijIf you think you have found a bug in @acronym{GNU} @command{cmp}, 4615170754Sdelphij@command{diff}, @command{diff3}, or @command{sdiff}, please report it 4616170754Sdelphijby electronic mail to the 4617170754Sdelphij@uref{http://mail.gnu.org/mailman/listinfo/bug-gnu-utils,GNU utilities 4618170754Sdelphijbug report mailing list} @email{bug-gnu-utils@@gnu.org}. Please send 4619170754Sdelphijbug reports for @acronym{GNU} @command{patch} to 4620170754Sdelphij@email{bug-patch@@gnu.org}. Send as precise a description of the 4621170754Sdelphijproblem as you can, including the output of the @option{--version} 4622170754Sdelphijoption and sample input files that produce the bug, if applicable. If 4623170754Sdelphijyou have a nontrivial fix for the bug, please send it as well. If you 4624170754Sdelphijhave a patch, please send it too. It may simplify the maintainer's 4625170754Sdelphijjob if the patch is relative to a recent test release, which you can 4626170754Sdelphijfind in the directory @uref{ftp://alpha.gnu.org/gnu/diffutils/}. 4627170754Sdelphij 4628170754Sdelphij@node Copying This Manual 4629170754Sdelphij@appendix Copying This Manual 4630170754Sdelphij 4631170754Sdelphij@menu 4632170754Sdelphij* GNU Free Documentation License:: License for copying this manual. 4633170754Sdelphij@end menu 4634170754Sdelphij 4635170754Sdelphij@include fdl.texi 4636170754Sdelphij 4637170754Sdelphij@node Translations 4638170754Sdelphij@appendix Translations of This Manual 4639170754Sdelphij 4640170754SdelphijNishio Futoshi of the GNUjdoc project has prepared a Japanese 4641170754Sdelphijtranslation of this manual. Its most recent version can be found at 4642170754Sdelphij@uref{http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/}. 4643170754Sdelphij 4644170754Sdelphij@node Index 4645170754Sdelphij@appendix Index 4646170754Sdelphij 4647170754Sdelphij@printindex cp 4648170754Sdelphij 4649170754Sdelphij@bye 4650