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 2468170764Sdelphij@itemx e1 2469170754SdelphijEdit a copy of the left version, then copy the result to the output. 2470170754Sdelphij 2471170754Sdelphij@item er 2472170764Sdelphij@itemx e2 2473170754SdelphijEdit a copy of the right version, then copy the result to the output. 2474170754Sdelphij 2475170754Sdelphij@item l 2476170764Sdelphij@itemx 1 2477170754SdelphijCopy the left version to the output. 2478170754Sdelphij 2479170754Sdelphij@item q 2480170754SdelphijQuit. 2481170754Sdelphij 2482170754Sdelphij@item r 2483170764Sdelphij@itemx 2 2484170754SdelphijCopy the right version to the output. 2485170754Sdelphij 2486170754Sdelphij@item s 2487170754SdelphijSilently copy common lines. 2488170754Sdelphij 2489170754Sdelphij@item v 2490170754SdelphijVerbosely copy common lines. This is the default. 2491170754Sdelphij@end table 2492170754Sdelphij 2493170754Sdelphij@vindex EDITOR 2494170754SdelphijThe text editor invoked is specified by the @env{EDITOR} environment 2495170754Sdelphijvariable if it is set. The default is system-dependent. 2496170754Sdelphij 2497170754Sdelphij@node Merging with patch 2498170754Sdelphij@chapter Merging with @command{patch} 2499170754Sdelphij 2500170754Sdelphij@command{patch} takes comparison output produced by @command{diff} and applies 2501170754Sdelphijthe differences to a copy of the original file, producing a patched 2502170754Sdelphijversion. With @command{patch}, you can distribute just the changes to a 2503170754Sdelphijset of files instead of distributing the entire file set; your 2504170754Sdelphijcorrespondents can apply @command{patch} to update their copy of the files 2505170754Sdelphijwith your changes. @command{patch} automatically determines the diff 2506170754Sdelphijformat, skips any leading or trailing headers, and uses the headers to 2507170754Sdelphijdetermine which file to patch. This lets your correspondents feed a 2508170754Sdelphijmail message containing a difference listing directly to 2509170754Sdelphij@command{patch}. 2510170754Sdelphij 2511170754Sdelphij@command{patch} detects and warns about common problems like forward 2512170754Sdelphijpatches. It saves any patches that it could not apply. It can also maintain a 2513170754Sdelphij@code{patchlevel.h} file to ensure that your correspondents apply 2514170754Sdelphijdiffs in the proper order. 2515170754Sdelphij 2516170754Sdelphij@command{patch} accepts a series of diffs in its standard input, usually 2517170754Sdelphijseparated by headers that specify which file to patch. It applies 2518170754Sdelphij@command{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not 2519170754Sdelphijexactly match the original file, @command{patch} uses heuristics to try to 2520170754Sdelphijpatch the file as well as it can. If no approximate match can be found, 2521170754Sdelphij@command{patch} rejects the hunk and skips to the next hunk. @command{patch} 2522170754Sdelphijnormally replaces each file @var{f} with its new version, putting reject 2523170754Sdelphijhunks (if any) into @samp{@var{f}.rej}. 2524170754Sdelphij 2525170754Sdelphij@xref{Invoking patch}, for detailed information on the options to 2526170754Sdelphij@command{patch}. 2527170754Sdelphij 2528170754Sdelphij@menu 2529170754Sdelphij* patch Input:: Selecting the type of @command{patch} input. 2530170754Sdelphij* Revision Control:: Getting files from @acronym{RCS}, @acronym{SCCS}, etc. 2531170754Sdelphij* Imperfect:: Dealing with imperfect patches. 2532170754Sdelphij* Creating and Removing:: Creating and removing files with a patch. 2533170754Sdelphij* Patching Time Stamps:: Updating time stamps on patched files. 2534170754Sdelphij* Multiple Patches:: Handling multiple patches in a file. 2535170754Sdelphij* patch Directories:: Changing directory and stripping directories. 2536170754Sdelphij* Backups:: Whether backup files are made. 2537170754Sdelphij* Backup Names:: Backup file names. 2538170754Sdelphij* Reject Names:: Reject file names. 2539170754Sdelphij* patch Messages:: Messages and questions @command{patch} can produce. 2540170754Sdelphij* patch and POSIX:: Conformance to the @acronym{POSIX} standard. 2541170754Sdelphij* patch and Tradition:: @acronym{GNU} versus traditional @command{patch}. 2542170754Sdelphij@end menu 2543170754Sdelphij 2544170754Sdelphij@node patch Input 2545170754Sdelphij@section Selecting the @command{patch} Input Format 2546170754Sdelphij@cindex @command{patch} input format 2547170754Sdelphij 2548170754Sdelphij@command{patch} normally determines which @command{diff} format the patch 2549170754Sdelphijfile uses by examining its contents. For patch files that contain 2550170754Sdelphijparticularly confusing leading text, you might need to use one of the 2551170754Sdelphijfollowing options to force @command{patch} to interpret the patch file as a 2552170754Sdelphijcertain format of diff. The output formats listed here are the only 2553170754Sdelphijones that @command{patch} can understand. 2554170754Sdelphij 2555170754Sdelphij@table @option 2556170754Sdelphij@item -c 2557170754Sdelphij@itemx --context 2558170754Sdelphijcontext diff. 2559170754Sdelphij 2560170754Sdelphij@item -e 2561170754Sdelphij@itemx --ed 2562170754Sdelphij@command{ed} script. 2563170754Sdelphij 2564170754Sdelphij@item -n 2565170754Sdelphij@itemx --normal 2566170754Sdelphijnormal diff. 2567170754Sdelphij 2568170754Sdelphij@item -u 2569170754Sdelphij@itemx --unified 2570170754Sdelphijunified diff. 2571170754Sdelphij@end table 2572170754Sdelphij 2573170754Sdelphij@node Revision Control 2574170754Sdelphij@section Revision Control 2575170754Sdelphij@cindex revision control 2576170754Sdelphij@cindex version control 2577170754Sdelphij@cindex @acronym{RCS} 2578170754Sdelphij@cindex ClearCase 2579170754Sdelphij@cindex @acronym{SCCS} 2580170754Sdelphij 2581170754SdelphijIf a nonexistent input file is under a revision control system 2582170754Sdelphijsupported by @command{patch}, @command{patch} normally asks the user 2583170754Sdelphijwhether to get (or check out) the file from the revision control 2584170754Sdelphijsystem. Patch currently supports @acronym{RCS}, ClearCase and 2585170754Sdelphij@acronym{SCCS}. Under @acronym{RCS} and @acronym{SCCS}, 2586170754Sdelphij@command{patch} also asks when the input file is read-only and matches 2587170754Sdelphijthe default version in the revision control system. 2588170754Sdelphij 2589170754Sdelphij@vindex PATCH_GET 2590170754SdelphijThe @option{-g @var{num}} or @option{--get=@var{num}} option affects access 2591170754Sdelphijto files under supported revision control systems. If @var{num} is 2592170754Sdelphijpositive, @command{patch} gets the file without asking the user; if 2593170754Sdelphijzero, @command{patch} neither asks the user nor gets the file; and if 2594170754Sdelphijnegative, @command{patch} asks the user before getting the file. The 2595170754Sdelphijdefault value of @var{num} is given by the value of the 2596170754Sdelphij@env{PATCH_GET} environment variable if it is set; if not, the default 2597170754Sdelphijvalue is zero if @command{patch} is conforming to @acronym{POSIX}, negative 2598170754Sdelphijotherwise. @xref{patch and POSIX}. 2599170754Sdelphij 2600170754Sdelphij@vindex VERSION_CONTROL 2601170754SdelphijThe choice of revision control system is unaffected by the 2602170754Sdelphij@env{VERSION_CONTROL} environment variable (@pxref{Backup Names}). 2603170754Sdelphij 2604170754Sdelphij@node Imperfect 2605170754Sdelphij@section Applying Imperfect Patches 2606170754Sdelphij@cindex imperfect patch application 2607170754Sdelphij 2608170754Sdelphij@command{patch} tries to skip any leading text in the patch file, 2609170754Sdelphijapply the diff, and then skip any trailing text. Thus you can feed a 2610170754Sdelphijmail message directly to @command{patch}, and it should work. If the 2611170754Sdelphijentire diff is indented by a constant amount of white space, 2612170754Sdelphij@command{patch} automatically ignores the indentation. If a context 2613170754Sdelphijdiff contains trailing carriage return on each line, @command{patch} 2614170754Sdelphijautomatically ignores the carriage return. If a context diff has been 2615170754Sdelphijencapsulated by prepending @w{@samp{- }} to lines beginning with @samp{-} 2616170754Sdelphijas per @uref{ftp://ftp.isi.edu/in-notes/rfc934.txt, Internet RFC 934}, 2617170754Sdelphij@command{patch} automatically unencapsulates the input. 2618170754Sdelphij 2619170754SdelphijHowever, certain other types of imperfect input require user 2620170754Sdelphijintervention or testing. 2621170754Sdelphij 2622170754Sdelphij@menu 2623170754Sdelphij* Changed White Space:: When tabs and spaces don't match exactly. 2624170754Sdelphij* Reversed Patches:: Applying reversed patches correctly. 2625170754Sdelphij* Inexact:: Helping @command{patch} find close matches. 2626170754Sdelphij* Dry Runs:: Predicting what @command{patch} will do. 2627170754Sdelphij@end menu 2628170754Sdelphij 2629170754Sdelphij@node Changed White Space 2630170754Sdelphij@subsection Applying Patches with Changed White Space 2631170754Sdelphij@cindex white space in patches 2632170754Sdelphij 2633170754SdelphijSometimes mailers, editors, or other programs change spaces into tabs, 2634170754Sdelphijor vice versa. If this happens to a patch file or an input file, the 2635170754Sdelphijfiles might look the same, but @command{patch} will not be able to match 2636170754Sdelphijthem properly. If this problem occurs, use the @option{-l} or 2637170754Sdelphij@option{--ignore-white-space} option, which makes @command{patch} compare 2638170754Sdelphijblank characters (i.e.@: spaces and tabs) loosely so that any nonempty 2639170754Sdelphijsequence of blanks in the patch file matches any nonempty sequence of 2640170754Sdelphijblanks in the input files. Non-blank 2641170754Sdelphijcharacters must still match exactly. Each line of the context must 2642170754Sdelphijstill match a line in the input file. 2643170754Sdelphij 2644170754Sdelphij@node Reversed Patches 2645170754Sdelphij@subsection Applying Reversed Patches 2646170754Sdelphij@cindex reversed patches 2647170754Sdelphij 2648170754SdelphijSometimes people run @command{diff} with the new file first instead of 2649170754Sdelphijsecond. This creates a diff that is ``reversed''. To apply such 2650170754Sdelphijpatches, give @command{patch} the @option{-R} or @option{--reverse} option. 2651170754Sdelphij@command{patch} then attempts to swap each hunk around before applying it. 2652170754SdelphijRejects come out in the swapped format. 2653170754Sdelphij 2654170754SdelphijOften @command{patch} can guess that the patch is reversed. If the first 2655170754Sdelphijhunk of a patch fails, @command{patch} reverses the hunk to see if it can 2656170754Sdelphijapply it that way. If it can, @command{patch} asks you if you want to have 2657170754Sdelphijthe @option{-R} option set; if it can't, @command{patch} continues to apply 2658170754Sdelphijthe patch normally. This method cannot detect a reversed patch if it is 2659170754Sdelphija normal diff and the first command is an append (which should have been 2660170754Sdelphija delete) since appends always succeed, because a null context matches 2661170754Sdelphijanywhere. But most patches add or change lines rather than delete them, 2662170754Sdelphijso most reversed normal diffs begin with a delete, which fails, and 2663170754Sdelphij@command{patch} notices. 2664170754Sdelphij 2665170754SdelphijIf you apply a patch that you have already applied, @command{patch} thinks 2666170754Sdelphijit is a reversed patch and offers to un-apply the patch. This could be 2667170754Sdelphijconstrued as a feature. If you did this inadvertently and you don't 2668170754Sdelphijwant to un-apply the patch, just answer @samp{n} to this offer and to 2669170754Sdelphijthe subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the 2670170754Sdelphij@command{patch} process. 2671170754Sdelphij 2672170754Sdelphij@node Inexact 2673170754Sdelphij@subsection Helping @command{patch} Find Inexact Matches 2674170754Sdelphij@cindex inexact patches 2675170754Sdelphij@cindex fuzz factor when patching 2676170754Sdelphij 2677170754SdelphijFor context diffs, and to a lesser extent normal diffs, @command{patch} can 2678170754Sdelphijdetect when the line numbers mentioned in the patch are incorrect, and 2679170754Sdelphijit attempts to find the correct place to apply each hunk of the patch. 2680170754SdelphijAs a first guess, it takes the line number mentioned in the hunk, plus 2681170754Sdelphijor minus any offset used in applying the previous hunk. If that is not 2682170754Sdelphijthe correct place, @command{patch} scans both forward and backward for a 2683170754Sdelphijset of lines matching the context given in the hunk. 2684170754Sdelphij 2685170754SdelphijFirst @command{patch} looks for a place where all lines of the context 2686170754Sdelphijmatch. If it cannot find such a place, and it is reading a context or 2687170754Sdelphijunified diff, and the maximum fuzz factor is set to 1 or more, then 2688170754Sdelphij@command{patch} makes another scan, ignoring the first and last line of 2689170754Sdelphijcontext. If that fails, and the maximum fuzz factor is set to 2 or 2690170754Sdelphijmore, it makes another scan, ignoring the first two and last two lines 2691170754Sdelphijof context are ignored. It continues similarly if the maximum fuzz 2692170754Sdelphijfactor is larger. 2693170754Sdelphij 2694170754SdelphijThe @option{-F @var{lines}} or @option{--fuzz=@var{lines}} option sets the 2695170754Sdelphijmaximum fuzz factor to @var{lines}. This option only applies to context 2696170754Sdelphijand unified diffs; it ignores up to @var{lines} lines while looking for 2697170754Sdelphijthe place to install a hunk. Note that a larger fuzz factor increases 2698170754Sdelphijthe odds of making a faulty patch. The default fuzz factor is 2; there 2699170754Sdelphijis no point to setting it to more than the number of lines of context 2700170754Sdelphijin the diff, ordinarily 3. 2701170754Sdelphij 2702170754SdelphijIf @command{patch} cannot find a place to install a hunk of the patch, it 2703170754Sdelphijwrites the hunk out to a reject file (@pxref{Reject Names}, for information 2704170754Sdelphijon how reject files are named). It writes out rejected hunks in context 2705170754Sdelphijformat no matter what form the input patch is in. If the input is a 2706170754Sdelphijnormal or @command{ed} diff, many of the contexts are simply null. The 2707170754Sdelphijline numbers on the hunks in the reject file may be different from those 2708170754Sdelphijin the patch file: they show the approximate location where @command{patch} 2709170754Sdelphijthinks the failed hunks belong in the new file rather than in the old 2710170754Sdelphijone. 2711170754Sdelphij 2712170754SdelphijIf the @option{--verbose} option is given, then 2713170754Sdelphijas it completes each hunk @command{patch} tells you whether the hunk 2714170754Sdelphijsucceeded or failed, and if it failed, on which line (in the new file) 2715170754Sdelphij@command{patch} thinks the hunk should go. If this is different from the 2716170754Sdelphijline number specified in the diff, it tells you the offset. A single 2717170754Sdelphijlarge offset @emph{may} indicate that @command{patch} installed a hunk in 2718170754Sdelphijthe wrong place. @command{patch} also tells you if it used a fuzz factor 2719170754Sdelphijto make the match, in which case you should also be slightly suspicious. 2720170754Sdelphij 2721170754Sdelphij@command{patch} cannot tell if the line numbers are off in an @command{ed} 2722170754Sdelphijscript, and can only detect wrong line numbers in a normal diff when it 2723170754Sdelphijfinds a change or delete command. It may have the same problem with a 2724170754Sdelphijcontext diff using a fuzz factor equal to or greater than the number of 2725170754Sdelphijlines of context shown in the diff (typically 3). In these cases, you 2726170754Sdelphijshould probably look at a context diff between your original and patched 2727170754Sdelphijinput files to see if the changes make sense. Compiling without errors 2728170754Sdelphijis a pretty good indication that the patch worked, but not a guarantee. 2729170754Sdelphij 2730170754SdelphijA patch against an empty file applies to a nonexistent file, and vice 2731170754Sdelphijversa. @xref{Creating and Removing}. 2732170754Sdelphij 2733170754Sdelphij@command{patch} usually produces the correct results, even when it must 2734170754Sdelphijmake many guesses. However, the results are guaranteed only when 2735170754Sdelphijthe patch is applied to an exact copy of the file that the patch was 2736170754Sdelphijgenerated from. 2737170754Sdelphij 2738170754Sdelphij@node Dry Runs 2739170754Sdelphij@subsection Predicting what @command{patch} will do 2740170754Sdelphij@cindex testing @command{patch} 2741170754Sdelphij@cindex dry runs for @command{patch} 2742170754Sdelphij 2743170754SdelphijIt may not be obvious in advance what @command{patch} will do with a 2744170754Sdelphijcomplicated or poorly formatted patch. If you are concerned that the 2745170754Sdelphijinput might cause @command{patch} to modify the wrong files, you can 2746170754Sdelphijuse the @option{--dry-run} option, which causes @command{patch} to 2747170754Sdelphijprint the results of applying patches without actually changing any 2748170754Sdelphijfiles. You can then inspect the diagnostics generated by the dry run 2749170754Sdelphijto see whether @command{patch} will modify the files that you expect. 2750170754SdelphijIf the patch does not do what you want, you can modify the patch (or 2751170754Sdelphijthe other options to @command{patch}) and try another dry run. Once 2752170754Sdelphijyou are satisfied with the proposed patch you can apply it by invoking 2753170754Sdelphij@command{patch} as before, but this time without the 2754170754Sdelphij@option{--dry-run} option. 2755170754Sdelphij 2756170754Sdelphij@node Creating and Removing 2757170754Sdelphij@section Creating and Removing Files 2758170754Sdelphij@cindex creating files 2759170754Sdelphij@cindex empty files, removing 2760170754Sdelphij@cindex removing empty files 2761170754Sdelphij 2762170754SdelphijSometimes when comparing two directories, a file may exist in one 2763170754Sdelphijdirectory but not the other. If you give @command{diff} the 2764170754Sdelphij@option{-N} or @option{--new-file} option, or if you supply an old or 2765170754Sdelphijnew file that is named @file{/dev/null} or is empty and is dated the 2766170754SdelphijEpoch (1970-01-01 00:00:00 UTC), @command{diff} outputs a patch that 2767170754Sdelphijadds or deletes the contents of this file. When given such a patch, 2768170754Sdelphij@command{patch} normally creates a new file or removes the old file. 2769170754SdelphijHowever, when conforming to @acronym{POSIX} (@pxref{patch and POSIX}), 2770170754Sdelphij@command{patch} does not remove the old file, but leaves it empty. 2771170754SdelphijThe @option{-E} or @option{--remove-empty-files} option causes 2772170754Sdelphij@command{patch} to remove output files that are empty after applying a 2773170754Sdelphijpatch, even if the patch does not appear to be one that removed the 2774170754Sdelphijfile. 2775170754Sdelphij 2776170754SdelphijIf the patch appears to create a file that already exists, 2777170754Sdelphij@command{patch} asks for confirmation before applying the patch. 2778170754Sdelphij 2779170754Sdelphij@node Patching Time Stamps 2780170754Sdelphij@section Updating Time Stamps on Patched Files 2781170754Sdelphij@cindex time stamps on patched files 2782170754Sdelphij 2783170754SdelphijWhen @command{patch} updates a file, it normally sets the file's 2784170754Sdelphijlast-modified time stamp to the current time of day. If you are using 2785170754Sdelphij@command{patch} to track a software distribution, this can cause 2786170754Sdelphij@command{make} to incorrectly conclude that a patched file is out of 2787170754Sdelphijdate. For example, if @file{syntax.c} depends on @file{syntax.y}, and 2788170754Sdelphij@command{patch} updates @file{syntax.c} and then @file{syntax.y}, then 2789170754Sdelphij@file{syntax.c} will normally appear to be out of date with respect to 2790170754Sdelphij@file{syntax.y} even though its contents are actually up to date. 2791170754Sdelphij 2792170754SdelphijThe @option{-Z} or @option{--set-utc} option causes @command{patch} to 2793170754Sdelphijset a patched file's modification and access times to the time stamps 2794170754Sdelphijgiven in context diff headers. If the context diff headers do not 2795170754Sdelphijspecify a time zone, they are assumed to use Coordinated Universal 2796170754SdelphijTime (@acronym{UTC}, often known as @acronym{GMT}). 2797170754Sdelphij 2798170754SdelphijThe @option{-T} or @option{--set-time} option acts like @option{-Z} or 2799170754Sdelphij@option{--set-utc}, except that it assumes that the context diff 2800170754Sdelphijheaders' time stamps use local time instead of @acronym{UTC}. This option 2801170754Sdelphijis not recommended, because patches using local time cannot easily be 2802170754Sdelphijused by people in other time zones, and because local time stamps are 2803170754Sdelphijambiguous when local clocks move backwards during daylight-saving time 2804170754Sdelphijadjustments. If the context diff headers specify a time zone, this 2805170754Sdelphijoption is equivalent to @option{-Z} or @option{--set-utc}. 2806170754Sdelphij 2807170754Sdelphij@command{patch} normally refrains from setting a file's time stamps if 2808170754Sdelphijthe file's original last-modified time stamp does not match the time 2809170754Sdelphijgiven in the diff header, of if the file's contents do not exactly 2810170754Sdelphijmatch the patch. However, if the @option{-f} or @option{--force} 2811170754Sdelphijoption is given, the file's time stamps are set regardless. 2812170754Sdelphij 2813170754SdelphijDue to the limitations of the current @command{diff} format, 2814170754Sdelphij@command{patch} cannot update the times of files whose contents have 2815170754Sdelphijnot changed. Also, if you set file time stamps to values other than 2816170754Sdelphijthe current time of day, you should also remove (e.g., with @samp{make 2817170754Sdelphijclean}) all files that depend on the patched files, so that later 2818170754Sdelphijinvocations of @command{make} do not get confused by the patched 2819170754Sdelphijfiles' times. 2820170754Sdelphij 2821170754Sdelphij@node Multiple Patches 2822170754Sdelphij@section Multiple Patches in a File 2823170754Sdelphij@cindex multiple patches 2824170754Sdelphij@cindex intuiting file names from patches 2825170754Sdelphij 2826170754SdelphijIf the patch file contains more than one patch, and if you do not 2827170754Sdelphijspecify an input file on the command line, @command{patch} tries to 2828170754Sdelphijapply each patch as if they came from separate patch files. This 2829170754Sdelphijmeans that it determines the name of the file to patch for each patch, 2830170754Sdelphijand that it examines the leading text before each patch for file names 2831170754Sdelphijand prerequisite revision level (@pxref{Making Patches}, for more on 2832170754Sdelphijthat topic). 2833170754Sdelphij 2834170754Sdelphij@command{patch} uses the following rules to intuit a file name from 2835170754Sdelphijthe leading text before a patch. First, @command{patch} takes an 2836170754Sdelphijordered list of candidate file names as follows: 2837170754Sdelphij 2838170754Sdelphij@itemize @bullet 2839170754Sdelphij@item 2840170754SdelphijIf the header is that of a context diff, @command{patch} takes the old 2841170754Sdelphijand new file names in the header. A name is ignored if it does not 2842170754Sdelphijhave enough slashes to satisfy the @option{-p@var{num}} or 2843170754Sdelphij@option{--strip=@var{num}} option. The name @file{/dev/null} is also 2844170754Sdelphijignored. 2845170754Sdelphij 2846170754Sdelphij@item 2847170754SdelphijIf there is an @samp{Index:} line in the leading garbage and if either 2848170754Sdelphijthe old and new names are both absent or if @command{patch} is 2849170754Sdelphijconforming to @acronym{POSIX}, @command{patch} takes the name in the 2850170754Sdelphij@samp{Index:} line. 2851170754Sdelphij 2852170754Sdelphij@item 2853170754SdelphijFor the purpose of the following rules, the candidate file names are 2854170754Sdelphijconsidered to be in the order (old, new, index), regardless of the 2855170754Sdelphijorder that they appear in the header. 2856170754Sdelphij@end itemize 2857170754Sdelphij 2858170754Sdelphij@noindent 2859170754SdelphijThen @command{patch} selects a file name from the candidate list as 2860170754Sdelphijfollows: 2861170754Sdelphij 2862170754Sdelphij@itemize @bullet 2863170754Sdelphij@item 2864170754SdelphijIf some of the named files exist, @command{patch} selects the first 2865170754Sdelphijname if conforming to @acronym{POSIX}, and the best name otherwise. 2866170754Sdelphij 2867170754Sdelphij@item 2868170754SdelphijIf @command{patch} is not ignoring @acronym{RCS}, ClearCase, and @acronym{SCCS} 2869170754Sdelphij(@pxref{Revision Control}), and no named files exist but an @acronym{RCS}, 2870170754SdelphijClearCase, or @acronym{SCCS} master is found, @command{patch} selects the 2871170754Sdelphijfirst named file with an @acronym{RCS}, ClearCase, or @acronym{SCCS} master. 2872170754Sdelphij 2873170754Sdelphij@item 2874170754SdelphijIf no named files exist, no @acronym{RCS}, ClearCase, or @acronym{SCCS} master 2875170754Sdelphijwas found, some names are given, @command{patch} is not conforming to 2876170754Sdelphij@acronym{POSIX}, and the patch appears to create a file, @command{patch} 2877170754Sdelphijselects the best name requiring the creation of the fewest 2878170754Sdelphijdirectories. 2879170754Sdelphij 2880170754Sdelphij@item 2881170754SdelphijIf no file name results from the above heuristics, you are asked for 2882170754Sdelphijthe name of the file to patch, and @command{patch} selects that name. 2883170754Sdelphij@end itemize 2884170754Sdelphij 2885170754SdelphijTo determine the @dfn{best} of a nonempty list of file names, 2886170754Sdelphij@command{patch} first takes all the names with the fewest path name 2887170754Sdelphijcomponents; of those, it then takes all the names with the shortest 2888170754Sdelphijbasename; of those, it then takes all the shortest names; finally, it 2889170754Sdelphijtakes the first remaining name. 2890170754Sdelphij 2891170754Sdelphij@xref{patch and POSIX}, to see whether @command{patch} is conforming 2892170754Sdelphijto @acronym{POSIX}. 2893170754Sdelphij 2894170754Sdelphij@node patch Directories 2895170754Sdelphij@section Applying Patches in Other Directories 2896170754Sdelphij@cindex directories and patch 2897170754Sdelphij@cindex patching directories 2898170754Sdelphij 2899170754SdelphijThe @option{-d @var{directory}} or @option{--directory=@var{directory}} 2900170754Sdelphijoption to @command{patch} makes directory @var{directory} the current 2901170754Sdelphijdirectory for interpreting both file names in the patch file, and file 2902170754Sdelphijnames given as arguments to other options (such as @option{-B} and 2903170754Sdelphij@option{-o}). For example, while in a mail reading program, you can patch 2904170754Sdelphija file in the @file{/usr/src/emacs} directory directly from a message 2905170754Sdelphijcontaining the patch like this: 2906170754Sdelphij 2907170754Sdelphij@example 2908170754Sdelphij| patch -d /usr/src/emacs 2909170754Sdelphij@end example 2910170754Sdelphij 2911170754SdelphijSometimes the file names given in a patch contain leading directories, 2912170754Sdelphijbut you keep your files in a directory different from the one given in 2913170754Sdelphijthe patch. In those cases, you can use the 2914170754Sdelphij@option{-p@var{number}} or @option{--strip=@var{number}} 2915170754Sdelphijoption to set the file name strip count to @var{number}. The strip 2916170754Sdelphijcount tells @command{patch} how many slashes, along with the directory 2917170754Sdelphijnames between them, to strip from the front of file names. A sequence 2918170754Sdelphijof one or more adjacent slashes is counted as a single slash. By 2919170754Sdelphijdefault, @command{patch} strips off all leading directories, leaving 2920170754Sdelphijjust the base file names. 2921170754Sdelphij 2922170754SdelphijFor example, suppose the file name in the patch file is 2923170754Sdelphij@file{/gnu/src/emacs/etc/NEWS}. Using @option{-p0} gives the 2924170754Sdelphijentire file name unmodified, @option{-p1} gives 2925170754Sdelphij@file{gnu/src/emacs/etc/NEWS} (no leading slash), @option{-p4} gives 2926170754Sdelphij@file{etc/NEWS}, and not specifying @option{-p} at all gives @file{NEWS}. 2927170754Sdelphij 2928170754Sdelphij@command{patch} looks for each file (after any slashes have been stripped) 2929170754Sdelphijin the current directory, or if you used the @option{-d @var{directory}} 2930170754Sdelphijoption, in that directory. 2931170754Sdelphij 2932170754Sdelphij@node Backups 2933170754Sdelphij@section Backup Files 2934170754Sdelphij@cindex backup file strategy 2935170754Sdelphij 2936170754SdelphijNormally, @command{patch} creates a backup file if the patch does not 2937170754Sdelphijexactly match the original input file, because in that case the 2938170754Sdelphijoriginal data might not be recovered if you undo the patch with 2939170754Sdelphij@samp{patch -R} (@pxref{Reversed Patches}). However, when conforming 2940170754Sdelphijto @acronym{POSIX}, @command{patch} does not create backup files by 2941170754Sdelphijdefault. @xref{patch and POSIX}. 2942170754Sdelphij 2943170754SdelphijThe @option{-b} or @option{--backup} option causes @command{patch} to 2944170754Sdelphijmake a backup file regardless of whether the patch matches the 2945170754Sdelphijoriginal input. The @option{--backup-if-mismatch} option causes 2946170754Sdelphij@command{patch} to create backup files for mismatches files; this is 2947170754Sdelphijthe default when not conforming to @acronym{POSIX}. The 2948170754Sdelphij@option{--no-backup-if-mismatch} option causes @command{patch} to not 2949170754Sdelphijcreate backup files, even for mismatched patches; this is the default 2950170754Sdelphijwhen conforming to @acronym{POSIX}. 2951170754Sdelphij 2952170754SdelphijWhen backing up a file that does not exist, an empty, unreadable 2953170754Sdelphijbackup file is created as a placeholder to represent the nonexistent 2954170754Sdelphijfile. 2955170754Sdelphij 2956170754Sdelphij@node Backup Names 2957170754Sdelphij@section Backup File Names 2958170754Sdelphij@cindex backup file names 2959170754Sdelphij 2960170754SdelphijNormally, @command{patch} renames an original input file into a backup 2961170754Sdelphijfile by appending to its name the extension @samp{.orig}, or @samp{~} 2962170754Sdelphijif using @samp{.orig} would make the backup file name too 2963170754Sdelphijlong.@footnote{A coding error in @acronym{GNU} @command{patch} version 2964170754Sdelphij2.5.4 causes it to always use @samp{~}, but this should be fixed in 2965170754Sdelphijthe next release.} The @option{-z @var{backup-suffix}} or 2966170754Sdelphij@option{--suffix=@var{backup-suffix}} option causes @command{patch} to 2967170754Sdelphijuse @var{backup-suffix} as the backup extension instead. 2968170754Sdelphij 2969170754Sdelphij@vindex SIMPLE_BACKUP_SUFFIX 2970170754SdelphijAlternately, you can specify the extension for backup files with the 2971170754Sdelphij@env{SIMPLE_BACKUP_SUFFIX} environment variable, which the options 2972170754Sdelphijoverride. 2973170754Sdelphij 2974170754Sdelphij@command{patch} can also create numbered backup files the way 2975170754Sdelphij@acronym{GNU} Emacs does. With this method, instead of having a 2976170754Sdelphijsingle backup of each file, @command{patch} makes a new backup file 2977170754Sdelphijname each time it patches a file. For example, the backups of a file 2978170754Sdelphijnamed @file{sink} would be called, successively, @file{sink.~1~}, 2979170754Sdelphij@file{sink.~2~}, @file{sink.~3~}, etc. 2980170754Sdelphij 2981170754Sdelphij@vindex PATCH_VERSION_CONTROL 2982170754Sdelphij@vindex VERSION_CONTROL 2983170754SdelphijThe @option{-V @var{backup-style}} or 2984170754Sdelphij@option{--version-control=@var{backup-style}} option takes as an 2985170754Sdelphijargument a method for creating backup file names. You can alternately 2986170754Sdelphijcontrol the type of backups that @command{patch} makes with the 2987170754Sdelphij@env{PATCH_VERSION_CONTROL} environment variable, which the 2988170754Sdelphij@option{-V} option overrides. If @env{PATCH_VERSION_CONTROL} is not 2989170754Sdelphijset, the @env{VERSION_CONTROL} environment variable is used instead. 2990170754SdelphijPlease note that these options and variables control backup file 2991170754Sdelphijnames; they do not affect the choice of revision control system 2992170754Sdelphij(@pxref{Revision Control}). 2993170754Sdelphij 2994170754SdelphijThe values of these environment variables and the argument to the 2995170754Sdelphij@option{-V} option are like the @acronym{GNU} Emacs @code{version-control} 2996170754Sdelphijvariable (@pxref{Backup Names, , , emacs, The @acronym{GNU} Emacs Manual}, 2997170754Sdelphijfor more information on backup versions in Emacs). They also 2998170754Sdelphijrecognize synonyms that are more descriptive. The valid values are 2999170754Sdelphijlisted below; unique abbreviations are acceptable. 3000170754Sdelphij 3001170754Sdelphij@table @option 3002170754Sdelphij@item t 3003170754Sdelphij@itemx numbered 3004170754SdelphijAlways make numbered backups. 3005170754Sdelphij 3006170754Sdelphij@item nil 3007170754Sdelphij@itemx existing 3008170754SdelphijMake numbered backups of files that already have them, simple backups of 3009170754Sdelphijthe others. This is the default. 3010170754Sdelphij 3011170754Sdelphij@item never 3012170754Sdelphij@itemx simple 3013170754SdelphijAlways make simple backups. 3014170754Sdelphij@end table 3015170754Sdelphij 3016170754SdelphijYou can also tell @command{patch} to prepend a prefix, such as a 3017170754Sdelphijdirectory name, to produce backup file names. The @option{-B 3018170754Sdelphij@var{prefix}} or @option{--prefix=@var{prefix}} option makes backup 3019170754Sdelphijfiles by prepending @var{prefix} to them. The @option{-Y 3020170754Sdelphij@var{prefix}} or @option{--basename-prefix=@var{prefix}} prepends 3021170754Sdelphij@var{prefix} to the last file name component of backup file names 3022170754Sdelphijinstead; for example, @option{-Y ~} causes the backup name for 3023170754Sdelphij@file{dir/file.c} to be @file{dir/~file.c}. If you use either of 3024170754Sdelphijthese prefix options, the suffix-based options are ignored. 3025170754Sdelphij 3026170754SdelphijIf you specify the output file with the @option{-o} option, that file is 3027170754Sdelphijthe one that is backed up, not the input file. 3028170754Sdelphij 3029170754SdelphijOptions that affect the names of backup files do not affect whether 3030170754Sdelphijbackups are made. For example, if you specify the 3031170754Sdelphij@option{--no-backup-if-mismatch} option, none of the options described 3032170754Sdelphijin this section have any affect, because no backups are made. 3033170754Sdelphij 3034170754Sdelphij@node Reject Names 3035170754Sdelphij@section Reject File Names 3036170754Sdelphij@cindex reject file names 3037170754Sdelphij 3038170754SdelphijThe names for reject files (files containing patches that 3039170754Sdelphij@command{patch} could not find a place to apply) are normally the name 3040170754Sdelphijof the output file with @samp{.rej} appended (or @samp{#} if using 3041170754Sdelphij@samp{.rej} would make the backup file name too long). 3042170754Sdelphij 3043170754SdelphijAlternatively, you can tell @command{patch} to place all of the rejected 3044170754Sdelphijpatches in a single file. The @option{-r @var{reject-file}} or 3045170754Sdelphij@option{--reject-file=@var{reject-file}} option uses @var{reject-file} as 3046170754Sdelphijthe reject file name. 3047170754Sdelphij 3048170754Sdelphij@node patch Messages 3049170754Sdelphij@section Messages and Questions from @command{patch} 3050170754Sdelphij@cindex @command{patch} messages and questions 3051170754Sdelphij@cindex diagnostics from @command{patch} 3052170754Sdelphij@cindex messages from @command{patch} 3053170754Sdelphij 3054170754Sdelphij@command{patch} can produce a variety of messages, especially if it 3055170754Sdelphijhas trouble decoding its input. In a few situations where it's not 3056170754Sdelphijsure how to proceed, @command{patch} normally prompts you for more 3057170754Sdelphijinformation from the keyboard. There are options to produce more or 3058170754Sdelphijfewer messages, to have it not ask for keyboard input, and to 3059170754Sdelphijaffect the way that file names are quoted in messages. 3060170754Sdelphij 3061170754Sdelphij@menu 3062170754Sdelphij* More or Fewer Messages:: Controlling the verbosity of @command{patch}. 3063170754Sdelphij* patch and Keyboard Input:: Inhibiting keyboard input. 3064170754Sdelphij* patch Quoting Style:: Quoting file names in diagnostics. 3065170754Sdelphij@end menu 3066170754Sdelphij 3067170754Sdelphij@command{patch} exits with status 0 if all hunks are applied successfully, 3068170754Sdelphij1 if some hunks cannot be applied, and 2 if there is more serious trouble. 3069170754SdelphijWhen applying a set of patches in a loop, you should check the 3070170754Sdelphijexit status, so you don't apply a later patch to a partially patched 3071170754Sdelphijfile. 3072170754Sdelphij 3073170754Sdelphij@node More or Fewer Messages 3074170754Sdelphij@subsection Controlling the Verbosity of @command{patch} 3075170754Sdelphij@cindex verbose messages from @command{patch} 3076170754Sdelphij@cindex inhibit messages from @command{patch} 3077170754Sdelphij 3078170754SdelphijYou can cause @command{patch} to produce more messages by using the 3079170754Sdelphij@option{--verbose} option. For example, when you give this option, 3080170754Sdelphijthe message @samp{Hmm...} indicates that @command{patch} is reading text in 3081170754Sdelphijthe patch file, attempting to determine whether there is a patch in that 3082170754Sdelphijtext, and if so, what kind of patch it is. 3083170754Sdelphij 3084170754SdelphijYou can inhibit all terminal output from @command{patch}, unless an error 3085170754Sdelphijoccurs, by using the @option{-s}, @option{--quiet}, or @option{--silent} 3086170754Sdelphijoption. 3087170754Sdelphij 3088170754Sdelphij@node patch and Keyboard Input 3089170754Sdelphij@subsection Inhibiting Keyboard Input 3090170754Sdelphij@cindex keyboard input to @command{patch} 3091170754Sdelphij 3092170754SdelphijThere are two ways you can prevent @command{patch} from asking you any 3093170754Sdelphijquestions. The @option{-f} or @option{--force} option assumes that you know 3094170754Sdelphijwhat you are doing. It causes @command{patch} to do the following: 3095170754Sdelphij 3096170754Sdelphij@itemize @bullet 3097170754Sdelphij@item 3098170754SdelphijSkip patches that do not contain file names in their headers. 3099170754Sdelphij 3100170754Sdelphij@item 3101170754SdelphijPatch files even though they have the wrong version for the 3102170754Sdelphij@samp{Prereq:} line in the patch; 3103170754Sdelphij 3104170754Sdelphij@item 3105170754SdelphijAssume that patches are not reversed even if they look like they are. 3106170754Sdelphij@end itemize 3107170754Sdelphij 3108170754Sdelphij@noindent 3109170754SdelphijThe @option{-t} or @option{--batch} option is similar to @option{-f}, in that 3110170754Sdelphijit suppresses questions, but it makes somewhat different assumptions: 3111170754Sdelphij 3112170754Sdelphij@itemize @bullet 3113170754Sdelphij@item 3114170754SdelphijSkip patches that do not contain file names in their headers 3115170754Sdelphij(the same as @option{-f}). 3116170754Sdelphij 3117170754Sdelphij@item 3118170754SdelphijSkip patches for which the file has the wrong version for the 3119170754Sdelphij@samp{Prereq:} line in the patch; 3120170754Sdelphij 3121170754Sdelphij@item 3122170754SdelphijAssume that patches are reversed if they look like they are. 3123170754Sdelphij@end itemize 3124170754Sdelphij 3125170754Sdelphij@node patch Quoting Style 3126170754Sdelphij@subsection @command{patch} Quoting Style 3127170754Sdelphij@cindex quoting style 3128170754Sdelphij 3129170754SdelphijWhen @command{patch} outputs a file name in a diagnostic message, it 3130170754Sdelphijcan format the name in any of several ways. This can be useful to 3131170754Sdelphijoutput file names unambiguously, even if they contain punctuation or 3132170754Sdelphijspecial characters like newlines. The 3133170754Sdelphij@option{--quoting-style=@var{word}} option controls how names are 3134170754Sdelphijoutput. The @var{word} should be one of the following: 3135170754Sdelphij 3136170754Sdelphij@table @samp 3137170754Sdelphij@item literal 3138170754SdelphijOutput names as-is. 3139170754Sdelphij@item shell 3140170754SdelphijQuote names for the shell if they contain shell metacharacters or would 3141170754Sdelphijcause ambiguous output. 3142170754Sdelphij@item shell-always 3143170754SdelphijQuote names for the shell, even if they would normally not require quoting. 3144170754Sdelphij@item c 3145170754SdelphijQuote names as for a C language string. 3146170754Sdelphij@item escape 3147170754SdelphijQuote as with @samp{c} except omit the surrounding double-quote 3148170754Sdelphijcharacters. 3149170754Sdelphij@c The following are not yet implemented in patch 2.5.4. 3150170754Sdelphij@c @item clocale 3151170754Sdelphij@c Quote as with @samp{c} except use quotation marks appropriate for the 3152170754Sdelphij@c locale. 3153170754Sdelphij@c @item locale 3154170754Sdelphij@c @c Use @t instead of @samp to avoid duplicate quoting in some output styles. 3155170754Sdelphij@c Like @samp{clocale}, but quote @t{`like this'} instead of @t{"like 3156170754Sdelphij@c this"} in the default C locale. This looks nicer on many displays. 3157170754Sdelphij@end table 3158170754Sdelphij 3159170754Sdelphij@vindex QUOTING_STYLE 3160170754SdelphijYou can specify the default value of the @option{--quoting-style} 3161170754Sdelphijoption with the environment variable @env{QUOTING_STYLE}. If that 3162170754Sdelphijenvironment variable is not set, the default value is @samp{shell}, 3163170754Sdelphijbut this default may change in a future version of @command{patch}. 3164170754Sdelphij 3165170754Sdelphij@node patch and POSIX 3166170754Sdelphij@section @command{patch} and the @acronym{POSIX} Standard 3167170754Sdelphij@cindex @acronym{POSIX} 3168170754Sdelphij 3169170754Sdelphij@vindex POSIXLY_CORRECT 3170170754SdelphijIf you specify the @option{--posix} option, or set the 3171170754Sdelphij@env{POSIXLY_CORRECT} environment variable, @command{patch} conforms 3172170754Sdelphijmore strictly to the @acronym{POSIX} standard, as follows: 3173170754Sdelphij 3174170754Sdelphij@itemize @bullet 3175170754Sdelphij@item 3176170754SdelphijTake the first existing file from the list (old, new, index) 3177170754Sdelphijwhen intuiting file names from diff headers. @xref{Multiple Patches}. 3178170754Sdelphij 3179170754Sdelphij@item 3180170754SdelphijDo not remove files that are removed by a diff. 3181170754Sdelphij@xref{Creating and Removing}. 3182170754Sdelphij 3183170754Sdelphij@item 3184170754SdelphijDo not ask whether to get files from @acronym{RCS}, ClearCase, or 3185170754Sdelphij@acronym{SCCS}. @xref{Revision Control}. 3186170754Sdelphij 3187170754Sdelphij@item 3188170754SdelphijRequire that all options precede the files in the command line. 3189170754Sdelphij 3190170754Sdelphij@item 3191170754SdelphijDo not backup files, even when there is a mismatch. @xref{Backups}. 3192170754Sdelphij 3193170754Sdelphij@end itemize 3194170754Sdelphij 3195170754Sdelphij@node patch and Tradition 3196170754Sdelphij@section @acronym{GNU} @command{patch} and Traditional @command{patch} 3197170754Sdelphij@cindex traditional @command{patch} 3198170754Sdelphij 3199170754SdelphijThe current version of @acronym{GNU} @command{patch} normally follows the 3200170754Sdelphij@acronym{POSIX} standard. @xref{patch and POSIX}, for the few exceptions 3201170754Sdelphijto this general rule. 3202170754Sdelphij 3203170754SdelphijUnfortunately, @acronym{POSIX} redefined the behavior of @command{patch} in 3204170754Sdelphijseveral important ways. You should be aware of the following 3205170754Sdelphijdifferences if you must interoperate with traditional @command{patch}, 3206170754Sdelphijor with @acronym{GNU} @command{patch} version 2.1 and earlier. 3207170754Sdelphij 3208170754Sdelphij@itemize @bullet 3209170754Sdelphij@item 3210170754SdelphijIn traditional @command{patch}, the @option{-p} option's operand was 3211170754Sdelphijoptional, and a bare @option{-p} was equivalent to @option{-p0}. The 3212170754Sdelphij@option{-p} option now requires an operand, and @option{-p@ 0} is now 3213170754Sdelphijequivalent to @option{-p0}. For maximum compatibility, use options 3214170754Sdelphijlike @option{-p0} and @option{-p1}. 3215170754Sdelphij 3216170754SdelphijAlso, traditional @command{patch} simply counted slashes when 3217170754Sdelphijstripping path prefixes; @command{patch} now counts pathname 3218170754Sdelphijcomponents. That is, a sequence of one or more adjacent slashes now 3219170754Sdelphijcounts as a single slash. For maximum portability, avoid sending 3220170754Sdelphijpatches containing @file{//} in file names. 3221170754Sdelphij 3222170754Sdelphij@item 3223170754SdelphijIn traditional @command{patch}, backups were enabled by default. This 3224170754Sdelphijbehavior is now enabled with the @option{-b} or @option{--backup} 3225170754Sdelphijoption. 3226170754Sdelphij 3227170754SdelphijConversely, in @acronym{POSIX} @command{patch}, backups are never made, 3228170754Sdelphijeven when there is a mismatch. In @acronym{GNU} @command{patch}, this 3229170754Sdelphijbehavior is enabled with the @option{--no-backup-if-mismatch} option, 3230170754Sdelphijor by conforming to @acronym{POSIX}. 3231170754Sdelphij 3232170754SdelphijThe @option{-b@ @var{suffix}} option of traditional @command{patch} is 3233170754Sdelphijequivalent to the @samp{-b -z@ @var{suffix}} options of @acronym{GNU} 3234170754Sdelphij@command{patch}. 3235170754Sdelphij 3236170754Sdelphij@item 3237170754SdelphijTraditional @command{patch} used a complicated (and incompletely 3238170754Sdelphijdocumented) method to intuit the name of the file to be patched from 3239170754Sdelphijthe patch header. This method did not conform to @acronym{POSIX}, and had 3240170754Sdelphija few gotchas. Now @command{patch} uses a different, equally 3241170754Sdelphijcomplicated (but better documented) method that is optionally 3242170754Sdelphij@acronym{POSIX}-conforming; we hope it has fewer gotchas. The two methods 3243170754Sdelphijare compatible if the file names in the context diff header and the 3244170754Sdelphij@samp{Index:} line are all identical after prefix-stripping. Your 3245170754Sdelphijpatch is normally compatible if each header's file names all contain 3246170754Sdelphijthe same number of slashes. 3247170754Sdelphij 3248170754Sdelphij@item 3249170754SdelphijWhen traditional @command{patch} asked the user a question, it sent 3250170754Sdelphijthe question to standard error and looked for an answer from the first 3251170754Sdelphijfile in the following list that was a terminal: standard error, 3252170754Sdelphijstandard output, @file{/dev/tty}, and standard input. Now 3253170754Sdelphij@command{patch} sends questions to standard output and gets answers 3254170754Sdelphijfrom @file{/dev/tty}. Defaults for some answers have been changed so 3255170754Sdelphijthat @command{patch} never goes into an infinite loop when using 3256170754Sdelphijdefault answers. 3257170754Sdelphij 3258170754Sdelphij@item 3259170754SdelphijTraditional @command{patch} exited with a status value that counted 3260170754Sdelphijthe number of bad hunks, or with status 1 if there was real trouble. 3261170754SdelphijNow @command{patch} exits with status 1 if some hunks failed, or with 3262170754Sdelphij2 if there was real trouble. 3263170754Sdelphij 3264170754Sdelphij@item 3265170754SdelphijLimit yourself to the following options when sending instructions 3266170754Sdelphijmeant to be executed by anyone running @acronym{GNU} @command{patch}, 3267170754Sdelphijtraditional @command{patch}, or a @command{patch} that conforms to 3268170754Sdelphij@acronym{POSIX}. Spaces are significant in the following list, and 3269170754Sdelphijoperands are required. 3270170754Sdelphij 3271170754Sdelphij@example 3272170754Sdelphij@option{-c} 3273170754Sdelphij@option{-d @var{dir}} 3274170754Sdelphij@option{-D @var{define}} 3275170754Sdelphij@option{-e} 3276170754Sdelphij@option{-l} 3277170754Sdelphij@option{-n} 3278170754Sdelphij@option{-N} 3279170754Sdelphij@option{-o @var{outfile}} 3280170754Sdelphij@option{-p@var{num}} 3281170754Sdelphij@option{-R} 3282170754Sdelphij@option{-r @var{rejectfile}} 3283170754Sdelphij@end example 3284170754Sdelphij 3285170754Sdelphij@end itemize 3286170754Sdelphij 3287170754Sdelphij@node Making Patches 3288170754Sdelphij@chapter Tips for Making and Using Patches 3289170754Sdelphij 3290170754SdelphijUse some common sense when making and using patches. For example, 3291170754Sdelphijwhen sending bug fixes to a program's maintainer, send several small 3292170754Sdelphijpatches, one per independent subject, instead of one large, 3293170754Sdelphijharder-to-digest patch that covers all the subjects. 3294170754Sdelphij 3295170754SdelphijHere are some other things you should keep in mind if you are going to 3296170754Sdelphijdistribute patches for updating a software package. 3297170754Sdelphij 3298170754Sdelphij@menu 3299170754Sdelphij* Tips for Patch Producers:: Advice for making patches. 3300170754Sdelphij* Tips for Patch Consumers:: Advice for using patches. 3301170754Sdelphij* Avoiding Common Mistakes:: Avoiding common mistakes when using @command{patch}. 3302170754Sdelphij* Generating Smaller Patches:: How to generate smaller patches. 3303170754Sdelphij@end menu 3304170754Sdelphij 3305170754Sdelphij@node Tips for Patch Producers 3306170754Sdelphij@section Tips for Patch Producers 3307170754Sdelphij@cindex patch producer tips 3308170754Sdelphij 3309170754SdelphijTo create a patch that changes an older version of a package into a 3310170754Sdelphijnewer version, first make a copy of the older and newer versions in 3311170754Sdelphijadjacent subdirectories. It is common to do that by unpacking 3312170754Sdelphij@command{tar} archives of the two versions. 3313170754Sdelphij 3314170754SdelphijTo generate the patch, use the command @samp{diff -Naur @var{old} 3315170754Sdelphij@var{new}} where @var{old} and @var{new} identify the old and new 3316170754Sdelphijdirectories. The names @var{old} and @var{new} should not contain any 3317170754Sdelphijslashes. The @option{-N} option lets the patch create and remove 3318170754Sdelphijfiles; @option{-a} lets the patch update non-text files; @option{-u} 3319170754Sdelphijgenerates useful time stamps and enough context; and @option{-r} lets 3320170754Sdelphijthe patch update subdirectories. Here is an example command, using 3321170754SdelphijBourne shell syntax: 3322170754Sdelphij 3323170754Sdelphij@example 3324170754Sdelphijdiff -Naur gcc-3.0.3 gcc-3.0.4 3325170754Sdelphij@end example 3326170754Sdelphij 3327170754SdelphijTell your recipients how to apply the patches. This should include 3328170754Sdelphijwhich working directory to use, and which @command{patch} options to 3329170754Sdelphijuse; the option @samp{-p1} is recommended. Test your procedure by 3330170754Sdelphijpretending to be a recipient and applying your patches to a copy of 3331170754Sdelphijthe original files. 3332170754Sdelphij 3333170754Sdelphij@xref{Avoiding Common Mistakes}, for how to avoid common mistakes when 3334170754Sdelphijgenerating a patch. 3335170754Sdelphij 3336170754Sdelphij@node Tips for Patch Consumers 3337170754Sdelphij@section Tips for Patch Consumers 3338170754Sdelphij@cindex patch consumer tips 3339170754Sdelphij 3340170754SdelphijA patch producer should tell recipients how to apply the patches, so 3341170754Sdelphijthe first rule of thumb for a patch consumer is to follow the 3342170754Sdelphijinstructions supplied with the patch. 3343170754Sdelphij 3344170754Sdelphij@acronym{GNU} @command{diff} can analyze files with arbitrarily long lines 3345170754Sdelphijand files that end in incomplete lines. However, older versions of 3346170754Sdelphij@command{patch} cannot patch such files. If you are having trouble 3347170754Sdelphijapplying such patches, try upgrading to a recent version of @acronym{GNU} 3348170754Sdelphij@command{patch}. 3349170754Sdelphij 3350170754Sdelphij@node Avoiding Common Mistakes 3351170754Sdelphij@section Avoiding Common Mistakes 3352170754Sdelphij@cindex common mistakes with patches 3353170754Sdelphij@cindex patch, common mistakes 3354170754Sdelphij 3355170754SdelphijWhen producing a patch for multiple files, apply @command{diff} to 3356170754Sdelphijdirectories whose names do not have slashes. This reduces confusion 3357170754Sdelphijwhen the patch consumer specifies the @option{-p@var{number}} option, 3358170754Sdelphijsince this option can have surprising results when the old and new 3359170754Sdelphijfile names have different numbers of slashes. For example, do not 3360170754Sdelphijsend a patch with a header that looks like this: 3361170754Sdelphij 3362170754Sdelphij@example 3363170754Sdelphijdiff -Naur v2.0.29/prog/README prog/README 3364170754Sdelphij--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 3365170754Sdelphij+++ prog/README 2002-03-17 20:49:32.442260588 -0800 3366170754Sdelphij@end example 3367170754Sdelphij 3368170754Sdelphij@noindent 3369170754Sdelphijbecause the two file names have different numbers of slashes, and 3370170754Sdelphijdifferent versions of @command{patch} interpret the file names 3371170754Sdelphijdifferently. To avoid confusion, send output that looks like this 3372170754Sdelphijinstead: 3373170754Sdelphij 3374170754Sdelphij@example 3375170754Sdelphijdiff -Naur v2.0.29/prog/README v2.0.30/prog/README 3376170754Sdelphij--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 3377170754Sdelphij+++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800 3378170754Sdelphij@end example 3379170754Sdelphij 3380170754SdelphijMake sure you have specified the file names correctly, either in a 3381170754Sdelphijcontext diff header or with an @samp{Index:} line. Take care to not send out 3382170754Sdelphijreversed patches, since these make people wonder whether they have 3383170754Sdelphijalready applied the patch. 3384170754Sdelphij 3385170754SdelphijAvoid sending patches that compare backup file names like 3386170754Sdelphij@file{README.orig} or @file{README~}, since this might confuse 3387170754Sdelphij@command{patch} into patching a backup file instead of the real file. 3388170754SdelphijInstead, send patches that compare the same base file names in 3389170754Sdelphijdifferent directories, e.g.@: @file{old/README} and @file{new/README}. 3390170754Sdelphij 3391170754SdelphijTo save people from partially applying a patch before other patches that 3392170754Sdelphijshould have gone before it, you can make the first patch in the patch 3393170754Sdelphijfile update a file with a name like @file{patchlevel.h} or 3394170754Sdelphij@file{version.c}, which contains a patch level or version number. If 3395170754Sdelphijthe input file contains the wrong version number, @command{patch} will 3396170754Sdelphijcomplain immediately. 3397170754Sdelphij 3398170754SdelphijAn even clearer way to prevent this problem is to put a @samp{Prereq:} 3399170754Sdelphijline before the patch. If the leading text in the patch file contains a 3400170754Sdelphijline that starts with @samp{Prereq:}, @command{patch} takes the next word 3401170754Sdelphijfrom that line (normally a version number) and checks whether the next 3402170754Sdelphijinput file contains that word, preceded and followed by either 3403170754Sdelphijwhite space or a newline. If not, @command{patch} prompts you for 3404170754Sdelphijconfirmation before proceeding. This makes it difficult to accidentally 3405170754Sdelphijapply patches in the wrong order. 3406170754Sdelphij 3407170754Sdelphij@node Generating Smaller Patches 3408170754Sdelphij@section Generating Smaller Patches 3409170754Sdelphij@cindex patches, shrinking 3410170754Sdelphij 3411170754SdelphijThe simplest way to generate a patch is to use @samp{diff -Naur} 3412170754Sdelphij(@pxref{Tips for Patch Producers}), but you might be able to reduce 3413170754Sdelphijthe size of the patch by renaming or removing some files before making 3414170754Sdelphijthe patch. If the older version of the package contains any files 3415170754Sdelphijthat the newer version does not, or if any files have been renamed 3416170754Sdelphijbetween the two versions, make a list of @command{rm} and @command{mv} 3417170754Sdelphijcommands for the user to execute in the old version directory before 3418170754Sdelphijapplying the patch. Then run those commands yourself in the scratch 3419170754Sdelphijdirectory. 3420170754Sdelphij 3421170754SdelphijIf there are any files that you don't need to include in the patch 3422170754Sdelphijbecause they can easily be rebuilt from other files (for example, 3423170754Sdelphij@file{TAGS} and output from @command{yacc} and @command{makeinfo}), 3424170754Sdelphijexclude them from the patch by giving @command{diff} the @option{-x 3425170754Sdelphij@var{pattern}} option (@pxref{Comparing Directories}). If you want 3426170754Sdelphijyour patch to modify a derived file because your recipients lack tools 3427170754Sdelphijto build it, make sure that the patch for the derived file follows any 3428170754Sdelphijpatches for files that it depends on, so that the recipients' time 3429170754Sdelphijstamps will not confuse @command{make}. 3430170754Sdelphij 3431170754SdelphijNow you can create the patch using @samp{diff -Naur}. Make sure to 3432170754Sdelphijspecify the scratch directory first and the newer directory second. 3433170754Sdelphij 3434170754SdelphijAdd to the top of the patch a note telling the user any @command{rm} and 3435170754Sdelphij@command{mv} commands to run before applying the patch. Then you can 3436170754Sdelphijremove the scratch directory. 3437170754Sdelphij 3438170754SdelphijYou can also shrink the patch size by using fewer lines of context, 3439170754Sdelphijbut bear in mind that @command{patch} typically needs at least two 3440170754Sdelphijlines for proper operation when patches do not exactly match the input 3441170754Sdelphijfiles. 3442170754Sdelphij 3443170754Sdelphij@node Invoking cmp 3444170754Sdelphij@chapter Invoking @command{cmp} 3445170754Sdelphij@cindex invoking @command{cmp} 3446170754Sdelphij@cindex @command{cmp} invocation 3447170754Sdelphij 3448170754SdelphijThe @command{cmp} command compares two files, and if they differ, 3449170754Sdelphijtells the first byte and line number where they differ or reports 3450170754Sdelphijthat one file is a prefix of the other. Bytes and 3451170754Sdelphijlines are numbered starting with 1. The arguments of @command{cmp} 3452170754Sdelphijare as follows: 3453170754Sdelphij 3454170754Sdelphij@example 3455170754Sdelphijcmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file} @r{[}@var{from-skip} @r{[}@var{to-skip}@r{]}@r{]}@r{]} 3456170754Sdelphij@end example 3457170754Sdelphij 3458170754SdelphijThe file name @file{-} is always the standard input. @command{cmp} 3459170754Sdelphijalso uses the standard input if one file name is omitted. The 3460170754Sdelphij@var{from-skip} and @var{to-skip} operands specify how many bytes to 3461170754Sdelphijignore at the start of each file; they are equivalent to the 3462170754Sdelphij@option{--ignore-initial=@var{from-skip}:@var{to-skip}} option. 3463170754Sdelphij 3464170754SdelphijBy default, @command{cmp} outputs nothing if the two files have the 3465170754Sdelphijsame contents. If one file is a prefix of the other, @command{cmp} 3466170754Sdelphijprints to standard error a message of the following form: 3467170754Sdelphij 3468170754Sdelphij@example 3469170754Sdelphijcmp: EOF on @var{shorter-file} 3470170754Sdelphij@end example 3471170754Sdelphij 3472170754SdelphijOtherwise, @command{cmp} prints to standard output a message of the 3473170754Sdelphijfollowing form: 3474170754Sdelphij 3475170754Sdelphij@example 3476170754Sdelphij@var{from-file} @var{to-file} differ: char @var{byte-number}, line @var{line-number} 3477170754Sdelphij@end example 3478170754Sdelphij 3479170754SdelphijThe message formats can differ outside the @acronym{POSIX} locale. 3480170754SdelphijAlso, @acronym{POSIX} allows the @acronym{EOF} message to be followed 3481170754Sdelphijby a blank and some additional information. 3482170754Sdelphij 3483170754SdelphijAn exit status of 0 means no differences were found, 1 means some 3484170754Sdelphijdifferences were found, and 2 means trouble. 3485170754Sdelphij 3486170754Sdelphij@menu 3487170754Sdelphij* cmp Options:: Summary of options to @command{cmp}. 3488170754Sdelphij@end menu 3489170754Sdelphij 3490170754Sdelphij@node cmp Options 3491170754Sdelphij@section Options to @command{cmp} 3492170754Sdelphij@cindex @command{cmp} options 3493170754Sdelphij@cindex options for @command{cmp} 3494170754Sdelphij 3495170754SdelphijBelow is a summary of all of the options that @acronym{GNU} 3496170754Sdelphij@command{cmp} accepts. Most options have two equivalent names, one of 3497170754Sdelphijwhich is a single letter preceded by @samp{-}, and the other of which 3498170754Sdelphijis a long name preceded by @samp{--}. Multiple single letter options 3499170754Sdelphij(unless they take an argument) can be combined into a single command 3500170754Sdelphijline word: @option{-bl} is equivalent to @option{-b -l}. 3501170754Sdelphij 3502170754Sdelphij@table @option 3503170754Sdelphij@item -b 3504170754Sdelphij@itemx --print-bytes 3505170754SdelphijPrint the differing bytes. Display control bytes as a 3506170754Sdelphij@samp{^} followed by a letter of the alphabet and precede bytes 3507170754Sdelphijthat have the high bit set with @samp{M-} (which stands for ``meta''). 3508170754Sdelphij 3509170754Sdelphij@item --help 3510170754SdelphijOutput a summary of usage and then exit. 3511170754Sdelphij 3512170754Sdelphij@item -i @var{skip} 3513170754Sdelphij@itemx --ignore-initial=@var{skip} 3514170754SdelphijIgnore any differences in the first @var{skip} bytes of the input 3515170754Sdelphijfiles. Treat files with fewer than @var{skip} bytes as if they are 3516170754Sdelphijempty. If @var{skip} is of the form 3517170754Sdelphij@option{@var{from-skip}:@var{to-skip}}, skip the first @var{from-skip} 3518170754Sdelphijbytes of the first input file and the first @var{to-skip} bytes of the 3519170754Sdelphijsecond. 3520170754Sdelphij 3521170754Sdelphij@item -l 3522170754Sdelphij@itemx --verbose 3523170754SdelphijOutput the (decimal) byte numbers and (octal) values of all differing bytes, 3524170754Sdelphijinstead of the default standard output. 3525170754Sdelphij 3526170754Sdelphij@item -n @var{count} 3527170754Sdelphij@itemx --bytes=@var{count} 3528170754SdelphijCompare at most @var{count} input bytes. 3529170754Sdelphij 3530170754Sdelphij@item -s 3531170754Sdelphij@itemx --quiet 3532170754Sdelphij@itemx --silent 3533170754SdelphijDo not print anything; only return an exit status indicating whether 3534170754Sdelphijthe files differ. 3535170754Sdelphij 3536170754Sdelphij@item -v 3537170754Sdelphij@itemx --version 3538170754SdelphijOutput version information and then exit. 3539170754Sdelphij@end table 3540170754Sdelphij 3541170754SdelphijIn the above table, operands that are byte counts are normally 3542170754Sdelphijdecimal, but may be preceded by @samp{0} for octal and @samp{0x} for 3543170754Sdelphijhexadecimal. 3544170754Sdelphij 3545170754SdelphijA byte count can be followed by a suffix to specify a multiple of that 3546170754Sdelphijcount; in this case an omitted integer is understood to be 1. A bare 3547170754Sdelphijsize letter, or one followed by @samp{iB}, specifies a multiple using 3548170754Sdelphijpowers of 1024. A size letter followed by @samp{B} specifies powers 3549170754Sdelphijof 1000 instead. For example, @option{-n 4M} and @option{-n 4MiB} are 3550170754Sdelphijequivalent to @option{-n 4194304}, whereas @option{-n 4MB} is 3551170754Sdelphijequivalent to @option{-n 4000000}. This notation is upward compatible 3552170754Sdelphijwith the @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI 3553170754Sdelphijprefixes} for decimal multiples and with the 3554170754Sdelphij@uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2 3555170754Sdelphijprefixes for binary multiples}. 3556170754Sdelphij 3557170754SdelphijThe following suffixes are defined. Large sizes like @code{1Y} may be 3558170754Sdelphijrejected by your computer due to limitations of its arithmetic. 3559170754Sdelphij 3560170754Sdelphij@table @samp 3561170754Sdelphij@item kB 3562170754Sdelphij@cindex kilobyte, definition of 3563170754Sdelphijkilobyte: @math{10^3 = 1000}. 3564170754Sdelphij@item k 3565170754Sdelphij@itemx K 3566170754Sdelphij@itemx KiB 3567170754Sdelphij@cindex kibibyte, definition of 3568170754Sdelphijkibibyte: @math{2^10 = 1024}. @samp{K} is special: the SI prefix is 3569170754Sdelphij@samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and 3570170754Sdelphij@acronym{POSIX} use @samp{k} to mean @samp{KiB}. 3571170754Sdelphij@item MB 3572170754Sdelphij@cindex megabyte, definition of 3573170754Sdelphijmegabyte: @math{10^6 = 1,000,000}. 3574170754Sdelphij@item M 3575170754Sdelphij@itemx MiB 3576170754Sdelphij@cindex mebibyte, definition of 3577170754Sdelphijmebibyte: @math{2^20 = 1,048,576}. 3578170754Sdelphij@item GB 3579170754Sdelphij@cindex gigabyte, definition of 3580170754Sdelphijgigabyte: @math{10^9 = 1,000,000,000}. 3581170754Sdelphij@item G 3582170754Sdelphij@itemx GiB 3583170754Sdelphij@cindex gibibyte, definition of 3584170754Sdelphijgibibyte: @math{2^30 = 1,073,741,824}. 3585170754Sdelphij@item TB 3586170754Sdelphij@cindex terabyte, definition of 3587170754Sdelphijterabyte: @math{10^12 = 1,000,000,000,000}. 3588170754Sdelphij@item T 3589170754Sdelphij@itemx TiB 3590170754Sdelphij@cindex tebibyte, definition of 3591170754Sdelphijtebibyte: @math{2^40 = 1,099,511,627,776}. 3592170754Sdelphij@item PB 3593170754Sdelphij@cindex petabyte, definition of 3594170754Sdelphijpetabyte: @math{10^15 = 1,000,000,000,000,000}. 3595170754Sdelphij@item P 3596170754Sdelphij@itemx PiB 3597170754Sdelphij@cindex pebibyte, definition of 3598170754Sdelphijpebibyte: @math{2^50 = 1,125,899,906,842,624}. 3599170754Sdelphij@item EB 3600170754Sdelphij@cindex exabyte, definition of 3601170754Sdelphijexabyte: @math{10^18 = 1,000,000,000,000,000,000}. 3602170754Sdelphij@item E 3603170754Sdelphij@itemx EiB 3604170754Sdelphij@cindex exbibyte, definition of 3605170754Sdelphijexbibyte: @math{2^60 = 1,152,921,504,606,846,976}. 3606170754Sdelphij@item ZB 3607170754Sdelphij@cindex zettabyte, definition of 3608170754Sdelphijzettabyte: @math{10^21 = 1,000,000,000,000,000,000,000} 3609170754Sdelphij@item Z 3610170754Sdelphij@itemx ZiB 3611170754Sdelphij@math{2^70 = 1,180,591,620,717,411,303,424}. 3612170754Sdelphij(@samp{Zi} is a GNU extension to IEC 60027-2.) 3613170754Sdelphij@item YB 3614170754Sdelphij@cindex yottabyte, definition of 3615170754Sdelphijyottabyte: @math{10^24 = 1,000,000,000,000,000,000,000,000}. 3616170754Sdelphij@item Y 3617170754Sdelphij@itemx YiB 3618170754Sdelphij@math{2^80 = 1,208,925,819,614,629,174,706,176}. 3619170754Sdelphij(@samp{Yi} is a GNU extension to IEC 60027-2.) 3620170754Sdelphij@end table 3621170754Sdelphij 3622170754Sdelphij@node Invoking diff 3623170754Sdelphij@chapter Invoking @command{diff} 3624170754Sdelphij@cindex invoking @command{diff} 3625170754Sdelphij@cindex @command{diff} invocation 3626170754Sdelphij 3627170754SdelphijThe format for running the @command{diff} command is: 3628170754Sdelphij 3629170754Sdelphij@example 3630170754Sdelphijdiff @var{options}@dots{} @var{files}@dots{} 3631170754Sdelphij@end example 3632170754Sdelphij 3633170754SdelphijIn the simplest case, two file names @var{from-file} and 3634170754Sdelphij@var{to-file} are given, and @command{diff} compares the contents of 3635170754Sdelphij@var{from-file} and @var{to-file}. A file name of @file{-} stands for 3636170754Sdelphijtext read from the standard input. As a special case, @samp{diff - -} 3637170754Sdelphijcompares a copy of standard input to itself. 3638170754Sdelphij 3639170754SdelphijIf one file is a directory and the other is not, @command{diff} compares 3640170754Sdelphijthe file in the directory whose name is that of the non-directory. 3641170754SdelphijThe non-directory file must not be @file{-}. 3642170754Sdelphij 3643170754SdelphijIf two file names are given and both are directories, 3644170754Sdelphij@command{diff} compares corresponding files in both directories, in 3645170754Sdelphijalphabetical order; this comparison is not recursive unless the 3646170754Sdelphij@option{-r} or @option{--recursive} option is given. @command{diff} never 3647170754Sdelphijcompares the actual contents of a directory as if it were a file. The 3648170754Sdelphijfile that is fully specified may not be standard input, because standard 3649170754Sdelphijinput is nameless and the notion of ``file with the same name'' does not 3650170754Sdelphijapply. 3651170754Sdelphij 3652170754SdelphijIf the @option{--from-file=@var{file}} option is given, the number of 3653170754Sdelphijfile names is arbitrary, and @var{file} is compared to each named file. 3654170754SdelphijSimilarly, if the @option{--to-file=@var{file}} option is given, each 3655170754Sdelphijnamed file is compared to @var{file}. 3656170754Sdelphij 3657170754Sdelphij@command{diff} options begin with @samp{-}, so normally file names 3658170754Sdelphijmay not begin with @samp{-}. However, @option{--} as an 3659170754Sdelphijargument by itself treats the remaining arguments as file names even if 3660170754Sdelphijthey begin with @samp{-}. 3661170754Sdelphij 3662170754SdelphijAn exit status of 0 means no differences were found, 1 means some 3663170754Sdelphijdifferences were found, and 2 means trouble. Normally, differing 3664170754Sdelphijbinary files count as trouble, but this can be altered by using the 3665170754Sdelphij@option{-a} or @option{--text} option, or the @option{-q} or 3666170754Sdelphij@option{--brief} option. 3667170754Sdelphij 3668170754Sdelphij@menu 3669170754Sdelphij* diff Options:: Summary of options to @command{diff}. 3670170754Sdelphij@end menu 3671170754Sdelphij 3672170754Sdelphij@node diff Options 3673170754Sdelphij@section Options to @command{diff} 3674170754Sdelphij@cindex @command{diff} options 3675170754Sdelphij@cindex options for @command{diff} 3676170754Sdelphij 3677170754SdelphijBelow is a summary of all of the options that @acronym{GNU} 3678170754Sdelphij@command{diff} accepts. Most options have two equivalent names, one 3679170754Sdelphijof which is a single letter preceded by @samp{-}, and the other of 3680170754Sdelphijwhich is a long name preceded by @samp{--}. Multiple single letter 3681170754Sdelphijoptions (unless they take an argument) can be combined into a single 3682170754Sdelphijcommand line word: @option{-ac} is equivalent to @option{-a -c}. Long 3683170754Sdelphijnamed options can be abbreviated to any unique prefix of their name. 3684170754SdelphijBrackets ([ and ]) indicate that an option takes an optional argument. 3685170754Sdelphij 3686170754Sdelphij@table @option 3687170754Sdelphij@item -a 3688170754Sdelphij@itemx --text 3689170754SdelphijTreat all files as text and compare them line-by-line, even if they 3690170754Sdelphijdo not seem to be text. @xref{Binary}. 3691170754Sdelphij 3692170754Sdelphij@item -b 3693170754Sdelphij@itemx --ignore-space-change 3694170754SdelphijIgnore changes in amount of white space. @xref{White Space}. 3695170754Sdelphij 3696170754Sdelphij@item -B 3697170754Sdelphij@itemx --ignore-blank-lines 3698170754SdelphijIgnore changes that just insert or delete blank lines. @xref{Blank 3699170754SdelphijLines}. 3700170754Sdelphij 3701170754Sdelphij@item --binary 3702170754SdelphijRead and write data in binary mode. @xref{Binary}. 3703170754Sdelphij 3704170754Sdelphij@item -c 3705170754SdelphijUse the context output format, showing three lines of context. 3706170754Sdelphij@xref{Context Format}. 3707170754Sdelphij 3708170754Sdelphij@item -C @var{lines} 3709170754Sdelphij@itemx --context@r{[}=@var{lines}@r{]} 3710170754SdelphijUse the context output format, showing @var{lines} (an integer) lines of 3711170754Sdelphijcontext, or three if @var{lines} is not given. @xref{Context Format}. 3712170754SdelphijFor proper operation, @command{patch} typically needs at least two lines of 3713170754Sdelphijcontext. 3714170754Sdelphij 3715170754SdelphijOn older systems, @command{diff} supports an obsolete option 3716170754Sdelphij@option{-@var{lines}} that has effect when combined with @option{-c} 3717170754Sdelphijor @option{-p}. @acronym{POSIX} 1003.1-2001 (@pxref{Standards 3718170754Sdelphijconformance}) does not allow this; use @option{-C @var{lines}} 3719170754Sdelphijinstead. 3720170754Sdelphij 3721170754Sdelphij@item --changed-group-format=@var{format} 3722170754SdelphijUse @var{format} to output a line group containing differing lines from 3723170754Sdelphijboth files in if-then-else format. @xref{Line Group Formats}. 3724170754Sdelphij 3725170754Sdelphij@item -d 3726170754Sdelphij@itemx --minimal 3727170754SdelphijChange the algorithm perhaps find a smaller set of changes. This makes 3728170754Sdelphij@command{diff} slower (sometimes much slower). @xref{diff Performance}. 3729170754Sdelphij 3730170754Sdelphij@item -D @var{name} 3731170754Sdelphij@itemx --ifdef=@var{name} 3732170754SdelphijMake merged @samp{#ifdef} format output, conditional on the preprocessor 3733170754Sdelphijmacro @var{name}. @xref{If-then-else}. 3734170754Sdelphij 3735170754Sdelphij@item -e 3736170754Sdelphij@itemx --ed 3737170754SdelphijMake output that is a valid @command{ed} script. @xref{ed Scripts}. 3738170754Sdelphij 3739170754Sdelphij@item -E 3740170754Sdelphij@itemx --ignore-tab-expansion 3741170754SdelphijIgnore changes due to tab expansion. 3742170754Sdelphij@xref{White Space}. 3743170754Sdelphij 3744170754Sdelphij@item -f 3745170754Sdelphij@itemx --forward-ed 3746170754SdelphijMake output that looks vaguely like an @command{ed} script but has changes 3747170754Sdelphijin the order they appear in the file. @xref{Forward ed}. 3748170754Sdelphij 3749170754Sdelphij@item -F @var{regexp} 3750170754Sdelphij@itemx --show-function-line=@var{regexp} 3751170754SdelphijIn context and unified format, for each hunk of differences, show some 3752170754Sdelphijof the last preceding line that matches @var{regexp}. @xref{Specified 3753170754SdelphijHeadings}. 3754170754Sdelphij 3755170754Sdelphij@item --from-file=@var{file} 3756170754SdelphijCompare @var{file} to each operand; @var{file} may be a directory. 3757170754Sdelphij 3758170754Sdelphij@item --help 3759170754SdelphijOutput a summary of usage and then exit. 3760170754Sdelphij 3761170754Sdelphij@item --horizon-lines=@var{lines} 3762170754SdelphijDo not discard the last @var{lines} lines of the common prefix 3763170754Sdelphijand the first @var{lines} lines of the common suffix. 3764170754Sdelphij@xref{diff Performance}. 3765170754Sdelphij 3766170754Sdelphij@item -i 3767170754Sdelphij@itemx --ignore-case 3768170754SdelphijIgnore changes in case; consider upper- and lower-case letters 3769170754Sdelphijequivalent. @xref{Case Folding}. 3770170754Sdelphij 3771170754Sdelphij@item -I @var{regexp} 3772170754Sdelphij@itemx --ignore-matching-lines=@var{regexp} 3773170754SdelphijIgnore changes that just insert or delete lines that match @var{regexp}. 3774170754Sdelphij@xref{Specified Lines}. 3775170754Sdelphij 3776170754Sdelphij@item --ignore-file-name-case 3777170754SdelphijIgnore case when comparing file names during recursive comparison. 3778170754Sdelphij@xref{Comparing Directories}. 3779170754Sdelphij 3780170754Sdelphij@item -l 3781170754Sdelphij@itemx --paginate 3782170754SdelphijPass the output through @command{pr} to paginate it. @xref{Pagination}. 3783170754Sdelphij 3784170754Sdelphij@item --label=@var{label} 3785170754SdelphijUse @var{label} instead of the file name in the context format 3786170754Sdelphij(@pxref{Context Format}) and unified format (@pxref{Unified Format}) 3787170754Sdelphijheaders. @xref{RCS}. 3788170754Sdelphij 3789170754Sdelphij@item --left-column 3790170754SdelphijPrint only the left column of two common lines in side by side format. 3791170754Sdelphij@xref{Side by Side Format}. 3792170754Sdelphij 3793170754Sdelphij@item --line-format=@var{format} 3794170754SdelphijUse @var{format} to output all input lines in if-then-else format. 3795170754Sdelphij@xref{Line Formats}. 3796170754Sdelphij 3797170754Sdelphij@item -n 3798170754Sdelphij@itemx --rcs 3799170754SdelphijOutput @acronym{RCS}-format diffs; like @option{-f} except that each command 3800170754Sdelphijspecifies the number of lines affected. @xref{RCS}. 3801170754Sdelphij 3802170754Sdelphij@item -N 3803170754Sdelphij@itemx --new-file 3804170754SdelphijIn directory comparison, if a file is found in only one directory, 3805170754Sdelphijtreat it as present but empty in the other directory. @xref{Comparing 3806170754SdelphijDirectories}. 3807170754Sdelphij 3808170754Sdelphij@item --new-group-format=@var{format} 3809170754SdelphijUse @var{format} to output a group of lines taken from just the second 3810170754Sdelphijfile in if-then-else format. @xref{Line Group Formats}. 3811170754Sdelphij 3812170754Sdelphij@item --new-line-format=@var{format} 3813170754SdelphijUse @var{format} to output a line taken from just the second file in 3814170754Sdelphijif-then-else format. @xref{Line Formats}. 3815170754Sdelphij 3816170754Sdelphij@item --old-group-format=@var{format} 3817170754SdelphijUse @var{format} to output a group of lines taken from just the first 3818170754Sdelphijfile in if-then-else format. @xref{Line Group Formats}. 3819170754Sdelphij 3820170754Sdelphij@item --old-line-format=@var{format} 3821170754SdelphijUse @var{format} to output a line taken from just the first file in 3822170754Sdelphijif-then-else format. @xref{Line Formats}. 3823170754Sdelphij 3824170754Sdelphij@item -p 3825170754Sdelphij@itemx --show-c-function 3826170754SdelphijShow which C function each change is in. @xref{C Function Headings}. 3827170754Sdelphij 3828170754Sdelphij@item -q 3829170754Sdelphij@itemx --brief 3830170754SdelphijReport only whether the files differ, not the details of the 3831170754Sdelphijdifferences. @xref{Brief}. 3832170754Sdelphij 3833170754Sdelphij@item -r 3834170754Sdelphij@itemx --recursive 3835170754SdelphijWhen comparing directories, recursively compare any subdirectories 3836170754Sdelphijfound. @xref{Comparing Directories}. 3837170754Sdelphij 3838170754Sdelphij@item -s 3839170754Sdelphij@itemx --report-identical-files 3840170754SdelphijReport when two files are the same. @xref{Comparing Directories}. 3841170754Sdelphij 3842170754Sdelphij@item -S @var{file} 3843170754Sdelphij@itemx --starting-file=@var{file} 3844170754SdelphijWhen comparing directories, start with the file @var{file}. This is 3845170754Sdelphijused for resuming an aborted comparison. @xref{Comparing Directories}. 3846170754Sdelphij 3847170754Sdelphij@item --speed-large-files 3848170754SdelphijUse heuristics to speed handling of large files that have numerous 3849170754Sdelphijscattered small changes. @xref{diff Performance}. 3850170754Sdelphij 3851170754Sdelphij@item --strip-trailing-cr 3852170754SdelphijStrip any trailing carriage return at the end of an input line. 3853170754Sdelphij@xref{Binary}. 3854170754Sdelphij 3855170754Sdelphij@item --suppress-common-lines 3856170754SdelphijDo not print common lines in side by side format. 3857170754Sdelphij@xref{Side by Side Format}. 3858170754Sdelphij 3859170754Sdelphij@item -t 3860170754Sdelphij@itemx --expand-tabs 3861170754SdelphijExpand tabs to spaces in the output, to preserve the alignment of tabs 3862170754Sdelphijin the input files. @xref{Tabs}. 3863170754Sdelphij 3864170754Sdelphij@item -T 3865170754Sdelphij@itemx --initial-tab 3866170754SdelphijOutput a tab rather than a space before the text of a line in normal or 3867170754Sdelphijcontext format. This causes the alignment of tabs in the line to look 3868170754Sdelphijnormal. @xref{Tabs}. 3869170754Sdelphij 3870170754Sdelphij@item --tabsize=@var{columns} 3871170754SdelphijAssume that tab stops are set every @var{columns} (default 8) print 3872170754Sdelphijcolumns. @xref{Tabs}. 3873170754Sdelphij 3874170754Sdelphij@item --to-file=@var{file} 3875170754SdelphijCompare each operand to @var{file}; @var{file} may be a directory. 3876170754Sdelphij 3877170754Sdelphij@item -u 3878170754SdelphijUse the unified output format, showing three lines of context. 3879170754Sdelphij@xref{Unified Format}. 3880170754Sdelphij 3881170754Sdelphij@item --unchanged-group-format=@var{format} 3882170754SdelphijUse @var{format} to output a group of common lines taken from both files 3883170754Sdelphijin if-then-else format. @xref{Line Group Formats}. 3884170754Sdelphij 3885170754Sdelphij@item --unchanged-line-format=@var{format} 3886170754SdelphijUse @var{format} to output a line common to both files in if-then-else 3887170754Sdelphijformat. @xref{Line Formats}. 3888170754Sdelphij 3889170754Sdelphij@item --unidirectional-new-file 3890170754SdelphijWhen comparing directories, if a file appears only in the second 3891170754Sdelphijdirectory of the two, treat it as present but empty in the other. 3892170754Sdelphij@xref{Comparing Directories}. 3893170754Sdelphij 3894170754Sdelphij@item -U @var{lines} 3895170754Sdelphij@itemx --unified@r{[}=@var{lines}@r{]} 3896170754SdelphijUse the unified output format, showing @var{lines} (an integer) lines of 3897170754Sdelphijcontext, or three if @var{lines} is not given. @xref{Unified Format}. 3898170754SdelphijFor proper operation, @command{patch} typically needs at least two lines of 3899170754Sdelphijcontext. 3900170754Sdelphij 3901170754SdelphijOn older systems, @command{diff} supports an obsolete option 3902170754Sdelphij@option{-@var{lines}} that has effect when combined with @option{-u}. 3903170754Sdelphij@acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not allow 3904170754Sdelphijthis; use @option{-U @var{lines}} instead. 3905170754Sdelphij 3906170754Sdelphij@item -v 3907170754Sdelphij@itemx --version 3908170754SdelphijOutput version information and then exit. 3909170754Sdelphij 3910170754Sdelphij@item -w 3911170754Sdelphij@itemx --ignore-all-space 3912170754SdelphijIgnore white space when comparing lines. @xref{White Space}. 3913170754Sdelphij 3914170754Sdelphij@item -W @var{columns} 3915170754Sdelphij@itemx --width=@var{columns} 3916170754SdelphijOutput at most @var{columns} (default 130) print columns per line in 3917170754Sdelphijside by side format. @xref{Side by Side Format}. 3918170754Sdelphij 3919170754Sdelphij@item -x @var{pattern} 3920170754Sdelphij@itemx --exclude=@var{pattern} 3921170754SdelphijWhen comparing directories, ignore files and subdirectories whose basenames 3922170754Sdelphijmatch @var{pattern}. @xref{Comparing Directories}. 3923170754Sdelphij 3924170754Sdelphij@item -X @var{file} 3925170754Sdelphij@itemx --exclude-from=@var{file} 3926170754SdelphijWhen comparing directories, ignore files and subdirectories whose basenames 3927170754Sdelphijmatch any pattern contained in @var{file}. @xref{Comparing Directories}. 3928170754Sdelphij 3929170754Sdelphij@item -y 3930170754Sdelphij@itemx --side-by-side 3931170754SdelphijUse the side by side output format. @xref{Side by Side Format}. 3932170754Sdelphij@end table 3933170754Sdelphij 3934170754Sdelphij@node Invoking diff3 3935170754Sdelphij@chapter Invoking @command{diff3} 3936170754Sdelphij@cindex invoking @command{diff3} 3937170754Sdelphij@cindex @command{diff3} invocation 3938170754Sdelphij 3939170754SdelphijThe @command{diff3} command compares three files and outputs descriptions 3940170754Sdelphijof their differences. Its arguments are as follows: 3941170754Sdelphij 3942170754Sdelphij@example 3943170754Sdelphijdiff3 @var{options}@dots{} @var{mine} @var{older} @var{yours} 3944170754Sdelphij@end example 3945170754Sdelphij 3946170754SdelphijThe files to compare are @var{mine}, @var{older}, and @var{yours}. 3947170754SdelphijAt most one of these three file names may be @file{-}, 3948170754Sdelphijwhich tells @command{diff3} to read the standard input for that file. 3949170754Sdelphij 3950170754SdelphijAn exit status of 0 means @command{diff3} was successful, 1 means some 3951170754Sdelphijconflicts were found, and 2 means trouble. 3952170754Sdelphij 3953170754Sdelphij@menu 3954170754Sdelphij* diff3 Options:: Summary of options to @command{diff3}. 3955170754Sdelphij@end menu 3956170754Sdelphij 3957170754Sdelphij@node diff3 Options 3958170754Sdelphij@section Options to @command{diff3} 3959170754Sdelphij@cindex @command{diff3} options 3960170754Sdelphij@cindex options for @command{diff3} 3961170754Sdelphij 3962170754SdelphijBelow is a summary of all of the options that @acronym{GNU} @command{diff3} 3963170754Sdelphijaccepts. Multiple single letter options (unless they take an argument) 3964170754Sdelphijcan be combined into a single command line argument. 3965170754Sdelphij 3966170754Sdelphij@table @option 3967170754Sdelphij@item -a 3968170754Sdelphij@itemx --text 3969170754SdelphijTreat all files as text and compare them line-by-line, even if they 3970170754Sdelphijdo not appear to be text. @xref{Binary}. 3971170754Sdelphij 3972170754Sdelphij@item -A 3973170754Sdelphij@itemx --show-all 3974170754SdelphijIncorporate all unmerged changes from @var{older} to @var{yours} into 3975170754Sdelphij@var{mine}, surrounding conflicts with bracket lines. 3976170754Sdelphij@xref{Marking Conflicts}. 3977170754Sdelphij 3978170754Sdelphij@item --diff-program=@var{program} 3979170754SdelphijUse the compatible comparison program @var{program} to compare files 3980170754Sdelphijinstead of @command{diff}. 3981170754Sdelphij 3982170754Sdelphij@item -e 3983170754Sdelphij@itemx --ed 3984170754SdelphijGenerate an @command{ed} script that incorporates all the changes from 3985170754Sdelphij@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}. 3986170754Sdelphij 3987170754Sdelphij@item -E 3988170754Sdelphij@itemx --show-overlap 3989170754SdelphijLike @option{-e}, except bracket lines from overlapping changes' first 3990170754Sdelphijand third files. 3991170754Sdelphij@xref{Marking Conflicts}. 3992170754SdelphijWith @option{-E}, an overlapping change looks like this: 3993170754Sdelphij 3994170754Sdelphij@example 3995170754Sdelphij<<<<<<< @var{mine} 3996170754Sdelphij@r{lines from @var{mine}} 3997170754Sdelphij======= 3998170754Sdelphij@r{lines from @var{yours}} 3999170754Sdelphij>>>>>>> @var{yours} 4000170754Sdelphij@end example 4001170754Sdelphij 4002170754Sdelphij@item --help 4003170754SdelphijOutput a summary of usage and then exit. 4004170754Sdelphij 4005170754Sdelphij@item -i 4006170754SdelphijGenerate @samp{w} and @samp{q} commands at the end of the @command{ed} 4007170754Sdelphijscript for System V compatibility. This option must be combined with 4008170754Sdelphijone of the @option{-AeExX3} options, and may not be combined with @option{-m}. 4009170754Sdelphij@xref{Saving the Changed File}. 4010170754Sdelphij 4011170754Sdelphij@item --label=@var{label} 4012170754SdelphijUse the label @var{label} for the brackets output by the @option{-A}, 4013170754Sdelphij@option{-E} and @option{-X} options. This option may be given up to three 4014170754Sdelphijtimes, one for each input file. The default labels are the names of 4015170754Sdelphijthe input files. Thus @samp{diff3 --label X --label Y --label Z -m A 4016170754SdelphijB C} acts like 4017170754Sdelphij@samp{diff3 -m A B C}, except that the output looks like it came from 4018170754Sdelphijfiles named @samp{X}, @samp{Y} and @samp{Z} rather than from files 4019170754Sdelphijnamed @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}. 4020170754Sdelphij 4021170754Sdelphij@item -m 4022170754Sdelphij@itemx --merge 4023170754SdelphijApply the edit script to the first file and send the result to standard 4024170754Sdelphijoutput. Unlike piping the output from @command{diff3} to @command{ed}, this 4025170754Sdelphijworks even for binary files and incomplete lines. @option{-A} is assumed 4026170754Sdelphijif no edit script option is specified. @xref{Bypassing ed}. 4027170754Sdelphij 4028170754Sdelphij@item --strip-trailing-cr 4029170754SdelphijStrip any trailing carriage return at the end of an input line. 4030170754Sdelphij@xref{Binary}. 4031170754Sdelphij 4032170754Sdelphij@item -T 4033170754Sdelphij@itemx --initial-tab 4034170754SdelphijOutput a tab rather than two spaces before the text of a line in normal format. 4035170754SdelphijThis causes the alignment of tabs in the line to look normal. @xref{Tabs}. 4036170754Sdelphij 4037170754Sdelphij@item -v 4038170754Sdelphij@itemx --version 4039170754SdelphijOutput version information and then exit. 4040170754Sdelphij 4041170754Sdelphij@item -x 4042170754Sdelphij@itemx --overlap-only 4043170754SdelphijLike @option{-e}, except output only the overlapping changes. 4044170754Sdelphij@xref{Which Changes}. 4045170754Sdelphij 4046170754Sdelphij@item -X 4047170754SdelphijLike @option{-E}, except output only the overlapping changes. 4048170754SdelphijIn other words, like @option{-x}, except bracket changes as in @option{-E}. 4049170754Sdelphij@xref{Marking Conflicts}. 4050170754Sdelphij 4051170754Sdelphij@item -3 4052170754Sdelphij@itemx --easy-only 4053170754SdelphijLike @option{-e}, except output only the nonoverlapping changes. 4054170754Sdelphij@xref{Which Changes}. 4055170754Sdelphij@end table 4056170754Sdelphij 4057170754Sdelphij@node Invoking patch 4058170754Sdelphij@chapter Invoking @command{patch} 4059170754Sdelphij@cindex invoking @command{patch} 4060170754Sdelphij@cindex @command{patch} invocation 4061170754Sdelphij 4062170754SdelphijNormally @command{patch} is invoked like this: 4063170754Sdelphij 4064170754Sdelphij@example 4065170754Sdelphijpatch <@var{patchfile} 4066170754Sdelphij@end example 4067170754Sdelphij 4068170754SdelphijThe full format for invoking @command{patch} is: 4069170754Sdelphij 4070170754Sdelphij@example 4071170754Sdelphijpatch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]} 4072170754Sdelphij@end example 4073170754Sdelphij 4074170754SdelphijYou can also specify where to read the patch from with the @option{-i 4075170754Sdelphij@var{patchfile}} or @option{--input=@var{patchfile}} option. 4076170754SdelphijIf you do not specify @var{patchfile}, or if @var{patchfile} is 4077170754Sdelphij@file{-}, @command{patch} reads the patch (that is, the @command{diff} output) 4078170754Sdelphijfrom the standard input. 4079170754Sdelphij 4080170754SdelphijIf you do not specify an input file on the command line, @command{patch} 4081170754Sdelphijtries to intuit from the @dfn{leading text} (any text in the patch 4082170754Sdelphijthat comes before the @command{diff} output) which file to edit. 4083170754Sdelphij@xref{Multiple Patches}. 4084170754Sdelphij 4085170754SdelphijBy default, @command{patch} replaces the original input file with the 4086170754Sdelphijpatched version, possibly after renaming the original file into a 4087170754Sdelphijbackup file (@pxref{Backup Names}, for a description of how 4088170754Sdelphij@command{patch} names backup files). You can also specify where to 4089170754Sdelphijput the output with the @option{-o @var{file}} or 4090170754Sdelphij@option{--output=@var{file}} option; however, do not use this option 4091170754Sdelphijif @var{file} is one of the input files. 4092170754Sdelphij 4093170754Sdelphij@menu 4094170754Sdelphij* patch Options:: Summary table of options to @command{patch}. 4095170754Sdelphij@end menu 4096170754Sdelphij 4097170754Sdelphij@node patch Options 4098170754Sdelphij@section Options to @command{patch} 4099170754Sdelphij@cindex @command{patch} options 4100170754Sdelphij@cindex options for @command{patch} 4101170754Sdelphij 4102170754SdelphijHere is a summary of all of the options that @acronym{GNU} @command{patch} 4103170754Sdelphijaccepts. @xref{patch and Tradition}, for which of these options are 4104170754Sdelphijsafe to use in older versions of @command{patch}. 4105170754Sdelphij 4106170754SdelphijMultiple single-letter options that do not take an argument can be 4107170754Sdelphijcombined into a single command line argument with only one dash. 4108170754Sdelphij 4109170754Sdelphij@table @option 4110170754Sdelphij@item -b 4111170754Sdelphij@itemx --backup 4112170754SdelphijBack up the original contents of each file, even if backups would 4113170754Sdelphijnormally not be made. @xref{Backups}. 4114170754Sdelphij 4115170754Sdelphij@item -B @var{prefix} 4116170754Sdelphij@itemx --prefix=@var{prefix} 4117170754SdelphijPrepend @var{prefix} to backup file names. @xref{Backup Names}. 4118170754Sdelphij 4119170754Sdelphij@item --backup-if-mismatch 4120170754SdelphijBack up the original contents of each file if the patch does not 4121170754Sdelphijexactly match the file. This is the default behavior when not 4122170754Sdelphijconforming to @acronym{POSIX}. @xref{Backups}. 4123170754Sdelphij 4124170754Sdelphij@item --binary 4125170754SdelphijRead and write all files in binary mode, except for standard output 4126170754Sdelphijand @file{/dev/tty}. This option has no effect on 4127170754Sdelphij@acronym{POSIX}-conforming systems like @acronym{GNU}/Linux. On systems where 4128170754Sdelphijthis option makes a difference, the patch should be generated by 4129170754Sdelphij@samp{diff -a --binary}. @xref{Binary}. 4130170754Sdelphij 4131170754Sdelphij@item -c 4132170754Sdelphij@itemx --context 4133170754SdelphijInterpret the patch file as a context diff. @xref{patch Input}. 4134170754Sdelphij 4135170754Sdelphij@item -d @var{directory} 4136170754Sdelphij@itemx --directory=@var{directory} 4137170754SdelphijMake directory @var{directory} the current directory for interpreting 4138170754Sdelphijboth file names in the patch file, and file names given as arguments to 4139170754Sdelphijother options. @xref{patch Directories}. 4140170754Sdelphij 4141170754Sdelphij@item -D @var{name} 4142170754Sdelphij@itemx --ifdef=@var{name} 4143170754SdelphijMake merged if-then-else output using @var{name}. @xref{If-then-else}. 4144170754Sdelphij 4145170754Sdelphij@item --dry-run 4146170754SdelphijPrint the results of applying the patches without actually changing 4147170754Sdelphijany files. @xref{Dry Runs}. 4148170754Sdelphij 4149170754Sdelphij@item -e 4150170754Sdelphij@itemx --ed 4151170754SdelphijInterpret the patch file as an @command{ed} script. @xref{patch Input}. 4152170754Sdelphij 4153170754Sdelphij@item -E 4154170754Sdelphij@itemx --remove-empty-files 4155170754SdelphijRemove output files that are empty after the patches have been applied. 4156170754Sdelphij@xref{Creating and Removing}. 4157170754Sdelphij 4158170754Sdelphij@item -f 4159170754Sdelphij@itemx --force 4160170754SdelphijAssume that the user knows exactly what he or she is doing, and do not 4161170754Sdelphijask any questions. @xref{patch Messages}. 4162170754Sdelphij 4163170754Sdelphij@item -F @var{lines} 4164170754Sdelphij@itemx --fuzz=@var{lines} 4165170754SdelphijSet the maximum fuzz factor to @var{lines}. @xref{Inexact}. 4166170754Sdelphij 4167170754Sdelphij@item -g @var{num} 4168170754Sdelphij@itemx --get=@var{num} 4169170754SdelphijIf @var{num} is positive, get input files from a revision control 4170170754Sdelphijsystem as necessary; if zero, do not get the files; if negative, ask 4171170754Sdelphijthe user whether to get the files. @xref{Revision Control}. 4172170754Sdelphij 4173170754Sdelphij@item --help 4174170754SdelphijOutput a summary of usage and then exit. 4175170754Sdelphij 4176170754Sdelphij@item -i @var{patchfile} 4177170754Sdelphij@itemx --input=@var{patchfile} 4178170754SdelphijRead the patch from @var{patchfile} rather than from standard input. 4179170754Sdelphij@xref{patch Options}. 4180170754Sdelphij 4181170754Sdelphij@item -l 4182170754Sdelphij@itemx --ignore-white-space 4183170754SdelphijLet any sequence of blanks (spaces or tabs) in the patch file match 4184170754Sdelphijany sequence of blanks in the input file. @xref{Changed White Space}. 4185170754Sdelphij 4186170754Sdelphij@item -n 4187170754Sdelphij@itemx --normal 4188170754SdelphijInterpret the patch file as a normal diff. @xref{patch Input}. 4189170754Sdelphij 4190170754Sdelphij@item -N 4191170754Sdelphij@itemx --forward 4192170754SdelphijIgnore patches that @command{patch} thinks are reversed or already applied. 4193170754SdelphijSee also @option{-R}. @xref{Reversed Patches}. 4194170754Sdelphij 4195170754Sdelphij@item --no-backup-if-mismatch 4196170754SdelphijDo not back up the original contents of files. This is the default 4197170754Sdelphijbehavior when conforming to @acronym{POSIX}. @xref{Backups}. 4198170754Sdelphij 4199170754Sdelphij@item -o @var{file} 4200170754Sdelphij@itemx --output=@var{file} 4201170754SdelphijUse @var{file} as the output file name. @xref{patch Options}. 4202170754Sdelphij 4203170754Sdelphij@item -p@var{number} 4204170754Sdelphij@itemx --strip=@var{number} 4205170754SdelphijSet the file name strip count to @var{number}. @xref{patch Directories}. 4206170754Sdelphij 4207170754Sdelphij@item --posix 4208170754SdelphijConform to @acronym{POSIX}, as if the @env{POSIXLY_CORRECT} environment 4209170754Sdelphijvariable had been set. @xref{patch and POSIX}. 4210170754Sdelphij 4211170754Sdelphij@item --quoting-style=@var{word} 4212170754SdelphijUse style @var{word} to quote names in diagnostics, as if the 4213170754Sdelphij@env{QUOTING_STYLE} environment variable had been set to @var{word}. 4214170754Sdelphij@xref{patch Quoting Style}. 4215170754Sdelphij 4216170754Sdelphij@item -r @var{reject-file} 4217170754Sdelphij@itemx --reject-file=@var{reject-file} 4218170754SdelphijUse @var{reject-file} as the reject file name. @xref{Reject Names}. 4219170754Sdelphij 4220170754Sdelphij@item -R 4221170754Sdelphij@itemx --reverse 4222170754SdelphijAssume that this patch was created with the old and new files swapped. 4223170754Sdelphij@xref{Reversed Patches}. 4224170754Sdelphij 4225170754Sdelphij@item -s 4226170754Sdelphij@itemx --quiet 4227170754Sdelphij@itemx --silent 4228170754SdelphijWork silently unless an error occurs. @xref{patch Messages}. 4229170754Sdelphij 4230170754Sdelphij@item -t 4231170754Sdelphij@itemx --batch 4232170754SdelphijDo not ask any questions. @xref{patch Messages}. 4233170754Sdelphij 4234170754Sdelphij@item -T 4235170754Sdelphij@itemx --set-time 4236170754SdelphijSet the modification and access times of patched files from time 4237170754Sdelphijstamps given in context diff headers, assuming that the context diff 4238170754Sdelphijheaders use local time. @xref{Patching Time Stamps}. 4239170754Sdelphij 4240170754Sdelphij@item -u 4241170754Sdelphij@itemx --unified 4242170754SdelphijInterpret the patch file as a unified diff. @xref{patch Input}. 4243170754Sdelphij 4244170754Sdelphij@item -v 4245170754Sdelphij@itemx --version 4246170754SdelphijOutput version information and then exit. 4247170754Sdelphij 4248170754Sdelphij@item -V @var{backup-style} 4249170754Sdelphij@itemx --version=control=@var{backup-style} 4250170754SdelphijSelect the naming convention for backup file names. @xref{Backup Names}. 4251170754Sdelphij 4252170754Sdelphij@item --verbose 4253170754SdelphijPrint more diagnostics than usual. @xref{patch Messages}. 4254170754Sdelphij 4255170754Sdelphij@item -x @var{number} 4256170754Sdelphij@itemx --debug=@var{number} 4257170754SdelphijSet internal debugging flags. Of interest only to @command{patch} 4258170754Sdelphijpatchers. 4259170754Sdelphij 4260170754Sdelphij@item -Y @var{prefix} 4261170754Sdelphij@itemx --basename-prefix=@var{prefix} 4262170754SdelphijPrepend @var{prefix} to base names of backup files. @xref{Backup Names}. 4263170754Sdelphij 4264170754Sdelphij@item -z @var{suffix} 4265170754Sdelphij@itemx --suffix=@var{suffix} 4266170754SdelphijUse @var{suffix} as the backup extension instead of @samp{.orig} or 4267170754Sdelphij@samp{~}. @xref{Backup Names}. 4268170754Sdelphij 4269170754Sdelphij@item -Z 4270170754Sdelphij@itemx --set-utc 4271170754SdelphijSet the modification and access times of patched files from time 4272170754Sdelphijstamps given in context diff headers, assuming that the context diff 4273170754Sdelphijheaders use @acronym{UTC}. @xref{Patching Time Stamps}. 4274170754Sdelphij 4275170754Sdelphij@end table 4276170754Sdelphij 4277170754Sdelphij@node Invoking sdiff 4278170754Sdelphij@chapter Invoking @command{sdiff} 4279170754Sdelphij@cindex invoking @command{sdiff} 4280170754Sdelphij@cindex @command{sdiff} invocation 4281170754Sdelphij 4282170754SdelphijThe @command{sdiff} command merges two files and interactively outputs the 4283170754Sdelphijresults. Its arguments are as follows: 4284170754Sdelphij 4285170754Sdelphij@example 4286170754Sdelphijsdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file} 4287170754Sdelphij@end example 4288170754Sdelphij 4289170754SdelphijThis merges @var{from-file} with @var{to-file}, with output to @var{outfile}. 4290170754SdelphijIf @var{from-file} is a directory and @var{to-file} is not, @command{sdiff} 4291170754Sdelphijcompares the file in @var{from-file} whose file name is that of @var{to-file}, 4292170754Sdelphijand vice versa. @var{from-file} and @var{to-file} may not both be 4293170754Sdelphijdirectories. 4294170754Sdelphij 4295170754Sdelphij@command{sdiff} options begin with @samp{-}, so normally @var{from-file} 4296170754Sdelphijand @var{to-file} may not begin with @samp{-}. However, @option{--} as an 4297170754Sdelphijargument by itself treats the remaining arguments as file names even if 4298170754Sdelphijthey begin with @samp{-}. You may not use @file{-} as an input file. 4299170754Sdelphij 4300170754Sdelphij@command{sdiff} without @option{-o} (or @option{--output}) produces a 4301170754Sdelphijside-by-side difference. This usage is obsolete; use the @option{-y} 4302170754Sdelphijor @option{--side-by-side} option of @command{diff} instead. 4303170754Sdelphij 4304170754SdelphijAn exit status of 0 means no differences were found, 1 means some 4305170754Sdelphijdifferences were found, and 2 means trouble. 4306170754Sdelphij 4307170754Sdelphij@menu 4308170754Sdelphij* sdiff Options:: Summary of options to @command{diff}. 4309170754Sdelphij@end menu 4310170754Sdelphij 4311170754Sdelphij@node sdiff Options 4312170754Sdelphij@section Options to @command{sdiff} 4313170754Sdelphij@cindex @command{sdiff} options 4314170754Sdelphij@cindex options for @command{sdiff} 4315170754Sdelphij 4316170754SdelphijBelow is a summary of all of the options that @acronym{GNU} 4317170754Sdelphij@command{sdiff} accepts. Each option has two equivalent names, one of 4318170754Sdelphijwhich is a single letter preceded by @samp{-}, and the other of which 4319170754Sdelphijis a long name preceded by @samp{--}. Multiple single letter options 4320170754Sdelphij(unless they take an argument) can be combined into a single command 4321170754Sdelphijline argument. Long named options can be abbreviated to any unique 4322170754Sdelphijprefix of their name. 4323170754Sdelphij 4324170754Sdelphij@table @option 4325170754Sdelphij@item -a 4326170754Sdelphij@itemx --text 4327170754SdelphijTreat all files as text and compare them line-by-line, even if they 4328170754Sdelphijdo not appear to be text. @xref{Binary}. 4329170754Sdelphij 4330170754Sdelphij@item -b 4331170754Sdelphij@itemx --ignore-space-change 4332170754SdelphijIgnore changes in amount of white space. @xref{White Space}. 4333170754Sdelphij 4334170754Sdelphij@item -B 4335170754Sdelphij@itemx --ignore-blank-lines 4336170754SdelphijIgnore changes that just insert or delete blank lines. @xref{Blank 4337170754SdelphijLines}. 4338170754Sdelphij 4339170754Sdelphij@item -d 4340170754Sdelphij@itemx --minimal 4341170754SdelphijChange the algorithm to perhaps find a smaller set of changes. This 4342170754Sdelphijmakes @command{sdiff} slower (sometimes much slower). @xref{diff 4343170754SdelphijPerformance}. 4344170754Sdelphij 4345170754Sdelphij@item --diff-program=@var{program} 4346170754SdelphijUse the compatible comparison program @var{program} to compare files 4347170754Sdelphijinstead of @command{diff}. 4348170754Sdelphij 4349170754Sdelphij@item -E 4350170754Sdelphij@itemx --ignore-tab-expansion 4351170754SdelphijIgnore changes due to tab expansion. 4352170754Sdelphij@xref{White Space}. 4353170754Sdelphij 4354170754Sdelphij@item --help 4355170754SdelphijOutput a summary of usage and then exit. 4356170754Sdelphij 4357170754Sdelphij@item -i 4358170754Sdelphij@itemx --ignore-case 4359170754SdelphijIgnore changes in case; consider upper- and lower-case to be the same. 4360170754Sdelphij@xref{Case Folding}. 4361170754Sdelphij 4362170754Sdelphij@item -I @var{regexp} 4363170754Sdelphij@itemx --ignore-matching-lines=@var{regexp} 4364170754SdelphijIgnore changes that just insert or delete lines that match @var{regexp}. 4365170754Sdelphij@xref{Specified Lines}. 4366170754Sdelphij 4367170754Sdelphij@item -l 4368170754Sdelphij@itemx --left-column 4369170754SdelphijPrint only the left column of two common lines. 4370170754Sdelphij@xref{Side by Side Format}. 4371170754Sdelphij 4372170754Sdelphij@item -o @var{file} 4373170754Sdelphij@itemx --output=@var{file} 4374170754SdelphijPut merged output into @var{file}. This option is required for merging. 4375170754Sdelphij 4376170754Sdelphij@item -s 4377170754Sdelphij@itemx --suppress-common-lines 4378170754SdelphijDo not print common lines. @xref{Side by Side Format}. 4379170754Sdelphij 4380170754Sdelphij@item --speed-large-files 4381170754SdelphijUse heuristics to speed handling of large files that have numerous 4382170754Sdelphijscattered small changes. @xref{diff Performance}. 4383170754Sdelphij 4384170754Sdelphij@item --strip-trailing-cr 4385170754SdelphijStrip any trailing carriage return at the end of an input line. 4386170754Sdelphij@xref{Binary}. 4387170754Sdelphij 4388170754Sdelphij@item -t 4389170754Sdelphij@itemx --expand-tabs 4390170754SdelphijExpand tabs to spaces in the output, to preserve the alignment of tabs 4391170754Sdelphijin the input files. @xref{Tabs}. 4392170754Sdelphij 4393170754Sdelphij@item --tabsize=@var{columns} 4394170754SdelphijAssume that tab stops are set every @var{columns} (default 8) print 4395170754Sdelphijcolumns. @xref{Tabs}. 4396170754Sdelphij 4397170754Sdelphij@item -v 4398170754Sdelphij@itemx --version 4399170754SdelphijOutput version information and then exit. 4400170754Sdelphij 4401170754Sdelphij@item -w @var{columns} 4402170754Sdelphij@itemx --width=@var{columns} 4403170754SdelphijOutput at most @var{columns} (default 130) print columns per line. 4404170754Sdelphij@xref{Side by Side Format}. Note that for historical reasons, this 4405170754Sdelphijoption is @option{-W} in @command{diff}, @option{-w} in @command{sdiff}. 4406170754Sdelphij 4407170754Sdelphij@item -W 4408170754Sdelphij@itemx --ignore-all-space 4409170754SdelphijIgnore white space when comparing lines. @xref{White Space}. 4410170754SdelphijNote that for historical reasons, this option is @option{-w} in @command{diff}, 4411170754Sdelphij@option{-W} in @command{sdiff}. 4412170754Sdelphij@end table 4413170754Sdelphij 4414170754Sdelphij@node Standards conformance 4415170754Sdelphij@chapter Standards conformance 4416170754Sdelphij@cindex @acronym{POSIX} 4417170754Sdelphij 4418170754Sdelphij@vindex POSIXLY_CORRECT 4419170754SdelphijIn a few cases, the @acronym{GNU} utilities' default behavior is 4420170754Sdelphijincompatible with the @acronym{POSIX} standard. To suppress these 4421170754Sdelphijincompatibilities, define the @env{POSIXLY_CORRECT} environment 4422170754Sdelphijvariable. Unless you are checking for @acronym{POSIX} conformance, you 4423170754Sdelphijprobably do not need to define @env{POSIXLY_CORRECT}. 4424170754Sdelphij 4425170754SdelphijNormally options and operands can appear in any order, and programs act 4426170754Sdelphijas if all the options appear before any operands. For example, 4427170754Sdelphij@samp{diff lao tzu -C 2} acts like @samp{diff -C 2 lao tzu}, since 4428170754Sdelphij@samp{2} is an option-argument of @option{-C}. However, if the 4429170754Sdelphij@env{POSIXLY_CORRECT} environment variable is set, options must appear 4430170754Sdelphijbefore operands, unless otherwise specified for a particular command. 4431170754Sdelphij 4432170754SdelphijNewer versions of @acronym{POSIX} are occasionally incompatible with older 4433170754Sdelphijversions. For example, older versions of @acronym{POSIX} allowed the 4434170754Sdelphijcommand @samp{diff -c -10} to have the same meaning as @samp{diff -C 4435170754Sdelphij10}, but @acronym{POSIX} 1003.1-2001 @samp{diff} no longer allows 4436170754Sdelphijdigit-string options like @option{-10}. 4437170754Sdelphij 4438170754Sdelphij@vindex _POSIX2_VERSION 4439170754SdelphijThe @acronym{GNU} utilities normally conform to the version of @acronym{POSIX} 4440170754Sdelphijthat is standard for your system. To cause them to conform to a 4441170754Sdelphijdifferent version of @acronym{POSIX}, define the @env{_POSIX2_VERSION} 4442170754Sdelphijenvironment variable to a value of the form @var{yyyymm} specifying 4443170754Sdelphijthe year and month the standard was adopted. Two values are currently 4444170754Sdelphijsupported for @env{_POSIX2_VERSION}: @samp{199209} stands for 4445170754Sdelphij@acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX} 4446170754Sdelphij1003.1-2001. For example, if you are running older software that 4447170754Sdelphijassumes an older version of @acronym{POSIX} and uses @samp{diff -c -10}, 4448170754Sdelphijyou can work around the compatibility problems by setting 4449170754Sdelphij@samp{_POSIX2_VERSION=199209} in your environment. 4450170754Sdelphij 4451170754Sdelphij@node Projects 4452170754Sdelphij@chapter Future Projects 4453170754Sdelphij 4454170754SdelphijHere are some ideas for improving @acronym{GNU} @command{diff} and 4455170754Sdelphij@command{patch}. The @acronym{GNU} project has identified some 4456170754Sdelphijimprovements as potential programming projects for volunteers. You 4457170754Sdelphijcan also help by reporting any bugs that you find. 4458170754Sdelphij 4459170754SdelphijIf you are a programmer and would like to contribute something to the 4460170754Sdelphij@acronym{GNU} project, please consider volunteering for one of these 4461170754Sdelphijprojects. If you are seriously contemplating work, please write to 4462170754Sdelphij@email{gvc@@gnu.org} to coordinate with other volunteers. 4463170754Sdelphij 4464170754Sdelphij@menu 4465170754Sdelphij* Shortcomings:: Suggested projects for improvements. 4466170754Sdelphij* Bugs:: Reporting bugs. 4467170754Sdelphij@end menu 4468170754Sdelphij 4469170754Sdelphij@node Shortcomings 4470170754Sdelphij@section Suggested Projects for Improving @acronym{GNU} @command{diff} and @command{patch} 4471170754Sdelphij@cindex projects for directories 4472170754Sdelphij 4473170754SdelphijOne should be able to use @acronym{GNU} @command{diff} to generate a 4474170754Sdelphijpatch from any pair of directory trees, and given the patch and a copy 4475170754Sdelphijof one such tree, use @command{patch} to generate a faithful copy of 4476170754Sdelphijthe other. Unfortunately, some changes to directory trees cannot be 4477170754Sdelphijexpressed using current patch formats; also, @command{patch} does not 4478170754Sdelphijhandle some of the existing formats. These shortcomings motivate the 4479170754Sdelphijfollowing suggested projects. 4480170754Sdelphij 4481170754Sdelphij@menu 4482170754Sdelphij* Internationalization:: Handling multibyte and varying-width characters. 4483170754Sdelphij* Changing Structure:: Handling changes to the directory structure. 4484170754Sdelphij* Special Files:: Handling symbolic links, device special files, etc. 4485170754Sdelphij* Unusual File Names:: Handling file names that contain unusual characters. 4486170754Sdelphij* Time Stamp Order:: Outputting diffs in time stamp order. 4487170754Sdelphij* Ignoring Changes:: Ignoring certain changes while showing others. 4488170754Sdelphij* Speedups:: Improving performance. 4489170754Sdelphij@end menu 4490170754Sdelphij 4491170754Sdelphij@node Internationalization 4492170754Sdelphij@subsection Handling Multibyte and Varying-Width Characters 4493170754Sdelphij@cindex multibyte characters 4494170754Sdelphij@cindex varying-width characters 4495170754Sdelphij 4496170754Sdelphij@command{diff}, @command{diff3} and @command{sdiff} treat each line of 4497170754Sdelphijinput as a string of unibyte characters. This can mishandle multibyte 4498170754Sdelphijcharacters in some cases. For example, when asked to ignore spaces, 4499170754Sdelphij@command{diff} does not properly ignore a multibyte space character. 4500170754Sdelphij 4501170754SdelphijAlso, @command{diff} currently assumes that each byte is one column 4502170754Sdelphijwide, and this assumption is incorrect in some locales, e.g., locales 4503170754Sdelphijthat use UTF-8 encoding. This causes problems with the @option{-y} or 4504170754Sdelphij@option{--side-by-side} option of @command{diff}. 4505170754Sdelphij 4506170754SdelphijThese problems need to be fixed without unduly affecting the 4507170754Sdelphijperformance of the utilities in unibyte environments. 4508170754Sdelphij 4509170754SdelphijThe IBM GNU/Linux Technology Center Internationalization Team has 4510170754Sdelphijproposed 4511170754Sdelphij@uref{http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz,patches 4512170754Sdelphijto support internationalized @command{diff}}. 4513170754SdelphijUnfortunately, these patches are incomplete and are to an older 4514170754Sdelphijversion of @command{diff}, so more work needs to be done in this area. 4515170754Sdelphij 4516170754Sdelphij@node Changing Structure 4517170754Sdelphij@subsection Handling Changes to the Directory Structure 4518170754Sdelphij@cindex directory structure changes 4519170754Sdelphij 4520170754Sdelphij@command{diff} and @command{patch} do not handle some changes to directory 4521170754Sdelphijstructure. For example, suppose one directory tree contains a directory 4522170754Sdelphijnamed @samp{D} with some subsidiary files, and another contains a file 4523170754Sdelphijwith the same name @samp{D}. @samp{diff -r} does not output enough 4524170754Sdelphijinformation for @command{patch} to transform the directory subtree into 4525170754Sdelphijthe file. 4526170754Sdelphij 4527170754SdelphijThere should be a way to specify that a file has been removed without 4528170754Sdelphijhaving to include its entire contents in the patch file. There should 4529170754Sdelphijalso be a way to tell @command{patch} that a file was renamed, even if 4530170754Sdelphijthere is no way for @command{diff} to generate such information. 4531170754SdelphijThere should be a way to tell @command{patch} that a file's time stamp 4532170754Sdelphijhas changed, even if its contents have not changed. 4533170754Sdelphij 4534170754SdelphijThese problems can be fixed by extending the @command{diff} output format 4535170754Sdelphijto represent changes in directory structure, and extending @command{patch} 4536170754Sdelphijto understand these extensions. 4537170754Sdelphij 4538170754Sdelphij@node Special Files 4539170754Sdelphij@subsection Files that are Neither Directories Nor Regular Files 4540170754Sdelphij@cindex special files 4541170754Sdelphij 4542170754SdelphijSome files are neither directories nor regular files: they are unusual 4543170754Sdelphijfiles like symbolic links, device special files, named pipes, and 4544170754Sdelphijsockets. Currently, @command{diff} treats symbolic links as if they 4545170754Sdelphijwere the pointed-to files, except that a recursive @command{diff} 4546170754Sdelphijreports an error if it detects infinite loops of symbolic links (e.g., 4547170754Sdelphijsymbolic links to @file{..}). @command{diff} treats other special 4548170754Sdelphijfiles like regular files if they are specified at the top level, but 4549170754Sdelphijsimply reports their presence when comparing directories. This means 4550170754Sdelphijthat @command{patch} cannot represent changes to such files. For 4551170754Sdelphijexample, if you change which file a symbolic link points to, 4552170754Sdelphij@command{diff} outputs the difference between the two files, instead 4553170754Sdelphijof the change to the symbolic link. 4554170754Sdelphij 4555170754Sdelphij@c This might not be a good idea; is it wise for root to install devices 4556170754Sdelphij@c this way? 4557170754Sdelphij@command{diff} should optionally report changes to special files specially, 4558170754Sdelphijand @command{patch} should be extended to understand these extensions. 4559170754Sdelphij 4560170754Sdelphij@node Unusual File Names 4561170754Sdelphij@subsection File Names that Contain Unusual Characters 4562170754Sdelphij@cindex file names with unusual characters 4563170754Sdelphij 4564170754SdelphijWhen a file name contains an unusual character like a newline or 4565170754Sdelphijwhite space, @samp{diff -r} generates a patch that @command{patch} cannot 4566170754Sdelphijparse. The problem is with format of @command{diff} output, not just with 4567170754Sdelphij@command{patch}, because with odd enough file names one can cause 4568170754Sdelphij@command{diff} to generate a patch that is syntactically correct but 4569170754Sdelphijpatches the wrong files. The format of @command{diff} output should be 4570170754Sdelphijextended to handle all possible file names. 4571170754Sdelphij 4572170754Sdelphij@node Time Stamp Order 4573170754Sdelphij@subsection Outputting Diffs in Time Stamp Order 4574170754Sdelphij 4575170754SdelphijApplying @command{patch} to a multiple-file diff can result in files 4576170754Sdelphijwhose time stamps are out of order. @acronym{GNU} @command{patch} has 4577170754Sdelphijoptions to restore the time stamps of the updated files 4578170754Sdelphij(@pxref{Patching Time Stamps}), but sometimes it is useful to generate 4579170754Sdelphija patch that works even if the recipient does not have @acronym{GNU} patch, 4580170754Sdelphijor does not use these options. One way to do this would be to 4581170754Sdelphijimplement a @command{diff} option to output diffs in time stamp order. 4582170754Sdelphij 4583170754Sdelphij@node Ignoring Changes 4584170754Sdelphij@subsection Ignoring Certain Changes 4585170754Sdelphij 4586170754SdelphijIt would be nice to have a feature for specifying two strings, one in 4587170754Sdelphij@var{from-file} and one in @var{to-file}, which should be considered to 4588170754Sdelphijmatch. Thus, if the two strings are @samp{foo} and @samp{bar}, then if 4589170754Sdelphijtwo lines differ only in that @samp{foo} in file 1 corresponds to 4590170754Sdelphij@samp{bar} in file 2, the lines are treated as identical. 4591170754Sdelphij 4592170754SdelphijIt is not clear how general this feature can or should be, or 4593170754Sdelphijwhat syntax should be used for it. 4594170754Sdelphij 4595170754SdelphijA partial substitute is to filter one or both files before comparing, 4596170754Sdelphije.g.: 4597170754Sdelphij 4598170754Sdelphij@example 4599170754Sdelphijsed 's/foo/bar/g' file1 | diff - file2 4600170754Sdelphij@end example 4601170754Sdelphij 4602170754SdelphijHowever, this outputs the filtered text, not the original. 4603170754Sdelphij 4604170754Sdelphij@node Speedups 4605170754Sdelphij@subsection Improving Performance 4606170754Sdelphij 4607170754SdelphijWhen comparing two large directory structures, one of which was 4608170754Sdelphijoriginally copied from the other with time stamps preserved (e.g., 4609170754Sdelphijwith @samp{cp -pR}), it would greatly improve performance if an option 4610170754Sdelphijtold @command{diff} to assume that two files with the same size and 4611170754Sdelphijtime stamps have the same content. @xref{diff Performance}. 4612170754Sdelphij 4613170754Sdelphij@node Bugs 4614170754Sdelphij@section Reporting Bugs 4615170754Sdelphij@cindex bug reports 4616170754Sdelphij@cindex reporting bugs 4617170754Sdelphij 4618170754SdelphijIf you think you have found a bug in @acronym{GNU} @command{cmp}, 4619170754Sdelphij@command{diff}, @command{diff3}, or @command{sdiff}, please report it 4620170754Sdelphijby electronic mail to the 4621170754Sdelphij@uref{http://mail.gnu.org/mailman/listinfo/bug-gnu-utils,GNU utilities 4622170754Sdelphijbug report mailing list} @email{bug-gnu-utils@@gnu.org}. Please send 4623170754Sdelphijbug reports for @acronym{GNU} @command{patch} to 4624170754Sdelphij@email{bug-patch@@gnu.org}. Send as precise a description of the 4625170754Sdelphijproblem as you can, including the output of the @option{--version} 4626170754Sdelphijoption and sample input files that produce the bug, if applicable. If 4627170754Sdelphijyou have a nontrivial fix for the bug, please send it as well. If you 4628170754Sdelphijhave a patch, please send it too. It may simplify the maintainer's 4629170754Sdelphijjob if the patch is relative to a recent test release, which you can 4630170754Sdelphijfind in the directory @uref{ftp://alpha.gnu.org/gnu/diffutils/}. 4631170754Sdelphij 4632170754Sdelphij@node Copying This Manual 4633170754Sdelphij@appendix Copying This Manual 4634170754Sdelphij 4635170754Sdelphij@menu 4636170754Sdelphij* GNU Free Documentation License:: License for copying this manual. 4637170754Sdelphij@end menu 4638170754Sdelphij 4639170754Sdelphij@include fdl.texi 4640170754Sdelphij 4641170754Sdelphij@node Translations 4642170754Sdelphij@appendix Translations of This Manual 4643170754Sdelphij 4644170754SdelphijNishio Futoshi of the GNUjdoc project has prepared a Japanese 4645170754Sdelphijtranslation of this manual. Its most recent version can be found at 4646170754Sdelphij@uref{http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/}. 4647170754Sdelphij 4648170754Sdelphij@node Index 4649170754Sdelphij@appendix Index 4650170754Sdelphij 4651170754Sdelphij@printindex cp 4652170754Sdelphij 4653170754Sdelphij@bye 4654