From 7e662b2efdf7b11bed05bdd944746d7b7d0e56af Mon Sep 17 00:00:00 2001 From: peter Date: Sun, 29 Oct 1995 08:52:27 +0000 Subject: Import diff-2.7's diff.texi which I left out last time. Suggested by: bde --- gnu/usr.bin/diff/diff.texi | 3916 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3916 insertions(+) create mode 100644 gnu/usr.bin/diff/diff.texi (limited to 'gnu/usr.bin/diff') diff --git a/gnu/usr.bin/diff/diff.texi b/gnu/usr.bin/diff/diff.texi new file mode 100644 index 0000000..7551acb --- /dev/null +++ b/gnu/usr.bin/diff/diff.texi @@ -0,0 +1,3916 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename diff.info +@settitle Comparing and Merging Files +@setchapternewpage odd +@c %**end of header + +@ifinfo +This file documents the the GNU @code{diff}, @code{diff3}, @code{sdiff}, +and @code{cmp} commands for showing the differences between text files +and the @code{patch} command for using their output to update files. + +Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ifinfo + +@titlepage +@title Comparing and Merging Files +@subtitle @code{diff}, @code{diff3}, @code{sdiff}, @code{cmp}, and @code{patch} +@subtitle Edition 1.3, for @code{diff} 2.5 and @code{patch} 2.1 +@subtitle September 1993 +@author by David MacKenzie, Paul Eggert, and Richard Stallman + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end titlepage + +@node Top, , , (dir) + +@ifinfo +This file documents the the GNU @code{diff}, @code{diff3}, @code{sdiff}, +and @code{cmp} commands for showing the differences between text files +and the @code{patch} command for using their output to update files. + +This is Edition 1.2, for @code{diff} 2.4 and @code{patch} 2.1. +@end ifinfo + +@menu +* Overview:: Preliminary information. + +* Comparison:: What file comparison means. +* Output Formats:: Formats for difference reports. +* Comparing Directories:: Comparing files and directories. +* Adjusting Output:: Making @code{diff} output prettier. +* diff Performance:: Making @code{diff} smarter or faster. +* Comparing Three Files:: Formats for three-way difference reports. + +* diff3 Merging:: Merging from a common ancestor. +* Interactive Merging:: Interactive merging with @code{sdiff}. +* Merging with patch:: Using @code{patch} to change old files into new ones. +* Making Patches:: Tips for making patch distributions. + +* Invoking cmp:: How to run @code{cmp} and a summary of its options. +* Invoking diff:: How to run @code{diff} and a summary of its options. +* Invoking diff3:: How to run @code{diff3} and a summary of its options. +* Invoking patch:: How to run @code{patch} and a summary of its options. +* Invoking sdiff:: How to run @code{sdiff} and a summary of its options. + +* Incomplete Lines:: Lines that lack trailing newlines. +* Projects:: If you think you've found a bug or other shortcoming. + +* Concept Index:: Index of concepts. +@end menu + +@node Overview, Comparison, , Top +@unnumbered Overview +@cindex overview of @code{diff} and @code{patch} + +Computer users often find occasion to ask how two files differ. Perhaps +one file is a newer version of the other file. Or maybe the two files +started out as identical copies but were changed by different people. + +You can use the @code{diff} command to show differences between two +files, or each corresponding file in two directories. @code{diff} +outputs differences between files line by line in any of several +formats, selectable by command line options. This set of differences is +often called a @dfn{diff} or @dfn{patch}. For files that are identical, +@code{diff} normally produces no output; for binary (non-text) files, +@code{diff} normally reports only that they are different. + +You can use the @code{cmp} command to show the offsets and line numbers +where two files differ. @code{cmp} can also show all the characters +that differ between the two files, side by side. Another way to compare +two files character by character is the Emacs command @kbd{M-x +compare-windows}. @xref{Other Window, , Other Window, emacs, The GNU +Emacs Manual}, for more information on that command. + +You can use the @code{diff3} command to show differences among three +files. When two people have made independent changes to a common +original, @code{diff3} can report the differences between the original +and the two changed versions, and can produce a merged file that +contains both persons' changes together with warnings about conflicts. + +You can use the @code{sdiff} command to merge two files interactively. + +You can use the set of differences produced by @code{diff} to distribute +updates to text files (such as program source code) to other people. +This method is especially useful when the differences are small compared +to the complete files. Given @code{diff} output, you can use the +@code{patch} program to update, or @dfn{patch}, a copy of the file. If you +think of @code{diff} as subtracting one file from another to produce +their difference, you can think of @code{patch} as adding the difference +to one file to reproduce the other. + +This manual first concentrates on making diffs, and later shows how to +use diffs to update files. + +GNU @code{diff} was written by Mike Haertel, David Hayes, Richard +Stallman, Len Tower, and Paul Eggert. Wayne Davison designed and +implemented the unified output format. The basic algorithm is described +in ``An O(ND) Difference Algorithm and its Variations'', Eugene W. Myers, +@cite{Algorithmica} Vol.@: 1 No.@: 2, 1986, pp.@: 251--266; and in ``A File +Comparison Program'', Webb Miller and Eugene W. Myers, +@cite{Software---Practice and Experience} Vol.@: 15 No.@: 11, 1985, +pp.@: 1025--1040. +@c From: "Gene Myers" +@c They are about the same basic algorithm; the Algorithmica +@c paper gives a rigorous treatment and the sub-algorithm for +@c delivering scripts and should be the primary reference, but +@c both should be mentioned. +The algorithm was independently discovered as described in +``Algorithms for Approximate String Matching'', +E. Ukkonen, @cite{Information and Control} Vol.@: 64, 1985, pp.@: 100--118. +@c From: "Gene Myers" +@c Date: Wed, 29 Sep 1993 08:27:55 MST +@c Ukkonen should be given credit for also discovering the algorithm used +@c in GNU diff. + +GNU @code{diff3} was written by Randy Smith. GNU @code{sdiff} was +written by Thomas Lord. GNU @code{cmp} was written by Torbjorn Granlund +and David MacKenzie. + +@code{patch} was written mainly by Larry Wall; the GNU enhancements were +written mainly by Wayne Davison and David MacKenzie. Parts of this +manual are adapted from a manual page written by Larry Wall, with his +permission. + +@node Comparison, Output Formats, Overview, Top +@chapter What Comparison Means +@cindex introduction + +There are several ways to think about the differences between two files. +One way to think of the differences is as a series of lines that were +deleted from, inserted in, or changed in one file to produce the other +file. @code{diff} compares two files line by line, finds groups of +lines that differ, and reports each group of differing lines. It can +report the differing lines in several formats, which have different +purposes. + +GNU @code{diff} can show whether files are different without detailing +the differences. It also provides ways to suppress certain kinds of +differences that are not important to you. Most commonly, such +differences are changes in the amount of white space between words or +lines. @code{diff} also provides ways to suppress differences in +alphabetic case or in lines that match a regular expression that you +provide. These options can accumulate; for example, you can ignore +changes in both white space and alphabetic case. + +Another way to think of the differences between two files is as a +sequence of pairs of characters that can be either identical or +different. @code{cmp} reports the differences between two files +character by character, instead of line by line. As a result, it is +more useful than @code{diff} for comparing binary files. For text +files, @code{cmp} is useful mainly when you want to know only whether +two files are identical. + +To illustrate the effect that considering changes character by character +can have compared with considering them line by line, think of what +happens if a single newline character is added to the beginning of a +file. If that file is then compared with an otherwise identical file +that lacks the newline at the beginning, @code{diff} will report that a +blank line has been added to the file, while @code{cmp} will report that +almost every character of the two files differs. + +@code{diff3} normally compares three input files line by line, finds +groups of lines that differ, and reports each group of differing lines. +Its output is designed to make it easy to inspect two different sets of +changes to the same file. + +@menu +* Hunks:: Groups of differing lines. +* White Space:: Suppressing differences in white space. +* Blank Lines:: Suppressing differences in blank lines. +* Case Folding:: Suppressing differences in alphabetic case. +* Specified Folding:: Suppressing differences that match regular expressions. +* Brief:: Summarizing which files are different. +* Binary:: Comparing binary files or forcing text comparisons. +@end menu + +@node Hunks, White Space, , Comparison +@section Hunks +@cindex hunks + +When comparing two files, @code{diff} finds sequences of lines common to +both files, interspersed with groups of differing lines called +@dfn{hunks}. Comparing two identical files yields one sequence of +common lines and no hunks, because no lines differ. Comparing two +entirely different files yields no common lines and one large hunk that +contains all lines of both files. In general, there are many ways to +match up lines between two given files. @code{diff} tries to minimize +the total hunk size by finding large sequences of common lines +interspersed with small hunks of differing lines. + +For example, suppose the file @file{F} contains the three lines +@samp{a}, @samp{b}, @samp{c}, and the file @file{G} contains the same +three lines in reverse order @samp{c}, @samp{b}, @samp{a}. If +@code{diff} finds the line @samp{c} as common, then the command +@samp{diff F G} produces this output: + +@example +1,2d0 +< a +< b +3a2,3 +> b +> a +@end example + +@noindent +But if @code{diff} notices the common line @samp{b} instead, it produces +this output: + +@example +1c1 +< a +--- +> c +3c3 +< c +--- +> a +@end example + +@noindent +It is also possible to find @samp{a} as the common line. @code{diff} +does not always find an optimal matching between the files; it takes +shortcuts to run faster. But its output is usually close to the +shortest possible. You can adjust this tradeoff with the +@samp{--minimal} option (@pxref{diff Performance}). + +@node White Space, Blank Lines, Hunks, Comparison +@section Suppressing Differences in Blank and Tab Spacing +@cindex blank and tab difference suppression +@cindex tab and blank difference suppression + +The @samp{-b} and @samp{--ignore-space-change} options ignore white space +at line end, and considers all other sequences of one or more +white space characters to be equivalent. With these options, +@code{diff} considers the following two lines to be equivalent, where +@samp{$} denotes the line end: + +@example +Here lyeth muche rychnesse in lytell space. -- John Heywood$ +Here lyeth muche rychnesse in lytell space. -- John Heywood $ +@end example + +The @samp{-w} and @samp{--ignore-all-space} options are stronger than +@samp{-b}. They ignore difference even if one file has white space where +the other file has none. @dfn{White space} characters include +tab, newline, vertical tab, form feed, carriage return, and space; +some locales may define additional characters to be white space. +With these options, @code{diff} considers the +following two lines to be equivalent, where @samp{$} denotes the line +end and @samp{^M} denotes a carriage return: + +@example +Here lyeth muche rychnesse in lytell space.-- John Heywood$ + He relyeth much erychnes seinly tells pace. --John Heywood ^M$ +@end example + +@node Blank Lines, Case Folding, White Space, Comparison +@section Suppressing Differences in Blank Lines +@cindex blank line difference suppression + +The @samp{-B} and @samp{--ignore-blank-lines} options ignore insertions +or deletions of blank lines. These options normally affect only lines +that are completely empty; they do not affect lines that look empty but +contain space or tab characters. With these options, for example, a +file containing +@example +1. A point is that which has no part. + +2. A line is breadthless length. +-- Euclid, The Elements, I +@end example +@noindent +is considered identical to a file containing +@example +1. A point is that which has no part. +2. A line is breadthless length. + + +-- Euclid, The Elements, I +@end example + +@node Case Folding, Specified Folding, Blank Lines, Comparison +@section Suppressing Case Differences +@cindex case difference suppression + +GNU @code{diff} can treat lowercase letters as equivalent to their +uppercase counterparts, so that, for example, it considers @samp{Funky +Stuff}, @samp{funky STUFF}, and @samp{fUNKy stuFf} to all be the same. +To request this, use the @samp{-i} or @samp{--ignore-case} option. + +@node Specified Folding, Brief, Case Folding, Comparison +@section Suppressing Lines Matching a Regular Expression +@cindex regular expression suppression + +To ignore insertions and deletions of lines that match a regular +expression, use the @samp{-I @var{regexp}} or +@samp{--ignore-matching-lines=@var{regexp}} option. You should escape +regular expressions that contain shell metacharacters to prevent the +shell from expanding them. For example, @samp{diff -I '^[0-9]'} ignores +all changes to lines beginning with a digit. + +However, @samp{-I} only ignores the insertion or deletion of lines that +contain the regular expression if every changed line in the hunk---every +insertion and every deletion---matches the regular expression. In other +words, for each nonignorable change, @code{diff} prints the complete set +of changes in its vicinity, including the ignorable ones. + +You can specify more than one regular expression for lines to ignore by +using more than one @samp{-I} option. @code{diff} tries to match each +line against each regular expression, starting with the last one given. + +@node Brief, Binary, Specified Folding, Comparison +@section Summarizing Which Files Differ +@cindex summarizing which files differ +@cindex brief difference reports + +When you only want to find out whether files are different, and you +don't care what the differences are, you can use the summary output +format. In this format, instead of showing the differences between the +files, @code{diff} simply reports whether files differ. The @samp{-q} +and @samp{--brief} options select this output format. + +This format is especially useful when comparing the contents of two +directories. It is also much faster than doing the normal line by line +comparisons, because @code{diff} can stop analyzing the files as soon as +it knows that there are any differences. + +You can also get a brief indication of whether two files differ by using +@code{cmp}. For files that are identical, @code{cmp} produces no +output. When the files differ, by default, @code{cmp} outputs the byte +offset and line number where the first difference occurs. You can use +the @samp{-s} option to suppress that information, so that @code{cmp} +produces no output and reports whether the files differ using only its +exit status (@pxref{Invoking cmp}). + +@c Fix this. +Unlike @code{diff}, @code{cmp} cannot compare directories; it can only +compare two files. + +@node Binary, , Brief, Comparison +@section Binary Files and Forcing Text Comparisons +@cindex binary file diff +@cindex text versus binary diff + +If @code{diff} thinks that either of the two files it is comparing is +binary (a non-text file), it normally treats that pair of files much as +if the summary output format had been selected (@pxref{Brief}), and +reports only that the binary files are different. This is because line +by line comparisons are usually not meaningful for binary files. + +@code{diff} determines whether a file is text or binary by checking the +first few bytes in the file; the exact number of bytes is system +dependent, but it is typically several thousand. If every character in +that part of the file is non-null, @code{diff} considers the file to be +text; otherwise it considers the file to be binary. + +Sometimes you might want to force @code{diff} to consider files to be +text. For example, you might be comparing text files that contain +null characters; @code{diff} would erroneously decide that those are +non-text files. Or you might be comparing documents that are in a +format used by a word processing system that uses null characters to +indicate special formatting. You can force @code{diff} to consider all +files to be text files, and compare them line by line, by using the +@samp{-a} or @samp{--text} option. If the files you compare using this +option do not in fact contain text, they will probably contain few +newline characters, and the @code{diff} output will consist of hunks +showing differences between long lines of whatever characters the files +contain. + +You can also force @code{diff} to consider all files to be binary files, +and report only whether they differ (but not how). Use the +@samp{--brief} option for this. + +In operating systems that distinguish between text and binary files, +@code{diff} normally reads and writes all data as text. Use the +@samp{--binary} option to force @code{diff} to read and write binary +data instead. This option has no effect on a Posix-compliant system +like GNU or traditional Unix. However, many personal computer +operating systems represent the end of a line with a carriage return +followed by a newline. On such systems, @code{diff} normally ignores +these carriage returns on input and generates them at the end of each +output line, but with the @samp{--binary} option @code{diff} treats +each carriage return as just another input character, and does not +generate a carriage return at the end of each output line. This can be +useful when dealing with non-text files that are meant to be +interchanged with Posix-compliant systems. + +If you want to compare two files byte by byte, you can use the +@code{cmp} program with the @samp{-l} option to show the values of each +differing byte in the two files. With GNU @code{cmp}, you can also use +the @samp{-c} option to show the ASCII representation of those bytes. +@xref{Invoking cmp}, for more information. + +If @code{diff3} thinks that any of the files it is comparing is binary +(a non-text file), it normally reports an error, because such +comparisons are usually not useful. @code{diff3} uses the same test as +@code{diff} to decide whether a file is binary. As with @code{diff}, if +the input files contain a few non-text characters but otherwise are like +text files, you can force @code{diff3} to consider all files to be text +files and compare them line by line by using the @samp{-a} or +@samp{--text} options. + +@node Output Formats, Comparing Directories, Comparison, Top +@chapter @code{diff} Output Formats +@cindex output formats +@cindex format of @code{diff} output + +@code{diff} has several mutually exclusive options for output format. +The following sections describe each format, illustrating how +@code{diff} reports the differences between two sample input files. + +@menu +* Sample diff Input:: Sample @code{diff} input files for examples. +* Normal:: Showing differences without surrounding text. +* Context:: Showing differences with the surrounding text. +* Side by Side:: Showing differences in two columns. +* Scripts:: Generating scripts for other programs. +* If-then-else:: Merging files with if-then-else. +@end menu + +@node Sample diff Input, Normal, , Output Formats +@section Two Sample Input Files +@cindex @code{diff} sample input +@cindex sample input for @code{diff} + +Here are two sample files that we will use in numerous examples to +illustrate the output of @code{diff} and how various options can change +it. + +This is the file @file{lao}: + +@example +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +The Nameless is the origin of Heaven and Earth; +The Named is the mother of all things. +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their outcome. +The two are the same, +But after they are produced, + they have different names. +@end example + +This is the file @file{tzu}: + +@example +The Nameless is the origin of Heaven and Earth; +The named is the mother of all things. + +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their outcome. +The two are the same, +But after they are produced, + they have different names. +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +@end example + +In this example, the first hunk contains just the first two lines of +@file{lao}, the second hunk contains the fourth line of @file{lao} +opposing the second and third lines of @file{tzu}, and the last hunk +contains just the last three lines of @file{tzu}. + +@node Normal, Context, Sample diff Input, Output Formats +@section Showing Differences Without Context +@cindex normal output format +@cindex @samp{<} output format + +The ``normal'' @code{diff} output format shows each hunk of differences +without any surrounding context. Sometimes such output is the clearest +way to see how lines have changed, without the clutter of nearby +unchanged lines (although you can get similar results with the context +or unified formats by using 0 lines of context). However, this format +is no longer widely used for sending out patches; for that purpose, the +context format (@pxref{Context Format}) and the unified format +(@pxref{Unified Format}) are superior. Normal format is the default for +compatibility with older versions of @code{diff} and the Posix standard. + +@menu +* Detailed Normal:: A detailed description of normal output format. +* Example Normal:: Sample output in the normal format. +@end menu + +@node Detailed Normal, Example Normal, , Normal +@subsection Detailed Description of Normal Format + +The normal output format consists of one or more hunks of differences; +each hunk shows one area where the files differ. Normal format hunks +look like this: + +@example +@var{change-command} +< @var{from-file-line} +< @var{from-file-line}@dots{} +--- +> @var{to-file-line} +> @var{to-file-line}@dots{} +@end example + +There are three types of change commands. Each consists of a line +number or comma-separated range of lines in the first file, a single +character indicating the kind of change to make, and a line number or +comma-separated range of lines in the second file. All line numbers are +the original line numbers in each file. The types of change commands +are: + +@table @samp +@item @var{l}a@var{r} +Add the lines in range @var{r} of the second file after line @var{l} of +the first file. For example, @samp{8a12,15} means append lines 12--15 +of file 2 after line 8 of file 1; or, if changing file 2 into file 1, +delete lines 12--15 of file 2. + +@item @var{f}c@var{t} +Replace the lines in range @var{f} of the first file with lines in range +@var{t} of the second file. This is like a combined add and delete, but +more compact. For example, @samp{5,7c8,10} means change lines 5--7 of +file 1 to read as lines 8--10 of file 2; or, if changing file 2 into +file 1, change lines 8--10 of file 2 to read as lines 5--7 of file 1. + +@item @var{r}d@var{l} +Delete the lines in range @var{r} from the first file; line @var{l} is where +they would have appeared in the second file had they not been deleted. +For example, @samp{5,7d3} means delete lines 5--7 of file 1; or, if +changing file 2 into file 1, append lines 5--7 of file 1 after line 3 of +file 2. +@end table + +@node Example Normal, , Detailed Normal, Normal +@subsection An Example of Normal Format + +Here is the output of the command @samp{diff lao tzu} +(@pxref{Sample diff Input}, for the complete contents of the two files). +Notice that it shows only the lines that are different between the two +files. + +@example +1,2d0 +< The Way that can be told of is not the eternal Way; +< The name that can be named is not the eternal name. +4c2,3 +< The Named is the mother of all things. +--- +> The named is the mother of all things. +> +11a11,13 +> They both may be called deep and profound. +> Deeper and more profound, +> The door of all subtleties! +@end example + +@node Context, Side by Side, Normal, Output Formats +@section Showing Differences in Their Context +@cindex context output format +@cindex @samp{!} output format + +Usually, when you are looking at the differences between files, you will +also want to see the parts of the files near the lines that differ, to +help you understand exactly what has changed. These nearby parts of the +files are called the @dfn{context}. + +GNU @code{diff} provides two output formats that show context around the +differing lines: @dfn{context format} and @dfn{unified format}. It can +optionally show in which function or section of the file the differing +lines are found. + +If you are distributing new versions of files to other people in the +form of @code{diff} output, you should use one of the output formats +that show context so that they can apply the diffs even if they have +made small changes of their own to the files. @code{patch} can apply +the diffs in this case by searching in the files for the lines of +context around the differing lines; if those lines are actually a few +lines away from where the diff says they are, @code{patch} can adjust +the line numbers accordingly and still apply the diff correctly. +@xref{Imperfect}, for more information on using @code{patch} to apply +imperfect diffs. + +@menu +* Context Format:: An output format that shows surrounding lines. +* Unified Format:: A more compact output format that shows context. +* Sections:: Showing which sections of the files differences are in. +* Alternate Names:: Showing alternate file names in context headers. +@end menu + +@node Context Format, Unified Format, , Context +@subsection Context Format + +The context output format shows several lines of context around the +lines that differ. It is the standard format for distributing updates +to source code. + +To select this output format, use the @samp{-C @var{lines}}, +@samp{--context@r{[}=@var{lines}@r{]}}, or @samp{-c} option. The +argument @var{lines} that some of these options take is the number of +lines of context to show. If you do not specify @var{lines}, it +defaults to three. For proper operation, @code{patch} typically needs +at least two lines of context. + +@menu +* Detailed Context:: A detailed description of the context output format. +* Example Context:: Sample output in context format. +* Less Context:: Another sample with less context. +@end menu + +@node Detailed Context, Example Context, , Context Format +@subsubsection Detailed Description of Context Format + +The context output format starts with a two-line header, which looks +like this: + +@example +*** @var{from-file} @var{from-file-modification-time} +--- @var{to-file} @var{to-file-modification time} +@end example + +@noindent +You can change the header's content with the @samp{-L @var{label}} or +@samp{--label=@var{label}} option; see @ref{Alternate Names}. + +Next come one or more hunks of differences; each hunk shows one area +where the files differ. Context format hunks look like this: + +@example +*************** +*** @var{from-file-line-range} **** + @var{from-file-line} + @var{from-file-line}@dots{} +--- @var{to-file-line-range} ---- + @var{to-file-line} + @var{to-file-line}@dots{} +@end example + +The lines of context around the lines that differ start with two space +characters. The lines that differ between the two files start with one +of the following indicator characters, followed by a space character: + +@table @samp +@item ! +A line that is part of a group of one or more lines that changed between +the two files. There is a corresponding group of lines marked with +@samp{!} in the part of this hunk for the other file. + +@item + +An ``inserted'' line in the second file that corresponds to nothing in +the first file. + +@item - +A ``deleted'' line in the first file that corresponds to nothing in the +second file. +@end table + +If all of the changes in a hunk are insertions, the lines of +@var{from-file} are omitted. If all of the changes are deletions, the +lines of @var{to-file} are omitted. + +@node Example Context, Less Context, Detailed Context, Context Format +@subsubsection An Example of Context Format + +Here is the output of @samp{diff -c lao tzu} (@pxref{Sample diff Input}, +for the complete contents of the two files). Notice that up to three +lines that are not different are shown around each line that is +different; they are the context lines. Also notice that the first two +hunks have run together, because their contents overlap. + +@example +*** lao Sat Jan 26 23:30:39 1991 +--- tzu Sat Jan 26 23:30:50 1991 +*************** +*** 1,7 **** +- The Way that can be told of is not the eternal Way; +- The name that can be named is not the eternal name. + The Nameless is the origin of Heaven and Earth; +! The Named is the mother of all things. + Therefore let there always be non-being, + so we may see their subtlety, + And let there always be being, +--- 1,6 ---- + The Nameless is the origin of Heaven and Earth; +! The named is the mother of all things. +! + Therefore let there always be non-being, + so we may see their subtlety, + And let there always be being, +*************** +*** 9,11 **** +--- 8,13 ---- + The two are the same, + But after they are produced, + they have different names. ++ They both may be called deep and profound. ++ Deeper and more profound, ++ The door of all subtleties! +@end example + +@node Less Context, , Example Context, Context Format +@subsubsection An Example of Context Format with Less Context + +Here is the output of @samp{diff --context=1 lao tzu} (@pxref{Sample +diff Input}, for the complete contents of the two files). Notice that +at most one context line is reported here. + +@example +*** lao Sat Jan 26 23:30:39 1991 +--- tzu Sat Jan 26 23:30:50 1991 +*************** +*** 1,5 **** +- The Way that can be told of is not the eternal Way; +- The name that can be named is not the eternal name. + The Nameless is the origin of Heaven and Earth; +! The Named is the mother of all things. + Therefore let there always be non-being, +--- 1,4 ---- + The Nameless is the origin of Heaven and Earth; +! The named is the mother of all things. +! + Therefore let there always be non-being, +*************** +*** 11 **** +--- 10,13 ---- + they have different names. ++ They both may be called deep and profound. ++ Deeper and more profound, ++ The door of all subtleties! +@end example + +@node Unified Format, Sections, Context Format, Context +@subsection Unified Format +@cindex unified output format +@cindex @samp{+-} output format + +The unified output format is a variation on the context format that is +more compact because it omits redundant context lines. To select this +output format, use the @samp{-U @var{lines}}, +@samp{--unified@r{[}=@var{lines}@r{]}}, or @samp{-u} +option. The argument @var{lines} is the number of lines of context to +show. When it is not given, it defaults to three. + +At present, only GNU @code{diff} can produce this format and only GNU +@code{patch} can automatically apply diffs in this format. For proper +operation, @code{patch} typically needs at least two lines of context. + +@menu +* Detailed Unified:: A detailed description of unified format. +* Example Unified:: Sample output in unified format. +@end menu + +@node Detailed Unified, Example Unified, , Unified Format +@subsubsection Detailed Description of Unified Format + +The unified output format starts with a two-line header, which looks +like this: + +@example +--- @var{from-file} @var{from-file-modification-time} ++++ @var{to-file} @var{to-file-modification-time} +@end example + +@noindent +You can change the header's content with the @samp{-L @var{label}} or +@samp{--label=@var{label}} option; see @xref{Alternate Names}. + +Next come one or more hunks of differences; each hunk shows one area +where the files differ. Unified format hunks look like this: + +@example +@@@@ @var{from-file-range} @var{to-file-range} @@@@ + @var{line-from-either-file} + @var{line-from-either-file}@dots{} +@end example + +The lines common to both files begin with a space character. The lines +that actually differ between the two files have one of the following +indicator characters in the left column: + +@table @samp +@item + +A line was added here to the first file. + +@item - +A line was removed here from the first file. +@end table + +@node Example Unified, , Detailed Unified, Unified Format +@subsubsection An Example of Unified Format + +Here is the output of the command @samp{diff -u lao tzu} +(@pxref{Sample diff Input}, for the complete contents of the two files): + +@example +--- lao Sat Jan 26 23:30:39 1991 ++++ tzu Sat Jan 26 23:30:50 1991 +@@@@ -1,7 +1,6 @@@@ +-The Way that can be told of is not the eternal Way; +-The name that can be named is not the eternal name. + The Nameless is the origin of Heaven and Earth; +-The Named is the mother of all things. ++The named is the mother of all things. ++ + Therefore let there always be non-being, + so we may see their subtlety, + And let there always be being, +@@@@ -9,3 +8,6 @@@@ + The two are the same, + But after they are produced, + they have different names. ++They both may be called deep and profound. ++Deeper and more profound, ++The door of all subtleties! +@end example + +@node Sections, Alternate Names, Unified Format, Context +@subsection Showing Which Sections Differences Are in +@cindex headings +@cindex section headings + +Sometimes you might want to know which part of the files each change +falls in. If the files are source code, this could mean which function +was changed. If the files are documents, it could mean which chapter or +appendix was changed. GNU @code{diff} can show this by displaying the +nearest section heading line that precedes the differing lines. Which +lines are ``section headings'' is determined by a regular expression. + +@menu +* Specified Headings:: Showing headings that match regular expressions. +* C Function Headings:: Showing headings of C functions. +@end menu + +@node Specified Headings, C Function Headings, , Sections +@subsubsection Showing Lines That Match Regular Expressions +@cindex specified headings +@cindex regular expression matching headings + +To show in which sections differences occur for files that are not +source code for C or similar languages, use the @samp{-F @var{regexp}} +or @samp{--show-function-line=@var{regexp}} option. @code{diff} +considers lines that match the argument @var{regexp} to be the beginning +of a section of the file. Here are suggested regular expressions for +some common languages: + +@c Please add to this list, e.g. Fortran, Pascal. +@table @samp +@item ^[A-Za-z_] +C, C++, Prolog +@item ^( +Lisp +@item ^@@\(chapter\|appendix\|unnumbered\|chapheading\) +Texinfo +@end table + +This option does not automatically select an output format; in order to +use it, you must select the context format (@pxref{Context Format}) or +unified format (@pxref{Unified Format}). In other output formats it +has no effect. + +The @samp{-F} and @samp{--show-function-line} options find the nearest +unchanged line that precedes each hunk of differences and matches the +given regular expression. Then they add that line to the end of the +line of asterisks in the context format, or to the @samp{@@@@} line in +unified format. If no matching line exists, they leave the output for +that hunk unchanged. If that line is more than 40 characters long, they +output only the first 40 characters. You can specify more than one +regular expression for such lines; @code{diff} tries to match each line +against each regular expression, starting with the last one given. This +means that you can use @samp{-p} and @samp{-F} together, if you wish. + +@node C Function Headings, , Specified Headings, Sections +@subsubsection Showing C Function Headings +@cindex C function headings +@cindex function headings, C + +To show in which functions differences occur for C and similar +languages, you can use the @samp{-p} or @samp{--show-c-function} option. +This option automatically defaults to the context output format +(@pxref{Context Format}), with the default number of lines of context. +You can override that number with @samp{-C @var{lines}} elsewhere in the +command line. You can override both the format and the number with +@samp{-U @var{lines}} elsewhere in the command line. + +The @samp{-p} and @samp{--show-c-function} options are equivalent to +@samp{-F'^[_a-zA-Z$]'} if the unified format is specified, otherwise +@samp{-c -F'^[_a-zA-Z$]'} (@pxref{Specified Headings}). GNU @code{diff} +provides them for the sake of convenience. + +@node Alternate Names, , Sections, Context +@subsection Showing Alternate File Names +@cindex alternate file names +@cindex file name alternates + +If you are comparing two files that have meaningless or uninformative +names, you might want @code{diff} to show alternate names in the header +of the context and unified output formats. To do this, use the @samp{-L +@var{label}} or @samp{--label=@var{label}} option. The first time +you give this option, its argument replaces the name and date of the +first file in the header; the second time, its argument replaces the +name and date of the second file. If you give this option more than +twice, @code{diff} reports an error. The @samp{-L} option does not +affect the file names in the @code{pr} header when the @samp{-l} or +@samp{--paginate} option is used (@pxref{Pagination}). + +Here are the first two lines of the output from @samp{diff -C2 +-Loriginal -Lmodified lao tzu}: + +@example +*** original +--- modified +@end example + +@node Side by Side, Scripts, Context, Output Formats +@section Showing Differences Side by Side +@cindex side by side +@cindex two-column output +@cindex columnar output + +@code{diff} can produce a side by side difference listing of two files. +The files are listed in two columns with a gutter between them. The +gutter contains one of the following markers: + +@table @asis +@item white space +The corresponding lines are in common. That is, either the lines are +identical, or the difference is ignored because of one of the +@samp{--ignore} options (@pxref{White Space}). + +@item @samp{|} +The corresponding lines differ, and they are either both complete +or both incomplete. + +@item @samp{<} +The files differ and only the first file contains the line. + +@item @samp{>} +The files differ and only the second file contains the line. + +@item @samp{(} +Only the first file contains the line, but the difference is ignored. + +@item @samp{)} +Only the second file contains the line, but the difference is ignored. + +@item @samp{\} +The corresponding lines differ, and only the first line is incomplete. + +@item @samp{/} +The corresponding lines differ, and only the second line is incomplete. +@end table + +Normally, an output line is incomplete if and only if the lines that it +contains are incomplete; @xref{Incomplete Lines}. However, when an +output line represents two differing lines, one might be incomplete +while the other is not. In this case, the output line is complete, +but its the gutter is marked @samp{\} if the first line is incomplete, +@samp{/} if the second line is. + +Side by side format is sometimes easiest to read, but it has limitations. +It generates much wider output than usual, and truncates lines that are +too long to fit. Also, it relies on lining up output more heavily than +usual, so its output looks particularly bad if you use varying +width fonts, nonstandard tab stops, or nonprinting characters. + +You can use the @code{sdiff} command to interactively merge side by side +differences. @xref{Interactive Merging}, for more information on merging files. + +@menu +* Side by Side Format:: Controlling side by side output format. +* Example Side by Side:: Sample side by side output. +@end menu + +@node Side by Side Format, Example Side by Side, , Side by Side +@section Controlling Side by Side Format +@cindex side by side format + +The @samp{-y} or @samp{--side-by-side} option selects side by side +format. Because side by side output lines contain two input lines, they +are wider than usual. They are normally 130 columns, which can fit onto +a traditional printer line. You can set the length of output lines with +the @samp{-W @var{columns}} or @samp{--width=@var{columns}} option. The +output line is split into two halves of equal length, separated by a +small gutter to mark differences; the right half is aligned to a tab +stop so that tabs line up. Input lines that are too long to fit in half +of an output line are truncated for output. + +The @samp{--left-column} option prints only the left column of two +common lines. The @samp{--suppress-common-lines} option suppresses +common lines entirely. + +@node Example Side by Side, , Side by Side Format, Side by Side +@subsection An Example of Side by Side Format + +Here is the output of the command @samp{diff -y -W 72 lao tzu} +(@pxref{Sample diff Input}, for the complete contents of the two files). + +@example +The Way that can be told of is n < +The name that can be named is no < +The Nameless is the origin of He The Nameless is the origin of He +The Named is the mother of all t | The named is the mother of all t + > +Therefore let there always be no Therefore let there always be no + so we may see their subtlety, so we may see their subtlety, +And let there always be being, And let there always be being, + so we may see their outcome. so we may see their outcome. +The two are the same, The two are the same, +But after they are produced, But after they are produced, + they have different names. they have different names. + > They both may be called deep and + > Deeper and more profound, + > The door of all subtleties! +@end example + +@node Scripts, If-then-else, Side by Side, Output Formats +@section Making Edit Scripts +@cindex script output formats + +Several output modes produce command scripts for editing @var{from-file} +to produce @var{to-file}. + +@menu +* ed Scripts:: Using @code{diff} to produce commands for @code{ed}. +* Forward ed:: Making forward @code{ed} scripts. +* RCS:: A special @code{diff} output format used by RCS. +@end menu + +@node ed Scripts, Forward ed, , Scripts +@subsection @code{ed} Scripts +@cindex @code{ed} script output format + +@code{diff} can produce commands that direct the @code{ed} text editor +to change the first file into the second file. Long ago, this was the +only output mode that was suitable for editing one file into another +automatically; today, with @code{patch}, it is almost obsolete. Use the +@samp{-e} or @samp{--ed} option to select this output format. + +Like the normal format (@pxref{Normal}), this output format does not +show any context; unlike the normal format, it does not include the +information necessary to apply the diff in reverse (to produce the first +file if all you have is the second file and the diff). + +If the file @file{d} contains the output of @samp{diff -e old new}, then +the command @samp{(cat d && echo w) | ed - old} edits @file{old} to make +it a copy of @file{new}. More generally, if @file{d1}, @file{d2}, +@dots{}, @file{dN} contain the outputs of @samp{diff -e old new1}, +@samp{diff -e new1 new2}, @dots{}, @samp{diff -e newN-1 newN}, +respectively, then the command @samp{(cat d1 d2 @dots{} dN && echo w) | +ed - old} edits @file{old} to make it a copy of @file{newN}. + +@menu +* Detailed ed:: A detailed description of @code{ed} format. +* Example ed:: A sample @code{ed} script. +@end menu + +@node Detailed ed, Example ed, , ed Scripts +@subsubsection Detailed Description of @code{ed} Format + +The @code{ed} output format consists of one or more hunks of +differences. The changes closest to the ends of the files come first so +that commands that change the number of lines do not affect how +@code{ed} interprets line numbers in succeeding commands. @code{ed} +format hunks look like this: + +@example +@var{change-command} +@var{to-file-line} +@var{to-file-line}@dots{} +. +@end example + +Because @code{ed} uses a single period on a line to indicate the end of +input, GNU @code{diff} protects lines of changes that contain a single +period on a line by writing two periods instead, then writing a +subsequent @code{ed} command to change the two periods into one. The +@code{ed} format cannot represent an incomplete line, so if the second +file ends in a changed incomplete line, @code{diff} reports an error and +then pretends that a newline was appended. + +There are three types of change commands. Each consists of a line +number or comma-separated range of lines in the first file and a single +character indicating the kind of change to make. All line numbers are +the original line numbers in the file. The types of change commands +are: + +@table @samp +@item @var{l}a +Add text from the second file after line @var{l} in the first file. For +example, @samp{8a} means to add the following lines after line 8 of file +1. + +@item @var{r}c +Replace the lines in range @var{r} in the first file with the following +lines. Like a combined add and delete, but more compact. For example, +@samp{5,7c} means change lines 5--7 of file 1 to read as the text file +2. + +@item @var{r}d +Delete the lines in range @var{r} from the first file. For example, +@samp{5,7d} means delete lines 5--7 of file 1. +@end table + +@node Example ed, , Detailed ed, ed Scripts +@subsubsection Example @code{ed} Script + +Here is the output of @samp{diff -e lao tzu} (@pxref{Sample +diff Input}, for the complete contents of the two files): + +@example +11a +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +. +4c +The named is the mother of all things. + +. +1,2d +@end example + +@node Forward ed, RCS, ed Scripts, Scripts +@subsection Forward @code{ed} Scripts +@cindex forward @code{ed} script output format + +@code{diff} can produce output that is like an @code{ed} script, but +with hunks in forward (front to back) order. The format of the commands +is also changed slightly: command characters precede the lines they +modify, spaces separate line numbers in ranges, and no attempt is made +to disambiguate hunk lines consisting of a single period. Like +@code{ed} format, forward @code{ed} format cannot represent incomplete +lines. + +Forward @code{ed} format is not very useful, because neither @code{ed} +nor @code{patch} can apply diffs in this format. It exists mainly for +compatibility with older versions of @code{diff}. Use the @samp{-f} or +@samp{--forward-ed} option to select it. + +@node RCS, , Forward ed, Scripts +@subsection RCS Scripts +@cindex RCS script output format + +The RCS output format is designed specifically for use by the Revision +Control System, which is a set of free programs used for organizing +different versions and systems of files. Use the @samp{-n} or +@samp{--rcs} option to select this output format. It is like the +forward @code{ed} format (@pxref{Forward ed}), but it can represent +arbitrary changes to the contents of a file because it avoids the +forward @code{ed} format's problems with lines consisting of a single +period and with incomplete lines. Instead of ending text sections with +a line consisting of a single period, each command specifies the number +of lines it affects; a combination of the @samp{a} and @samp{d} +commands are used instead of @samp{c}. Also, if the second file ends +in a changed incomplete line, then the output also ends in an +incomplete line. + +Here is the output of @samp{diff -n lao tzu} (@pxref{Sample +diff Input}, for the complete contents of the two files): + +@example +d1 2 +d4 1 +a4 2 +The named is the mother of all things. + +a11 3 +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +@end example + +@node If-then-else, , Scripts, Output Formats +@section Merging Files with If-then-else +@cindex merged output format +@cindex if-then-else output format +@cindex C if-then-else output format +@cindex @code{ifdef} output format + +You can use @code{diff} to merge two files of C source code. The output +of @code{diff} in this format contains all the lines of both files. +Lines common to both files are output just once; the differing parts are +separated by the C preprocessor directives @code{#ifdef @var{name}} or +@code{#ifndef @var{name}}, @code{#else}, and @code{#endif}. When +compiling the output, you select which version to use by either defining +or leaving undefined the macro @var{name}. + +To merge two files, use @code{diff} with the @samp{-D @var{name}} or +@samp{--ifdef=@var{name}} option. The argument @var{name} is the C +preprocessor identifier to use in the @code{#ifdef} and @code{#ifndef} +directives. + +For example, if you change an instance of @code{wait (&s)} to +@code{waitpid (-1, &s, 0)} and then merge the old and new files with +the @samp{--ifdef=HAVE_WAITPID} option, then the affected part of your code +might look like this: + +@example + do @{ +#ifndef HAVE_WAITPID + if ((w = wait (&s)) < 0 && errno != EINTR) +#else /* HAVE_WAITPID */ + if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR) +#endif /* HAVE_WAITPID */ + return w; + @} while (w != child); +@end example + +You can specify formats for languages other than C by using line group +formats and line formats, as described in the next sections. + +@menu +* Line Group Formats:: Formats for general if-then-else line groups. +* Line Formats:: Formats for each line in a line group. +* Detailed If-then-else:: A detailed description of if-then-else format. +* Example If-then-else:: Sample if-then-else format output. +@end menu + +@node Line Group Formats, Line Formats, , If-then-else +@subsection Line Group Formats +@cindex line group formats +@cindex formats for if-then-else line groups + +Line group formats let you specify formats suitable for many +applications that allow if-then-else input, including programming +languages and text formatting languages. A line group format specifies +the output format for a contiguous group of similar lines. + +For example, the following command compares the TeX files @file{old} +and @file{new}, and outputs a merged file in which old regions are +surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new +regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. + +@example +diff \ + --old-group-format='\begin@{em@} +%<\end@{em@} +' \ + --new-group-format='\begin@{bf@} +%>\end@{bf@} +' \ + old new +@end example + +The following command is equivalent to the above example, but it is a +little more verbose, because it spells out the default line group formats. + +@example +diff \ + --old-group-format='\begin@{em@} +%<\end@{em@} +' \ + --new-group-format='\begin@{bf@} +%>\end@{bf@} +' \ + --unchanged-group-format='%=' \ + --changed-group-format='\begin@{em@} +%<\end@{em@} +\begin@{bf@} +%>\end@{bf@} +' \ + old new +@end example + +Here is a more advanced example, which outputs a diff listing with +headers containing line numbers in a ``plain English'' style. + +@example +diff \ + --unchanged-group-format='' \ + --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: +%<' \ + --new-group-format='-------- %dN line%(N=1?:s) added after %de: +%>' \ + --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: +%<-------- to: +%>' \ + old new +@end example + +To specify a line group format, use @code{diff} with one of the options +listed below. You can specify up to four line group formats, one for +each kind of line group. You should quote @var{format}, because it +typically contains shell metacharacters. + +@table @samp +@item --old-group-format=@var{format} +These line groups are hunks containing only lines from the first file. +The default old group format is the same as the changed group format if +it is specified; otherwise it is a format that outputs the line group as-is. + +@item --new-group-format=@var{format} +These line groups are hunks containing only lines from the second +file. The default new group format is same as the the changed group +format if it is specified; otherwise it is a format that outputs the +line group as-is. + +@item --changed-group-format=@var{format} +These line groups are hunks containing lines from both files. The +default changed group format is the concatenation of the old and new +group formats. + +@item --unchanged-group-format=@var{format} +These line groups contain lines common to both files. The default +unchanged group format is a format that outputs the line group as-is. +@end table + +In a line group format, ordinary characters represent themselves; +conversion specifications start with @samp{%} and have one of the +following forms. + +@table @samp +@item %< +stands for the lines from the first file, including the trailing newline. +Each line is formatted according to the old line format (@pxref{Line Formats}). + +@item %> +stands for the lines from the second file, including the trailing newline. +Each line is formatted according to the new line format. + +@item %= +stands for the lines common to both files, including the trailing newline. +Each line is formatted according to the unchanged line format. + +@item %% +stands for @samp{%}. + +@item %c'@var{C}' +where @var{C} is a single character, stands for @var{C}. +@var{C} may not be a backslash or an apostrophe. +For example, @samp{%c':'} stands for a colon, even inside +the then-part of an if-then-else format, which a colon would +normally terminate. + +@item %c'\@var{O}' +where @var{O} is a string of 1, 2, or 3 octal digits, +stands for the character with octal code @var{O}. +For example, @samp{%c'\0'} stands for a null character. + +@item @var{F}@var{n} +where @var{F} is a @code{printf} conversion specification and @var{n} is one +of the following letters, stands for @var{n}'s value formatted with @var{F}. + +@table @samp +@item e +The line number of the line just before the group in the old file. + +@item f +The line number of the first line in the group in the old file; +equals @var{e} + 1. + +@item l +The line number of the last line in the group in the old file. + +@item m +The line number of the line just after the group in the old file; +equals @var{l} + 1. + +@item n +The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. + +@item E, F, L, M, N +Likewise, for lines in the new file. + +@end table + +The @code{printf} conversion specification can be @samp{%d}, +@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, +lower case hexadecimal, or upper case hexadecimal output +respectively. After the @samp{%} the following options can appear in +sequence: a @samp{-} specifying left-justification; an integer +specifying the minimum field width; and a period followed by an +optional integer specifying the minimum number of digits. +For example, @samp{%5dN} prints the number of new lines in the group +in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. + +@item (@var{A}=@var{B}?@var{T}:@var{E}) +If @var{A} equals @var{B} then @var{T} else @var{E}. +@var{A} and @var{B} are each either a decimal constant +or a single letter interpreted as above. +This format spec is equivalent to @var{T} if +@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. + +For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to +@samp{no lines} if @var{N} (the number of lines in the group in the the +new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} +otherwise. +@end table + +@node Line Formats, Detailed If-then-else, Line Group Formats, If-then-else +@subsection Line Formats +@cindex line formats + +Line formats control how each line taken from an input file is +output as part of a line group in if-then-else format. + +For example, the following command outputs text with a one-column +change indicator to the left of the text. The first column of output +is @samp{-} for deleted lines, @samp{|} for added lines, and a space +for unchanged lines. The formats contain newline characters where +newlines are desired on output. + +@example +diff \ + --old-line-format='-%l +' \ + --new-line-format='|%l +' \ + --unchanged-line-format=' %l +' \ + old new +@end example + +To specify a line format, use one of the following options. You should +quote @var{format}, since it often contains shell metacharacters. + +@table @samp +@item --old-line-format=@var{format} +formats lines just from the first file. + +@item --new-line-format=@var{format} +formats lines just from the second file. + +@item --unchanged-line-format=@var{format} +formats lines common to both files. + +@item --line-format=@var{format} +formats all lines; in effect, it sets all three above options simultaneously. +@end table + +In a line format, ordinary characters represent themselves; +conversion specifications start with @samp{%} and have one of the +following forms. + +@table @samp +@item %l +stands for the the contents of the line, not counting its trailing +newline (if any). This format ignores whether the line is incomplete; +@xref{Incomplete Lines}. + +@item %L +stands for the the contents of the line, including its trailing newline +(if any). If a line is incomplete, this format preserves its +incompleteness. + +@item %% +stands for @samp{%}. + +@item %c'@var{C}' +where @var{C} is a single character, stands for @var{C}. +@var{C} may not be a backslash or an apostrophe. +For example, @samp{%c':'} stands for a colon. + +@item %c'\@var{O}' +where @var{O} is a string of 1, 2, or 3 octal digits, +stands for the character with octal code @var{O}. +For example, @samp{%c'\0'} stands for a null character. + +@item @var{F}n +where @var{F} is a @code{printf} conversion specification, +stands for the line number formatted with @var{F}. +For example, @samp{%.5dn} prints the line number using the +@code{printf} format @code{"%.5d"}. @xref{Line Group Formats}, for +more about printf conversion specifications. + +@end table + +The default line format is @samp{%l} followed by a newline character. + +If the input contains tab characters and it is important that they line +up on output, you should ensure that @samp{%l} or @samp{%L} in a line +format is just after a tab stop (e.g.@: by preceding @samp{%l} or +@samp{%L} with a tab character), or you should use the @samp{-t} or +@samp{--expand-tabs} option. + +Taken together, the line and line group formats let you specify many +different formats. For example, the following command uses a format +similar to @code{diff}'s normal format. You can tailor this command +to get fine control over @code{diff}'s output. + +@example +diff \ + --old-line-format='< %l +' \ + --new-line-format='> %l +' \ + --old-group-format='%df%(f=l?:,%dl)d%dE +%<' \ + --new-group-format='%dea%dF%(F=L?:,%dL) +%>' \ + --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) +%<--- +%>' \ + --unchanged-group-format='' \ + old new +@end example + +@node Detailed If-then-else, Example If-then-else, Line Formats, If-then-else +@subsection Detailed Description of If-then-else Format + +For lines common to both files, @code{diff} uses the unchanged line +group format. For each hunk of differences in the merged output +format, if the hunk contains only lines from the first file, +@code{diff} uses the old line group format; if the hunk contains only +lines from the second file, @code{diff} uses the new group format; +otherwise, @code{diff} uses the changed group format. + +The old, new, and unchanged line formats specify the output format of +lines from the first file, lines from the second file, and lines common +to both files, respectively. + +The option @samp{--ifdef=@var{name}} is equivalent to +the following sequence of options using shell syntax: + +@example +--old-group-format='#ifndef @var{name} +%<#endif /* not @var{name} */ +' \ +--new-group-format='#ifdef @var{name} +%>#endif /* @var{name} */ +' \ +--unchanged-group-format='%=' \ +--changed-group-format='#ifndef @var{name} +%<#else /* @var{name} */ +%>#endif /* @var{name} */ +' +@end example + +You should carefully check the @code{diff} output for proper nesting. +For example, when using the the @samp{-D @var{name}} or +@samp{--ifdef=@var{name}} option, you should check that if the +differing lines contain any of the C preprocessor directives +@samp{#ifdef}, @samp{#ifndef}, @samp{#else}, @samp{#elif}, or +@samp{#endif}, they are nested properly and match. If they don't, you +must make corrections manually. It is a good idea to carefully check +the resulting code anyway to make sure that it really does what you +want it to; depending on how the input files were produced, the output +might contain duplicate or otherwise incorrect code. + +The @code{patch} @samp{-D @var{name}} option behaves just like +the @code{diff} @samp{-D @var{name}} option, except it operates on +a file and a diff to produce a merged file; @xref{patch Options}. + +@node Example If-then-else, , Detailed If-then-else, If-then-else +@subsection An Example of If-then-else Format + +Here is the output of @samp{diff -DTWO lao tzu} (@pxref{Sample +diff Input}, for the complete contents of the two files): + +@example +#ifndef TWO +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +#endif /* not TWO */ +The Nameless is the origin of Heaven and Earth; +#ifndef TWO +The Named is the mother of all things. +#else /* TWO */ +The named is the mother of all things. + +#endif /* TWO */ +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their outcome. +The two are the same, +But after they are produced, + they have different names. +#ifdef TWO +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +#endif /* TWO */ +@end example + +@node Comparing Directories, Adjusting Output, Output Formats, Top +@chapter Comparing Directories + +You can use @code{diff} to compare some or all of the files in two +directory trees. When both file name arguments to @code{diff} are +directories, it compares each file that is contained in both +directories, examining file names in alphabetical order. Normally +@code{diff} is silent about pairs of files that contain no differences, +but if you use the @samp{-s} or @samp{--report-identical-files} option, +it reports pairs of identical files. Normally @code{diff} reports +subdirectories common to both directories without comparing +subdirectories' files, but if you use the @samp{-r} or +@samp{--recursive} option, it compares every corresponding pair of files +in the directory trees, as many levels deep as they go. + +For file names that are in only one of the directories, @code{diff} +normally does not show the contents of the file that exists; it reports +only that the file exists in that directory and not in the other. You +can make @code{diff} act as though the file existed but was empty in the +other directory, so that it outputs the entire contents of the file that +actually exists. (It is output as either an insertion or a +deletion, depending on whether it is in the first or the second +directory given.) To do this, use the @samp{-N} or @samp{--new-file} +option. + +If the older directory contains one or more large files that are not in +the newer directory, you can make the patch smaller by using the +@samp{-P} or @samp{--unidirectional-new-file} option instead of @samp{-N}. +This option is like @samp{-N} except that it only inserts the contents +of files that appear in the second directory but not the first (that is, +files that were added). At the top of the patch, write instructions for +the user applying the patch to remove the files that were deleted before +applying the patch. @xref{Making Patches}, for more discussion of +making patches for distribution. + +To ignore some files while comparing directories, use the @samp{-x +@var{pattern}} or @samp{--exclude=@var{pattern}} option. This option +ignores any files or subdirectories whose base names match the shell +pattern @var{pattern}. Unlike in the shell, a period at the start of +the base of a file name matches a wildcard at the start of a pattern. +You should enclose @var{pattern} in quotes so that the shell does not +expand it. For example, the option @samp{-x '*.[ao]'} ignores any file +whose name ends with @samp{.a} or @samp{.o}. + +This option accumulates if you specify it more than once. For example, +using the options @samp{-x 'RCS' -x '*,v'} ignores any file or +subdirectory whose base name is @samp{RCS} or ends with @samp{,v}. + +If you need to give this option many times, you can instead put the +patterns in a file, one pattern per line, and use the @samp{-X +@var{file}} or @samp{--exclude-from=@var{file}} option. + +If you have been comparing two directories and stopped partway through, +later you might want to continue where you left off. You can do this by +using the @samp{-S @var{file}} or @samp{--starting-file=@var{file}} +option. This compares only the file @var{file} and all alphabetically +later files in the topmost directory level. + +@node Adjusting Output, diff Performance, Comparing Directories, Top +@chapter Making @code{diff} Output Prettier + +@code{diff} provides several ways to adjust the appearance of its output. +These adjustments can be applied to any output format. + +@menu +* Tabs:: Preserving the alignment of tabstops. +* Pagination:: Page numbering and timestamping @code{diff} output. +@end menu + +@node Tabs, Pagination, , Adjusting Output +@section Preserving Tabstop Alignment +@cindex tabstop alignment +@cindex aligning tabstops + +The lines of text in some of the @code{diff} output formats are preceded +by one or two characters that indicate whether the text is inserted, +deleted, or changed. The addition of those characters can cause tabs to +move to the next tabstop, throwing off the alignment of columns in the +line. GNU @code{diff} provides two ways to make tab-aligned columns +line up correctly. + +The first way is to have @code{diff} convert all tabs into the correct +number of spaces before outputting them; select this method with the +@samp{-t} or @samp{--expand-tabs} option. @code{diff} assumes that +tabstops are set every 8 columns. To use this form of output with +@code{patch}, you must give @code{patch} the @samp{-l} or +@samp{--ignore-white-space} option (@pxref{Changed White Space}, for more +information). + +The other method for making tabs line up correctly is to add a tab +character instead of a space after the indicator character at the +beginning of the line. This ensures that all following tab characters +are in the same position relative to tabstops that they were in the +original files, so that the output is aligned correctly. Its +disadvantage is that it can make long lines too long to fit on one line +of the screen or the paper. It also does not work with the unified +output format, which does not have a space character after the change +type indicator character. Select this method with the @samp{-T} or +@samp{--initial-tab} option. + +@node Pagination, , Tabs, Adjusting Output +@section Paginating @code{diff} Output +@cindex paginating @code{diff} output + +It can be convenient to have long output page-numbered and time-stamped. +The @samp{-l} and @samp{--paginate} options do this by sending the +@code{diff} output through the @code{pr} program. Here is what the page +header might look like for @samp{diff -lc lao tzu}: + +@example +Mar 11 13:37 1991 diff -lc lao tzu Page 1 +@end example + +@node diff Performance, Comparing Three Files, Adjusting Output, Top +@chapter @code{diff} Performance Tradeoffs +@cindex performance of @code{diff} + +GNU @code{diff} runs quite efficiently; however, in some circumstances +you can cause it to run faster or produce a more compact set of changes. +There are two ways that you can affect the performance of GNU +@code{diff} by changing the way it compares files. + +Performance has more than one dimension. These options improve one +aspect of performance at the cost of another, or they improve +performance in some cases while hurting it in others. + +The way that GNU @code{diff} determines which lines have changed always +comes up with a near-minimal set of differences. Usually it is good +enough for practical purposes. If the @code{diff} output is large, you +might want @code{diff} to use a modified algorithm that sometimes +produces a smaller set of differences. The @samp{-d} or +@samp{--minimal} option does this; however, it can also cause +@code{diff} to run more slowly than usual, so it is not the default +behavior. + +When the files you are comparing are large and have small groups of +changes scattered throughout them, you can use the @samp{-H} or +@samp{--speed-large-files} option to make a different modification to +the algorithm that @code{diff} uses. If the input files have a constant +small density of changes, this option speeds up the comparisons without +changing the output. If not, @code{diff} might produce a larger set of +differences; however, the output will still be correct. + +Normally @code{diff} discards the prefix and suffix that is common to +both files before it attempts to find a minimal set of differences. +This makes @code{diff} run faster, but occasionally it may produce +non-minimal output. The @samp{--horizon-lines=@var{lines}} option +prevents @code{diff} from discarding the last @var{lines} lines of the +prefix and the first @var{lines} lines of the suffix. This gives +@code{diff} further opportunities to find a minimal output. + +@node Comparing Three Files, diff3 Merging, diff Performance, Top +@chapter Comparing Three Files +@cindex comparing three files +@cindex format of @code{diff3} output + +Use the program @code{diff3} to compare three files and show any +differences among them. (@code{diff3} can also merge files; see +@ref{diff3 Merging}). + +The ``normal'' @code{diff3} output format shows each hunk of +differences without surrounding context. Hunks are labeled depending +on whether they are two-way or three-way, and lines are annotated by +their location in the input files. + +@xref{Invoking diff3}, for more information on how to run @code{diff3}. + +@menu +* Sample diff3 Input:: Sample @code{diff3} input for examples. +* Detailed diff3 Normal:: A detailed description of normal output format. +* diff3 Hunks:: The format of normal output format. +* Example diff3 Normal:: Sample output in the normal format. +@end menu + +@node Sample diff3 Input, Detailed diff3 Normal, , Comparing Three Files +@section A Third Sample Input File +@cindex @code{diff3} sample input +@cindex sample input for @code{diff3} + +Here is a third sample file that will be used in examples to illustrate +the output of @code{diff3} and how various options can change it. The +first two files are the same that we used for @code{diff} (@pxref{Sample +diff Input}). This is the third sample file, called @file{tao}: + +@example +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +The Nameless is the origin of Heaven and Earth; +The named is the mother of all things. + +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their result. +The two are the same, +But after they are produced, + they have different names. + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +@end example + +@node Detailed diff3 Normal, diff3 Hunks, Sample diff3 Input, Comparing Three Files +@section Detailed Description of @code{diff3} Normal Format + +Each hunk begins with a line marked @samp{====}. Three-way hunks have +plain @samp{====} lines, and two-way hunks have @samp{1}, @samp{2}, or +@samp{3} appended to specify which of the three input files differ in +that hunk. The hunks contain copies of two or three sets of input +lines each preceded by one or two commands identifying where the lines +came from. + +Normally, two spaces precede each copy of an input line to distinguish +it from the commands. But with the @samp{-T} or @samp{--initial-tab} +option, @code{diff3} uses a tab instead of two spaces; this lines up +tabs correctly. @xref{Tabs}, for more information. + +Commands take the following forms: + +@table @samp +@item @var{file}:@var{l}a +This hunk appears after line @var{l} of file @var{file}, and +contains no lines in that file. To edit this file to yield the other +files, one must append hunk lines taken from the other files. For +example, @samp{1:11a} means that the hunk follows line 11 in the first +file and contains no lines from that file. + +@item @var{file}:@var{r}c +This hunk contains the lines in the range @var{r} of file @var{file}. +The range @var{r} is a comma-separated pair of line numbers, or just one +number if the range is a singleton. To edit this file to yield the +other files, one must change the specified lines to be the lines taken +from the other files. For example, @samp{2:11,13c} means that the hunk +contains lines 11 through 13 from the second file. +@end table + +If the last line in a set of input lines is incomplete +(@pxref{Incomplete Lines}), it is distinguished on output from a full +line by a following line that starts with @samp{\}. + +@node diff3 Hunks, Example diff3 Normal, Detailed diff3 Normal, Comparing Three Files +@section @code{diff3} Hunks +@cindex hunks for @code{diff3} +@cindex @code{diff3} hunks + +Groups of lines that differ in two or three of the input files are +called @dfn{diff3 hunks}, by analogy with @code{diff} hunks +(@pxref{Hunks}). If all three input files differ in a @code{diff3} +hunk, the hunk is called a @dfn{three-way hunk}; if just two input files +differ, it is a @dfn{two-way hunk}. + +As with @code{diff}, several solutions are possible. When comparing the +files @samp{A}, @samp{B}, and @samp{C}, @code{diff3} normally finds +@code{diff3} hunks by merging the two-way hunks output by the two +commands @samp{diff A B} and @samp{diff A C}. This does not necessarily +minimize the size of the output, but exceptions should be rare. + +For example, suppose @file{F} contains the three lines @samp{a}, +@samp{b}, @samp{f}, @file{G} contains the lines @samp{g}, @samp{b}, +@samp{g}, and @file{H} contains the lines @samp{a}, @samp{b}, +@samp{h}. @samp{diff3 F G H} might output the following: + +@example +====2 +1:1c +3:1c + a +2:1c + g +==== +1:3c + f +2:3c + g +3:3c + h +@end example + +@noindent +because it found a two-way hunk containing @samp{a} in the first and +third files and @samp{g} in the second file, then the single line +@samp{b} common to all three files, then a three-way hunk containing +the last line of each file. + +@node Example diff3 Normal, , diff3 Hunks, Comparing Three Files +@section An Example of @code{diff3} Normal Format + +Here is the output of the command @samp{diff3 lao tzu tao} +(@pxref{Sample diff3 Input}, for the complete contents of the files). +Notice that it shows only the lines that are different among the three +files. + +@example +====2 +1:1,2c +3:1,2c + The Way that can be told of is not the eternal Way; + The name that can be named is not the eternal name. +2:0a +====1 +1:4c + The Named is the mother of all things. +2:2,3c +3:4,5c + The named is the mother of all things. + +====3 +1:8c +2:7c + so we may see their outcome. +3:9c + so we may see their result. +==== +1:11a +2:11,13c + They both may be called deep and profound. + Deeper and more profound, + The door of all subtleties! +3:13,14c + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +@end example + +@node diff3 Merging, Interactive Merging, Comparing Three Files, Top +@chapter Merging From a Common Ancestor +@cindex merging from a common ancestor + +When two people have made changes to copies of the same file, +@code{diff3} can produce a merged output that contains both sets of +changes together with warnings about conflicts. + +One might imagine programs with names like @code{diff4} and @code{diff5} +to compare more than three files simultaneously, but in practice the +need rarely arises. You can use @code{diff3} to merge three or more +sets of changes to a file by merging two change sets at a time. + +@code{diff3} can incorporate changes from two modified versions into a +common preceding version. This lets you merge the sets of changes +represented by the two newer files. Specify the common ancestor version +as the second argument and the two newer versions as the first and third +arguments, like this: + +@example +diff3 @var{mine} @var{older} @var{yours} +@end example + +@noindent +You can remember the order of the arguments by noting that they are in +alphabetical order. + +@cindex conflict +@cindex overlap +You can think of this as subtracting @var{older} from @var{yours} and +adding the result to @var{mine}, or as merging into @var{mine} the +changes that would turn @var{older} into @var{yours}. This merging is +well-defined as long as @var{mine} and @var{older} match in the +neighborhood of each such change. This fails to be true when all three +input files differ or when only @var{older} differs; we call this +a @dfn{conflict}. When all three input files differ, we call the +conflict an @dfn{overlap}. + +@code{diff3} gives you several ways to handle overlaps and conflicts. +You can omit overlaps or conflicts, or select only overlaps, +or mark conflicts with special @samp{<<<<<<<} and @samp{>>>>>>>} lines. + +@code{diff3} can output the merge results as an @code{ed} script that +that can be applied to the first file to yield the merged output. +However, it is usually better to have @code{diff3} generate the merged +output directly; this bypasses some problems with @code{ed}. + +@menu +* Which Changes:: Selecting changes to incorporate. +* Marking Conflicts:: Marking conflicts. +* Bypassing ed:: Generating merged output directly. +* Merging Incomplete Lines:: How @code{diff3} merges incomplete lines. +* Saving the Changed File:: Emulating System V behavior. +@end menu + +@node Which Changes, Marking Conflicts, , diff3 Merging +@section Selecting Which Changes to Incorporate +@cindex overlapping change, selection of +@cindex unmerged change + +You can select all unmerged changes from @var{older} to @var{yours} for merging +into @var{mine} with the @samp{-e} or @samp{--ed} option. You can +select only the nonoverlapping unmerged changes with @samp{-3} or +@samp{--easy-only}, and you can select only the overlapping changes with +@samp{-x} or @samp{--overlap-only}. + +The @samp{-e}, @samp{-3} and @samp{-x} options select only +@dfn{unmerged changes}, i.e.@: changes where @var{mine} and @var{yours} +differ; they ignore changes from @var{older} to @var{yours} where +@var{mine} and @var{yours} are identical, because they assume that such +changes have already been merged. If this assumption is not a safe +one, you can use the @samp{-A} or @samp{--show-all} option +(@pxref{Marking Conflicts}). + +Here is the output of the command @code{diff3} with each of these three +options (@pxref{Sample diff3 Input}, for the complete contents of the files). +Notice that @samp{-e} outputs the union of the disjoint sets of changes +output by @samp{-3} and @samp{-x}. + +Output of @samp{diff3 -e lao tzu tao}: +@example +11a + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +. +8c + so we may see their result. +. +@end example + +Output of @samp{diff3 -3 lao tzu tao}: +@example +8c + so we may see their result. +. +@end example + +Output of @samp{diff3 -x lao tzu tao}: +@example +11a + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +. +@end example + +@node Marking Conflicts, Bypassing ed, Which Changes, diff3 Merging +@section Marking Conflicts +@cindex conflict marking +@cindex @samp{<<<<<<<} for marking conflicts + +@code{diff3} can mark conflicts in the merged output by +bracketing them with special marker lines. A conflict +that comes from two files @var{A} and @var{B} is marked as follows: + +@example +<<<<<<< @var{A} +@r{lines from @var{A}} +======= +@r{lines from @var{B}} +>>>>>>> @var{B} +@end example + +A conflict that comes from three files @var{A}, @var{B} and @var{C} is +marked as follows: + +@example +<<<<<<< @var{A} +@r{lines from @var{A}} +||||||| @var{B} +@r{lines from @var{B}} +======= +@r{lines from @var{C}} +>>>>>>> @var{C} +@end example + +The @samp{-A} or @samp{--show-all} option acts like the @samp{-e} +option, except that it brackets conflicts, and it outputs all changes +from @var{older} to @var{yours}, not just the unmerged changes. Thus, +given the sample input files (@pxref{Sample diff3 Input}), @samp{diff3 +-A lao tzu tao} puts brackets around the conflict where only @file{tzu} +differs: + +@example +<<<<<<< tzu +======= +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +>>>>>>> tao +@end example + +And it outputs the three-way conflict as follows: + +@example +<<<<<<< lao +||||||| tzu +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +======= + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +>>>>>>> tao +@end example + +The @samp{-E} or @samp{--show-overlap} option outputs less information +than the @samp{-A} or @samp{--show-all} option, because it outputs only +unmerged changes, and it never outputs the contents of the second +file. Thus the @samp{-E} option acts like the @samp{-e} option, +except that it brackets the first and third files from three-way +overlapping changes. Similarly, @samp{-X} acts like @samp{-x}, except +it brackets all its (necessarily overlapping) changes. For example, +for the three-way overlapping change above, the @samp{-E} and @samp{-X} +options output the following: + +@example +<<<<<<< lao +======= + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +>>>>>>> tao +@end example + +If you are comparing files that have meaningless or uninformative names, +you can use the @samp{-L @var{label}} or @samp{--label=@var{label}} +option to show alternate names in the @samp{<<<<<<<}, @samp{|||||||} +and @samp{>>>>>>>} brackets. This option can be given up to three +times, once for each input file. Thus @samp{diff3 -A -L X -L Y -L Z A +B C} acts like @samp{diff3 -A A B C}, except that the output looks like +it came from files named @samp{X}, @samp{Y} and @samp{Z} rather than +from files named @samp{A}, @samp{B} and @samp{C}. + +@node Bypassing ed, Merging Incomplete Lines, Marking Conflicts, diff3 Merging +@section Generating the Merged Output Directly +@cindex merged @code{diff3} format + +With the @samp{-m} or @samp{--merge} option, @code{diff3} outputs the +merged file directly. This is more efficient than using @code{ed} to +generate it, and works even with non-text files that @code{ed} would +reject. If you specify @samp{-m} without an @code{ed} script option, +@samp{-A} (@samp{--show-all}) is assumed. + +For example, the command @samp{diff3 -m lao tzu tao} +(@pxref{Sample diff3 Input} for a copy of the input files) would output +the following: + +@example +<<<<<<< tzu +======= +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +>>>>>>> tao +The Nameless is the origin of Heaven and Earth; +The Named is the mother of all things. +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their result. +The two are the same, +But after they are produced, + they have different names. +<<<<<<< lao +||||||| tzu +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +======= + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +>>>>>>> tao +@end example + +@node Merging Incomplete Lines, Saving the Changed File, Bypassing ed, diff3 Merging +@section How @code{diff3} Merges Incomplete Lines +@cindex incomplete line merging + +With @samp{-m}, incomplete lines (@pxref{Incomplete Lines}) are simply +copied to the output as they are found; if the merged output ends in an +conflict and one of the input files ends in an incomplete +line, succeeding @samp{|||||||}, @samp{=======} or @samp{>>>>>>>} +brackets appear somewhere other than the start of a line because +they are appended to the incomplete line. + +Without @samp{-m}, if an @code{ed} script option is specified and an +incomplete line is found, @code{diff3} generates a warning and acts as +if a newline had been present. + +@node Saving the Changed File, , Merging Incomplete Lines, diff3 Merging +@section Saving the Changed File +@cindex System V @code{diff3} compatibility + +Traditional Unix @code{diff3} generates an @code{ed} script without the +trailing @samp{w} and and @samp{q} commands that save the changes. +System V @code{diff3} generates these extra commands. GNU @code{diff3} +normally behaves like traditional Unix @code{diff3}, but with the +@samp{-i} option it behaves like System V @code{diff3} and appends the +@samp{w} and @samp{q} commands. + +The @samp{-i} option requires one of the @code{ed} script options +@samp{-AeExX3}, and is incompatible with the merged output option +@samp{-m}. + +@node Interactive Merging, Merging with patch, diff3 Merging, Top +@chapter Interactive Merging with @code{sdiff} +@cindex diff merging +@cindex interactive merging + +With @code{sdiff}, you can merge two files interactively based on a +side-by-side @samp{-y} format comparison (@pxref{Side by Side}). Use +@samp{-o @var{file}} or @samp{--output=@var{file}} to specify where to +put the merged text. @xref{Invoking sdiff}, for more details on the +options to @code{sdiff}. + +Another way to merge files interactively is to use the Emacs Lisp +package @code{emerge}. @xref{emerge, , emerge, emacs, The GNU Emacs +Manual}, for more information. + +@menu +* sdiff Option Summary::Summary of @code{sdiff} options. +* Merge Commands:: Merging two files interactively. +@end menu + +@node sdiff Option Summary, Merge Commands, , Interactive Merging +@section Specifying @code{diff} Options to @code{sdiff} +@cindex @code{sdiff} output format + +The following @code{sdiff} options have the same meaning as for +@code{diff}. @xref{diff Options}, for the use of these options. + +@example +-a -b -d -i -t -v +-B -H -I @var{regexp} + +--ignore-blank-lines --ignore-case +--ignore-matching-lines=@var{regexp} --ignore-space-change +--left-column --minimal --speed-large-files +--suppress-common-lines --expand-tabs +--text --version --width=@var{columns} +@end example + +For historical reasons, @code{sdiff} has alternate names for some +options. The @samp{-l} option is equivalent to the @samp{--left-column} +option, and similarly @samp{-s} is equivalent to +@samp{--suppress-common-lines}. The meaning of the @code{sdiff} +@samp{-w} and @samp{-W} options is interchanged from that of +@code{diff}: with @code{sdiff}, @samp{-w @var{columns}} is equivalent to +@samp{--width=@var{columns}}, and @samp{-W} is equivalent to +@samp{--ignore-all-space}. @code{sdiff} without the @samp{-o} option is +equivalent to @code{diff} with the @samp{-y} or @samp{--side-by-side} +option (@pxref{Side by Side}). + +@node Merge Commands, , sdiff Option Summary, Interactive Merging +@section Merge Commands +@cindex merge commands +@cindex merging interactively + +Groups of common lines, with a blank gutter, are copied from the first +file to the output. After each group of differing lines, @code{sdiff} +prompts with @samp{%} and pauses, waiting for one of the following +commands. Follow each command with @key{RET}. + +@table @samp +@item e +Discard both versions. +Invoke a text editor on an empty temporary file, +then copy the resulting file to the output. + +@item eb +Concatenate the two versions, edit the result in a temporary file, +then copy the edited result to the output. + +@item el +Edit a copy of the left version, then copy the result to the output. + +@item er +Edit a copy of the right version, then copy the result to the output. + +@item l +Copy the left version to the output. + +@item q +Quit. + +@item r +Copy the right version to the output. + +@item s +Silently copy common lines. + +@item v +Verbosely copy common lines. This is the default. +@end table + +The text editor invoked is specified by the @code{EDITOR} environment +variable if it is set. The default is system-dependent. + +@node Merging with patch, Making Patches, Interactive Merging, Top +@chapter Merging with @code{patch} + +@code{patch} takes comparison output produced by @code{diff} and applies +the differences to a copy of the original file, producing a patched +version. With @code{patch}, you can distribute just the changes to a +set of files instead of distributing the entire file set; your +correspondents can apply @code{patch} to update their copy of the files +with your changes. @code{patch} automatically determines the diff +format, skips any leading or trailing headers, and uses the headers to +determine which file to patch. This lets your correspondents feed an +article or message containing a difference listing directly to +@code{patch}. + +@code{patch} detects and warns about common problems like forward +patches. It saves the original version of the files it patches, and +saves any patches that it could not apply. It can also maintain a +@code{patchlevel.h} file to ensures that your correspondents apply +diffs in the proper order. + +@code{patch} accepts a series of diffs in its standard input, usually +separated by headers that specify which file to patch. It applies +@code{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not +exactly match the original file, @code{patch} uses heuristics to try to +patch the file as well as it can. If no approximate match can be found, +@code{patch} rejects the hunk and skips to the next hunk. @code{patch} +normally replaces each file @var{f} with its new version, saving the +original file in @samp{@var{f}.orig}, and putting reject hunks (if any) +into @samp{@var{f}.rej}. + +@xref{Invoking patch}, for detailed information on the options to +@code{patch}. @xref{Backups}, for more information on how +@code{patch} names backup files. @xref{Rejects}, for more information +on where @code{patch} puts reject hunks. + +@menu +* patch Input:: Selecting the type of @code{patch} input. +* Imperfect:: Dealing with imperfect patches. +* Empty Files:: Removing empty files after patching. +* Multiple Patches:: Handling multiple patches in a file specially. +* patch Messages:: Messages and questions @code{patch} can produce. +@end menu + +@node patch Input, Imperfect, , Merging with patch +@section Selecting the @code{patch} Input Format +@cindex @code{patch} input format + +@code{patch} normally determines which @code{diff} format the patch +file uses by examining its contents. For patch files that contain +particularly confusing leading text, you might need to use one of the +following options to force @code{patch} to interpret the patch file as a +certain format of diff. The output formats listed here are the only +ones that @code{patch} can understand. + +@table @samp +@item -c +@itemx --context +context diff. + +@item -e +@itemx --ed +@code{ed} script. + +@item -n +@itemx --normal +normal diff. + +@item -u +@itemx --unified +unified diff. +@end table + +@node Imperfect, Empty Files, patch Input, Merging with patch +@section Applying Imperfect Patches +@cindex imperfect patch application + +@code{patch} tries to skip any leading text in the patch file, apply the +diff, and then skip any trailing text. Thus you can feed a news article +or mail message directly to @code{patch}, and it should work. If the +entire diff is indented by a constant amount of white space, @code{patch} +automatically ignores the indentation. + +However, certain other types of imperfect input require user +intervention. + +@menu +* Changed White Space:: When tabs and spaces don't match exactly. +* Reversed Patches:: Applying reversed patches correctly. +* Inexact:: Helping @code{patch} find close matches. +@end menu + +@node Changed White Space, Reversed Patches, , Imperfect +@subsection Applying Patches with Changed White Space +@cindex white space in patches + +Sometimes mailers, editors, or other programs change spaces into tabs, +or vice versa. If this happens to a patch file or an input file, the +files might look the same, but @code{patch} will not be able to match +them properly. If this problem occurs, use the @samp{-l} or +@samp{--ignore-white-space} option, which makes @code{patch} compare +white space loosely so that any sequence of white space in the patch file +matches any sequence of white space in the input files. Non-white-space +characters must still match exactly. Each line of the context must +still match a line in the input file. + +@node Reversed Patches, Inexact, Changed White Space, Imperfect +@subsection Applying Reversed Patches +@cindex reversed patches + +Sometimes people run @code{diff} with the new file first instead of +second. This creates a diff that is ``reversed''. To apply such +patches, give @code{patch} the @samp{-R} or @samp{--reverse} option. +@code{patch} then attempts to swap each hunk around before applying it. +Rejects come out in the swapped format. The @samp{-R} option does not +work with @code{ed} scripts because there is too little information in +them to reconstruct the reverse operation. + +Often @code{patch} can guess that the patch is reversed. If the first +hunk of a patch fails, @code{patch} reverses the hunk to see if it can +apply it that way. If it can, @code{patch} asks you if you want to have +the @samp{-R} option set; if it can't, @code{patch} continues to apply +the patch normally. This method cannot detect a reversed patch if it is +a normal diff and the first command is an append (which should have been +a delete) since appends always succeed, because a null context matches +anywhere. But most patches add or change lines rather than delete them, +so most reversed normal diffs begin with a delete, which fails, and +@code{patch} notices. + +If you apply a patch that you have already applied, @code{patch} thinks +it is a reversed patch and offers to un-apply the patch. This could be +construed as a feature. If you did this inadvertently and you don't +want to un-apply the patch, just answer @samp{n} to this offer and to +the subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the +@code{patch} process. + +@node Inexact, , Reversed Patches, Imperfect +@subsection Helping @code{patch} Find Inexact Matches +@cindex inexact patches +@cindex fuzz factor when patching + +For context diffs, and to a lesser extent normal diffs, @code{patch} can +detect when the line numbers mentioned in the patch are incorrect, and +it attempts to find the correct place to apply each hunk of the patch. +As a first guess, it takes the line number mentioned in the hunk, plus +or minus any offset used in applying the previous hunk. If that is not +the correct place, @code{patch} scans both forward and backward for a +set of lines matching the context given in the hunk. + +First @code{patch} looks for a place where all lines of the context +match. If it cannot find such a place, and it is reading a context or +unified diff, and the maximum fuzz factor is set to 1 or more, then +@code{patch} makes another scan, ignoring the first and last line of +context. If that fails, and the maximum fuzz factor is set to 2 or +more, it makes another scan, ignoring the first two and last two lines +of context are ignored. It continues similarly if the maximum fuzz +factor is larger. + +The @samp{-F @var{lines}} or @samp{--fuzz=@var{lines}} option sets the +maximum fuzz factor to @var{lines}. This option only applies to context +and unified diffs; it ignores up to @var{lines} lines while looking for +the place to install a hunk. Note that a larger fuzz factor increases +the odds of making a faulty patch. The default fuzz factor is 2; it may +not be set to more than the number of lines of context in the diff, +ordinarily 3. + +If @code{patch} cannot find a place to install a hunk of the patch, it +writes the hunk out to a reject file (@pxref{Rejects}, for information +on how reject files are named). It writes out rejected hunks in context +format no matter what form the input patch is in. If the input is a +normal or @code{ed} diff, many of the contexts are simply null. The +line numbers on the hunks in the reject file may be different from those +in the patch file: they show the approximate location where @code{patch} +thinks the failed hunks belong in the new file rather than in the old +one. + +As it completes each hunk, @code{patch} tells you whether the hunk +succeeded or failed, and if it failed, on which line (in the new file) +@code{patch} thinks the hunk should go. If this is different from the +line number specified in the diff, it tells you the offset. A single +large offset @emph{may} indicate that @code{patch} installed a hunk in +the wrong place. @code{patch} also tells you if it used a fuzz factor +to make the match, in which case you should also be slightly suspicious. + +@code{patch} cannot tell if the line numbers are off in an @code{ed} +script, and can only detect wrong line numbers in a normal diff when it +finds a change or delete command. It may have the same problem with a +context diff using a fuzz factor equal to or greater than the number of +lines of context shown in the diff (typically 3). In these cases, you +should probably look at a context diff between your original and patched +input files to see if the changes make sense. Compiling without errors +is a pretty good indication that the patch worked, but not a guarantee. + +@code{patch} usually produces the correct results, even when it must +make many guesses. However, the results are guaranteed only when +the patch is applied to an exact copy of the file that the patch was +generated from. + +@node Empty Files, Multiple Patches, Imperfect, Merging with patch +@section Removing Empty Files +@cindex empty files, removing +@cindex removing empty files + +Sometimes when comparing two directories, the first directory contains a +file that the second directory does not. If you give @code{diff} the +@samp{-N} or @samp{--new-file} option, it outputs a diff that deletes +the contents of this file. By default, @code{patch} leaves an empty +file after applying such a diff. The @samp{-E} or +@samp{--remove-empty-files} option to @code{patch} deletes output files +that are empty after applying the diff. + +@node Multiple Patches, patch Messages, Empty Files, Merging with patch +@section Multiple Patches in a File +@cindex multiple patches + +If the patch file contains more than one patch, @code{patch} tries to +apply each of them as if they came from separate patch files. This +means that it determines the name of the file to patch for each patch, +and that it examines the leading text before each patch for file names +and prerequisite revision level (@pxref{Making Patches}, for more on +that topic). + +For the second and subsequent patches in the patch file, you can give +options and another original file name by separating their argument +lists with a @samp{+}. However, the argument list for a second or +subsequent patch may not specify a new patch file, since that does not +make sense. + +For example, to tell @code{patch} to strip the first three slashes from +the name of the first patch in the patch file and none from subsequent +patches, and to use @file{code.c} as the first input file, you can use: + +@example +patch -p3 code.c + -p0 < patchfile +@end example + +The @samp{-S} or @samp{--skip} option ignores the current patch from the +patch file, but continue looking for the next patch in the file. Thus, +to ignore the first and third patches in the patch file, you can use: + +@example +patch -S + + -S + < patch file +@end example + +@node patch Messages, , Multiple Patches, Merging with patch +@section Messages and Questions from @code{patch} +@cindex @code{patch} messages and questions +@cindex diagnostics from @code{patch} +@cindex messages from @code{patch} + +@code{patch} can produce a variety of messages, especially if it has +trouble decoding its input. In a few situations where it's not sure how +to proceed, @code{patch} normally prompts you for more information from +the keyboard. There are options to suppress printing non-fatal messages +and stopping for keyboard input. + +The message @samp{Hmm...} indicates that @code{patch} is reading text in +the patch file, attempting to determine whether there is a patch in that +text, and if so, what kind of patch it is. + +You can inhibit all terminal output from @code{patch}, unless an error +occurs, by using the @samp{-s}, @samp{--quiet}, or @samp{--silent} +option. + +There are two ways you can prevent @code{patch} from asking you any +questions. The @samp{-f} or @samp{--force} option assumes that you know +what you are doing. It assumes the following: + +@itemize @bullet +@item +skip patches that do not contain file names in their headers; + +@item +patch files even though they have the wrong version for the +@samp{Prereq:} line in the patch; + +@item +assume that patches are not reversed even if they look like they are. +@end itemize + +The @samp{-t} or @samp{--batch} option is similar to @samp{-f}, in that +it suppresses questions, but it makes somewhat different assumptions: + +@itemize @bullet +@item +skip patches that do not contain file names in their headers +(the same as @samp{-f}); + +@item +skip patches for which the file has the wrong version for the +@samp{Prereq:} line in the patch; + +@item +assume that patches are reversed if they look like they are. +@end itemize + +@code{patch} exits with a non-zero status if it creates any reject +files. When applying a set of patches in a loop, you should check the +exit status, so you don't apply a later patch to a partially patched +file. + +@node Making Patches, Invoking cmp, Merging with patch, Top +@chapter Tips for Making Patch Distributions +@cindex patch making tips +@cindex tips for patch making + +Here are some things you should keep in mind if you are going to +distribute patches for updating a software package. + +Make sure you have specified the file names correctly, either in a +context diff header or with an @samp{Index:} line. If you are patching +files in a subdirectory, be sure to tell the patch user to specify a +@samp{-p} or @samp{--strip} option as needed. Take care to not send out +reversed patches, since these make people wonder whether they have +already applied the patch. + +To save people from partially applying a patch before other patches that +should have gone before it, you can make the first patch in the patch +file update a file with a name like @file{patchlevel.h} or +@file{version.c}, which contains a patch level or version number. If +the input file contains the wrong version number, @code{patch} will +complain immediately. + +An even clearer way to prevent this problem is to put a @samp{Prereq:} +line before the patch. If the leading text in the patch file contains a +line that starts with @samp{Prereq:}, @code{patch} takes the next word +from that line (normally a version number) and checks whether the next +input file contains that word, preceded and followed by either +white space or a newline. If not, @code{patch} prompts you for +confirmation before proceeding. This makes it difficult to accidentally +apply patches in the wrong order. + +Since @code{patch} does not handle incomplete lines properly, make sure +that all the source files in your program end with a newline whenever +you release a version. + +To create a patch that changes an older version of a package into a +newer version, first make a copy of the older version in a scratch +directory. Typically you do that by unpacking a @code{tar} or +@code{shar} archive of the older version. + +You might be able to reduce the size of the patch by renaming or +removing some files before making the patch. If the older version of +the package contains any files that the newer version does not, or if +any files have been renamed between the two versions, make a list of +@code{rm} and @code{mv} commands for the user to execute in the old +version directory before applying the patch. Then run those commands +yourself in the scratch directory. + +If there are any files that you don't need to include in the patch +because they can easily be rebuilt from other files (for example, +@file{TAGS} and output from @code{yacc} and @code{makeinfo}), replace +the versions in the scratch directory with the newer versions, using +@code{rm} and @code{ln} or @code{cp}. + +Now you can create the patch. The de-facto standard @code{diff} format +for patch distributions is context format with two lines of context, +produced by giving @code{diff} the @samp{-C 2} option. Do not use less +than two lines of context, because @code{patch} typically needs at +least two lines for proper operation. Give @code{diff} the @samp{-P} +option in case the newer version of the package contains any files that +the older one does not. Make sure to specify the scratch directory +first and the newer directory second. + +Add to the top of the patch a note telling the user any @code{rm} and +@code{mv} commands to run before applying the patch. Then you can +remove the scratch directory. + +@node Invoking cmp, Invoking diff, Making Patches, Top +@chapter Invoking @code{cmp} +@cindex invoking @code{cmp} +@cindex @code{cmp} invocation + +The @code{cmp} command compares two files, and if they differ, tells the +first byte and line number where they differ. Its arguments are as +follows: + +@example +cmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file}@var{]} +@end example + +The file name @samp{-} is always the standard input. @code{cmp} also +uses the standard input if one file name is omitted. + +An exit status of 0 means no differences were found, 1 means some +differences were found, and 2 means trouble. + +@menu +* cmp Options:: Summary of options to @code{cmp}. +@end menu + +@node cmp Options, , , Invoking cmp +@section Options to @code{cmp} +@cindex @code{cmp} options +@cindex options for @code{cmp} + +Below is a summary of all of the options that GNU @code{cmp} accepts. +Most options have two equivalent names, one of which is a single letter +preceded by @samp{-}, and the other of which is a long name preceded by +@samp{--}. Multiple single letter options (unless they take an +argument) can be combined into a single command line word: @samp{-cl} is +equivalent to @samp{-c -l}. + +@table @samp +@item -c +Print the differing characters. Display control characters as a +@samp{^} followed by a letter of the alphabet and precede characters +that have the high bit set with @samp{M-} (which stands for ``meta''). + +@item --ignore-initial=@var{bytes} +Ignore any differences in the the first @var{bytes} bytes of the input files. +Treat files with fewer than @var{bytes} bytes as if they are empty. + +@item -l +Print the (decimal) offsets and (octal) values of all differing bytes. + +@item --print-chars +Print the differing characters. Display control characters as a +@samp{^} followed by a letter of the alphabet and precede characters +that have the high bit set with @samp{M-} (which stands for ``meta''). + +@item --quiet +@itemx -s +@itemx --silent +Do not print anything; only return an exit status indicating whether +the files differ. + +@item --verbose +Print the (decimal) offsets and (octal) values of all differing bytes. + +@item -v +@item --version +Output the version number of @code{cmp}. +@end table + +@node Invoking diff, Invoking diff3, Invoking cmp, Top +@chapter Invoking @code{diff} +@cindex invoking @code{diff} +@cindex @code{diff} invocation + +The format for running the @code{diff} command is: + +@example +diff @var{options}@dots{} @var{from-file} @var{to-file} +@end example + +In the simplest case, @code{diff} compares the contents of the two files +@var{from-file} and @var{to-file}. A file name of @samp{-} stands for +text read from the standard input. As a special case, @samp{diff - -} +compares a copy of standard input to itself. + +If @var{from-file} is a directory and @var{to-file} is not, @code{diff} +compares the file in @var{from-file} whose file name is that of @var{to-file}, +and vice versa. The non-directory file must not be @samp{-}. + +If both @var{from-file} and @var{to-file} are directories, +@code{diff} compares corresponding files in both directories, in +alphabetical order; this comparison is not recursive unless the +@samp{-r} or @samp{--recursive} option is given. @code{diff} never +compares the actual contents of a directory as if it were a file. The +file that is fully specified may not be standard input, because standard +input is nameless and the notion of ``file with the same name'' does not +apply. + +@code{diff} options begin with @samp{-}, so normally @var{from-file} and +@var{to-file} may not begin with @samp{-}. However, @samp{--} as an +argument by itself treats the remaining arguments as file names even if +they begin with @samp{-}. + +An exit status of 0 means no differences were found, 1 means some +differences were found, and 2 means trouble. + +@menu +* diff Options:: Summary of options to @code{diff}. +@end menu + +@node diff Options, , , Invoking diff +@section Options to @code{diff} +@cindex @code{diff} options +@cindex options for @code{diff} + +Below is a summary of all of the options that GNU @code{diff} accepts. +Most options have two equivalent names, one of which is a single letter +preceded by @samp{-}, and the other of which is a long name preceded by +@samp{--}. Multiple single letter options (unless they take an +argument) can be combined into a single command line word: @samp{-ac} is +equivalent to @samp{-a -c}. Long named options can be abbreviated to +any unique prefix of their name. Brackets ([ and ]) indicate that an +option takes an optional argument. + +@table @samp +@item -@var{lines} +Show @var{lines} (an integer) lines of context. This option does not +specify an output format by itself; it has no effect unless it is +combined with @samp{-c} (@pxref{Context Format}) or @samp{-u} +(@pxref{Unified Format}). This option is obsolete. For proper +operation, @code{patch} typically needs at least two lines of context. + +@item -a +Treat all files as text and compare them line-by-line, even if they +do not seem to be text. @xref{Binary}. + +@item -b +Ignore changes in amount of white space. @xref{White Space}. + +@item -B +Ignore changes that just insert or delete blank lines. @xref{Blank +Lines}. + +@item --binary +Read and write data in binary mode. @xref{Binary}. + +@item --brief +Report only whether the files differ, not the details of the +differences. @xref{Brief}. + +@item -c +Use the context output format. @xref{Context Format}. + +@item -C @var{lines} +@itemx --context@r{[}=@var{lines}@r{]} +Use the context output format, showing @var{lines} (an integer) lines of +context, or three if @var{lines} is not given. @xref{Context Format}. +For proper operation, @code{patch} typically needs at least two lines of +context. + +@item --changed-group-format=@var{format} +Use @var{format} to output a line group containing differing lines from +both files in if-then-else format. @xref{Line Group Formats}. + +@item -d +Change the algorithm perhaps find a smaller set of changes. This makes +@code{diff} slower (sometimes much slower). @xref{diff Performance}. + +@item -D @var{name} +Make merged @samp{#ifdef} format output, conditional on the preprocessor +macro @var{name}. @xref{If-then-else}. + +@item -e +@itemx --ed +Make output that is a valid @code{ed} script. @xref{ed Scripts}. + +@item --exclude=@var{pattern} +When comparing directories, ignore files and subdirectories whose basenames +match @var{pattern}. @xref{Comparing Directories}. + +@item --exclude-from=@var{file} +When comparing directories, ignore files and subdirectories whose basenames +match any pattern contained in @var{file}. @xref{Comparing Directories}. + +@item --expand-tabs +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. @xref{Tabs}. + +@item -f +Make output that looks vaguely like an @code{ed} script but has changes +in the order they appear in the file. @xref{Forward ed}. + +@item -F @var{regexp} +In context and unified format, for each hunk of differences, show some +of the last preceding line that matches @var{regexp}. @xref{Specified +Headings}. + +@item --forward-ed +Make output that looks vaguely like an @code{ed} script but has changes +in the order they appear in the file. @xref{Forward ed}. + +@item -h +This option currently has no effect; it is present for Unix +compatibility. + +@item -H +Use heuristics to speed handling of large files that have numerous +scattered small changes. @xref{diff Performance}. + +@item --horizon-lines=@var{lines} +Do not discard the last @var{lines} lines of the common prefix +and the first @var{lines} lines of the common suffix. +@xref{diff Performance}. + +@item -i +Ignore changes in case; consider upper- and lower-case letters +equivalent. @xref{Case Folding}. + +@item -I @var{regexp} +Ignore changes that just insert or delete lines that match @var{regexp}. +@xref{Specified Folding}. + +@item --ifdef=@var{name} +Make merged if-then-else output using @var{name}. @xref{If-then-else}. + +@item --ignore-all-space +Ignore white space when comparing lines. @xref{White Space}. + +@item --ignore-blank-lines +Ignore changes that just insert or delete blank lines. @xref{Blank +Lines}. + +@item --ignore-case +Ignore changes in case; consider upper- and lower-case to be the same. +@xref{Case Folding}. + +@item --ignore-matching-lines=@var{regexp} +Ignore changes that just insert or delete lines that match @var{regexp}. +@xref{Specified Folding}. + +@item --ignore-space-change +Ignore changes in amount of white space. +@xref{White Space}. + +@item --initial-tab +Output a tab rather than a space before the text of a line in normal or +context format. This causes the alignment of tabs in the line to look +normal. @xref{Tabs}. + +@item -l +Pass the output through @code{pr} to paginate it. @xref{Pagination}. + +@item -L @var{label} +Use @var{label} instead of the file name in the context format +(@pxref{Context Format}) and unified format (@pxref{Unified Format}) +headers. @xref{RCS}. + +@item --label=@var{label} +Use @var{label} instead of the file name in the context format +(@pxref{Context Format}) and unified format (@pxref{Unified Format}) +headers. + +@item --left-column +Print only the left column of two common lines in side by side format. +@xref{Side by Side Format}. + +@item --line-format=@var{format} +Use @var{format} to output all input lines in if-then-else format. +@xref{Line Formats}. + +@item --minimal +Change the algorithm to perhaps find a smaller set of changes. This +makes @code{diff} slower (sometimes much slower). @xref{diff +Performance}. + +@item -n +Output RCS-format diffs; like @samp{-f} except that each command +specifies the number of lines affected. @xref{RCS}. + +@item -N +@itemx --new-file +In directory comparison, if a file is found in only one directory, +treat it as present but empty in the other directory. @xref{Comparing +Directories}. + +@item --new-group-format=@var{format} +Use @var{format} to output a group of lines taken from just the second +file in if-then-else format. @xref{Line Group Formats}. + +@item --new-line-format=@var{format} +Use @var{format} to output a line taken from just the second file in +if-then-else format. @xref{Line Formats}. + +@item --old-group-format=@var{format} +Use @var{format} to output a group of lines taken from just the first +file in if-then-else format. @xref{Line Group Formats}. + +@item --old-line-format=@var{format} +Use @var{format} to output a line taken from just the first file in +if-then-else format. @xref{Line Formats}. + +@item -p +Show which C function each change is in. @xref{C Function Headings}. + +@item -P +When comparing directories, if a file appears only in the second +directory of the two, treat it as present but empty in the other. +@xref{Comparing Directories}. + +@item --paginate +Pass the output through @code{pr} to paginate it. @xref{Pagination}. + +@item -q +Report only whether the files differ, not the details of the +differences. @xref{Brief}. + +@item -r +When comparing directories, recursively compare any subdirectories +found. @xref{Comparing Directories}. + +@item --rcs +Output RCS-format diffs; like @samp{-f} except that each command +specifies the number of lines affected. @xref{RCS}. + +@item --recursive +When comparing directories, recursively compare any subdirectories +found. @xref{Comparing Directories}. + +@item --report-identical-files +Report when two files are the same. @xref{Comparing Directories}. + +@item -s +Report when two files are the same. @xref{Comparing Directories}. + +@item -S @var{file} +When comparing directories, start with the file @var{file}. This is +used for resuming an aborted comparison. @xref{Comparing Directories}. + +@item --sdiff-merge-assist +Print extra information to help @code{sdiff}. @code{sdiff} uses this +option when it runs @code{diff}. This option is not intended for users +to use directly. + +@item --show-c-function +Show which C function each change is in. @xref{C Function Headings}. + +@item --show-function-line=@var{regexp} +In context and unified format, for each hunk of differences, show some +of the last preceding line that matches @var{regexp}. @xref{Specified +Headings}. + +@item --side-by-side +Use the side by side output format. @xref{Side by Side Format}. + +@item --speed-large-files +Use heuristics to speed handling of large files that have numerous +scattered small changes. @xref{diff Performance}. + +@item --starting-file=@var{file} +When comparing directories, start with the file @var{file}. This is +used for resuming an aborted comparison. @xref{Comparing Directories}. + +@item --suppress-common-lines +Do not print common lines in side by side format. +@xref{Side by Side Format}. + +@item -t +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. @xref{Tabs}. + +@item -T +Output a tab rather than a space before the text of a line in normal or +context format. This causes the alignment of tabs in the line to look +normal. @xref{Tabs}. + +@item --text +Treat all files as text and compare them line-by-line, even if they +do not appear to be text. @xref{Binary}. + +@item -u +Use the unified output format. @xref{Unified Format}. + +@item --unchanged-group-format=@var{format} +Use @var{format} to output a group of common lines taken from both files +in if-then-else format. @xref{Line Group Formats}. + +@item --unchanged-line-format=@var{format} +Use @var{format} to output a line common to both files in if-then-else +format. @xref{Line Formats}. + +@item --unidirectional-new-file +When comparing directories, if a file appears only in the second +directory of the two, treat it as present but empty in the other. +@xref{Comparing Directories}. + +@item -U @var{lines} +@itemx --unified@r{[}=@var{lines}@r{]} +Use the unified output format, showing @var{lines} (an integer) lines of +context, or three if @var{lines} is not given. @xref{Unified Format}. +For proper operation, @code{patch} typically needs at least two lines of +context. + +@item -v +@itemx --version +Output the version number of @code{diff}. + +@item -w +Ignore white space when comparing lines. @xref{White Space}. + +@item -W @var{columns} +@itemx --width=@var{columns} +Use an output width of @var{columns} in side by side format. +@xref{Side by Side Format}. + +@item -x @var{pattern} +When comparing directories, ignore files and subdirectories whose basenames +match @var{pattern}. @xref{Comparing Directories}. + +@item -X @var{file} +When comparing directories, ignore files and subdirectories whose basenames +match any pattern contained in @var{file}. @xref{Comparing Directories}. + +@item -y +Use the side by side output format. @xref{Side by Side Format}. +@end table + +@node Invoking diff3, Invoking patch, Invoking diff, Top +@chapter Invoking @code{diff3} +@cindex invoking @code{diff3} +@cindex @code{diff3} invocation + +The @code{diff3} command compares three files and outputs descriptions +of their differences. Its arguments are as follows: + +@example +diff3 @var{options}@dots{} @var{mine} @var{older} @var{yours} +@end example + +The files to compare are @var{mine}, @var{older}, and @var{yours}. +At most one of these three file names may be @samp{-}, +which tells @code{diff3} to read the standard input for that file. + +An exit status of 0 means @code{diff3} was successful, 1 means some +conflicts were found, and 2 means trouble. + +@menu +* diff3 Options:: Summary of options to @code{diff3}. +@end menu + +@node diff3 Options, , , Invoking diff3 +@section Options to @code{diff3} +@cindex @code{diff3} options +@cindex options for @code{diff3} + +Below is a summary of all of the options that GNU @code{diff3} +accepts. Multiple single letter options (unless they take an argument) +can be combined into a single command line argument. + +@table @samp +@item -a +Treat all files as text and compare them line-by-line, even if they +do not appear to be text. @xref{Binary}. + +@item -A +Incorporate all changes from @var{older} to @var{yours} into @var{mine}, +surrounding all conflicts with bracket lines. +@xref{Marking Conflicts}. + +@item -e +Generate an @code{ed} script that incorporates all the changes from +@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}. + +@item -E +Like @samp{-e}, except bracket lines from overlapping changes' first +and third files. +@xref{Marking Conflicts}. +With @samp{-e}, an overlapping change looks like this: + +@example +<<<<<<< @var{mine} +@r{lines from @var{mine}} +======= +@r{lines from @var{yours}} +>>>>>>> @var{yours} +@end example + +@item --ed +Generate an @code{ed} script that incorporates all the changes from +@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}. + +@item --easy-only +Like @samp{-e}, except output only the nonoverlapping changes. +@xref{Which Changes}. + +@item -i +Generate @samp{w} and @samp{q} commands at the end of the @code{ed} +script for System V compatibility. This option must be combined with +one of the @samp{-AeExX3} options, and may not be combined with @samp{-m}. +@xref{Saving the Changed File}. + +@item --initial-tab +Output a tab rather than two spaces before the text of a line in normal format. +This causes the alignment of tabs in the line to look normal. @xref{Tabs}. + +@item -L @var{label} +@itemx --label=@var{label} +Use the label @var{label} for the brackets output by the @samp{-A}, +@samp{-E} and @samp{-X} options. This option may be given up to three +times, one for each input file. The default labels are the names of +the input files. Thus @samp{diff3 -L X -L Y -L Z -m A B C} acts like +@samp{diff3 -m A B C}, except that the output looks like it came from +files named @samp{X}, @samp{Y} and @samp{Z} rather than from files +named @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}. + +@item -m +@itemx --merge +Apply the edit script to the first file and send the result to standard +output. Unlike piping the output from @code{diff3} to @code{ed}, this +works even for binary files and incomplete lines. @samp{-A} is assumed +if no edit script option is specified. @xref{Bypassing ed}. + +@item --overlap-only +Like @samp{-e}, except output only the overlapping changes. +@xref{Which Changes}. + +@item --show-all +Incorporate all unmerged changes from @var{older} to @var{yours} into +@var{mine}, surrounding all overlapping changes with bracket lines. +@xref{Marking Conflicts}. + +@item --show-overlap +Like @samp{-e}, except bracket lines from overlapping changes' first +and third files. +@xref{Marking Conflicts}. + +@item -T +Output a tab rather than two spaces before the text of a line in normal format. +This causes the alignment of tabs in the line to look normal. @xref{Tabs}. + +@item --text +Treat all files as text and compare them line-by-line, even if they +do not appear to be text. @xref{Binary}. + +@item -v +@itemx --version +Output the version number of @code{diff3}. + +@item -x +Like @samp{-e}, except output only the overlapping changes. +@xref{Which Changes}. + +@item -X +Like @samp{-E}, except output only the overlapping changes. +In other words, like @samp{-x}, except bracket changes as in @samp{-E}. +@xref{Marking Conflicts}. + +@item -3 +Like @samp{-e}, except output only the nonoverlapping changes. +@xref{Which Changes}. +@end table + +@node Invoking patch, Invoking sdiff, Invoking diff3, Top +@chapter Invoking @code{patch} +@cindex invoking @code{patch} +@cindex @code{patch} invocation + +Normally @code{patch} is invoked like this: + +@example +patch <@var{patchfile} +@end example + +The full format for invoking @code{patch} is: + +@example +patch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]} @r{[}+ @var{options}@dots{} @r{[}@var{origfile}@r{]}@r{]}@dots{} +@end example + +If you do not specify @var{patchfile}, or if @var{patchfile} is +@samp{-}, @code{patch} reads the patch (that is, the @code{diff} output) +from the standard input. + +You can specify one or more of the original files as @var{orig} arguments; +each one and options for interpreting it is separated from the others with a +@samp{+}. @xref{Multiple Patches}, for more information. + +If you do not specify an input file on the command line, @code{patch} +tries to figure out from the @dfn{leading text} (any text in the patch +that comes before the @code{diff} output) which file to edit. In the +header of a context or unified diff, @code{patch} looks in lines +beginning with @samp{***}, @samp{---}, or @samp{+++}; among those, it +chooses the shortest name of an existing file. Otherwise, if there is +an @samp{Index:} line in the leading text, @code{patch} tries to use the +file name from that line. If @code{patch} cannot figure out the name of +an existing file from the leading text, it prompts you for the name of +the file to patch. + +If the input file does not exist or is read-only, and a suitable RCS or +SCCS file exists, @code{patch} attempts to check out or get the file +before proceeding. + +By default, @code{patch} replaces the original input file with the +patched version, after renaming the original file into a backup file +(@pxref{Backups}, for a description of how @code{patch} names backup +files). You can also specify where to put the output with the @samp{-o +@var{output-file}} or @samp{--output=@var{output-file}} option. + +@menu +* patch Directories:: Changing directory and stripping directories. +* Backups:: Backup file names. +* Rejects:: Reject file names. +* patch Options:: Summary table of options to @code{patch}. +@end menu + +@node patch Directories, Backups, , Invoking patch +@section Applying Patches in Other Directories +@cindex directories and patch +@cindex patching directories + +The @samp{-d @var{directory}} or @samp{--directory=@var{directory}} +option to @code{patch} makes directory @var{directory} the current +directory for interpreting both file names in the patch file, and file +names given as arguments to other options (such as @samp{-B} and +@samp{-o}). For example, while in a news reading program, you can patch +a file in the @file{/usr/src/emacs} directory directly from the article +containing the patch like this: + +@example +| patch -d /usr/src/emacs +@end example + +Sometimes the file names given in a patch contain leading directories, +but you keep your files in a directory different from the one given in +the patch. In those cases, you can use the +@samp{-p@r{[}@var{number}@r{]}} or @samp{--strip@r{[}=@var{number}@r{]}} +option to set the file name strip count to @var{number}. The strip +count tells @code{patch} how many slashes, along with the directory +names between them, to strip from the front of file names. @samp{-p} +with no @var{number} given is equivalent to @samp{-p0}. By default, +@code{patch} strips off all leading directories, leaving just the base file +names, except that when a file name given in the patch is a relative +file name and all of its leading directories already exist, @code{patch} does +not strip off the leading directory. (A @dfn{relative} file name is one +that does not start with a slash.) + +@code{patch} looks for each file (after any slashes have been stripped) +in the current directory, or if you used the @samp{-d @var{directory}} +option, in that directory. + +For example, suppose the file name in the patch file is +@file{/gnu/src/emacs/etc/NEWS}. Using @samp{-p} or @samp{-p0} gives the +entire file name unmodified, @samp{-p1} gives +@file{gnu/src/emacs/etc/NEWS} (no leading slash), @samp{-p4} gives +@file{etc/NEWS}, and not specifying @samp{-p} at all gives @file{NEWS}. + +@node Backups, Rejects, patch Directories, Invoking patch +@section Backup File Names +@cindex backup file names + +Normally, @code{patch} renames an original input file into a backup file +by appending to its name the extension @samp{.orig}, or @samp{~} on +systems that do not support long file names. The @samp{-b +@var{backup-suffix}} or @samp{--suffix=@var{backup-suffix}} option uses +@var{backup-suffix} as the backup extension instead. + +Alternately, you can specify the extension for backup files with the +@code{SIMPLE_BACKUP_SUFFIX} environment variable, which the options +override. + +@code{patch} can also create numbered backup files the way GNU Emacs +does. With this method, instead of having a single backup of each file, +@code{patch} makes a new backup file name each time it patches a file. +For example, the backups of a file named @file{sink} would be called, +successively, @file{sink.~1~}, @file{sink.~2~}, @file{sink.~3~}, etc. + +The @samp{-V @var{backup-style}} or +@samp{--version-control=@var{backup-style}} option takes as an argument +a method for creating backup file names. You can alternately control +the type of backups that @code{patch} makes with the +@code{VERSION_CONTROL} environment variable, which the @samp{-V} option +overrides. The value of the @code{VERSION_CONTROL} environment variable +and the argument to the @samp{-V} option are like the GNU Emacs +@code{version-control} variable (@pxref{Backups, +emacs, The GNU Emacs Manual}, for more information on backup versions in +Emacs). They also recognize synonyms that are more descriptive. The +valid values are listed below; unique abbreviations are acceptable. + +@table @samp +@item t +@itemx numbered +Always make numbered backups. + +@item nil +@itemx existing +Make numbered backups of files that already have them, simple backups of +the others. This is the default. + +@item never +@itemx simple +Always make simple backups. +@end table + +Alternately, you can tell @code{patch} to prepend a prefix, such as a +directory name, to produce backup file names. The @samp{-B +@var{backup-prefix}} or @samp{--prefix=@var{backup-prefix}} option makes +backup files by prepending @var{backup-prefix} to them. If you use this +option, @code{patch} ignores any @samp{-b} option that you give. + +If the backup file already exists, @code{patch} creates a new backup +file name by changing the first lowercase letter in the last component +of the file name into uppercase. If there are no more lowercase letters +in the name, it removes the first character from the name. It repeats +this process until it comes up with a backup file name that does not +already exist. + +If you specify the output file with the @samp{-o} option, that file is +the one that is backed up, not the input file. + +@node Rejects, patch Options, Backups, Invoking patch +@section Reject File Names +@cindex reject file names + +The names for reject files (files containing patches that @code{patch} +could not find a place to apply) are normally the name of the output +file with @samp{.rej} appended (or @samp{#} on systems that do not +support long file names). + +Alternatively, you can tell @code{patch} to place all of the rejected +patches in a single file. The @samp{-r @var{reject-file}} or +@samp{--reject-file=@var{reject-file}} option uses @var{reject-file} as +the reject file name. + +@node patch Options, , Rejects, Invoking patch +@section Options to @code{patch} +@cindex @code{patch} options +@cindex options for @code{patch} + +Here is a summary of all of the options that @code{patch} accepts. +Older versions of @code{patch} do not accept long-named options or the +@samp{-t}, @samp{-E}, or @samp{-V} options. + +Multiple single-letter options that do not take an argument can be +combined into a single command line argument (with only one dash). +Brackets ([ and ]) indicate that an option takes an optional argument. + +@table @samp +@item -b @var{backup-suffix} +Use @var{backup-suffix} as the backup extension instead of +@samp{.orig} or @samp{~}. @xref{Backups}. + +@item -B @var{backup-prefix} +Use @var{backup-prefix} as a prefix to the backup file name. If this +option is specified, any @samp{-b} option is ignored. @xref{Backups}. + +@item --batch +Do not ask any questions. @xref{patch Messages}. + +@item -c +@itemx --context +Interpret the patch file as a context diff. @xref{patch Input}. + +@item -d @var{directory} +@itemx --directory=@var{directory} +Makes directory @var{directory} the current directory for interpreting +both file names in the patch file, and file names given as arguments to +other options. @xref{patch Directories}. + +@item -D @var{name} +Make merged if-then-else output using @var{format}. @xref{If-then-else}. + +@item --debug=@var{number} +Set internal debugging flags. Of interest only to @code{patch} +patchers. + +@item -e +@itemx --ed +Interpret the patch file as an @code{ed} script. @xref{patch Input}. + +@item -E +Remove output files that are empty after the patches have been applied. +@xref{Empty Files}. + +@item -f +Assume that the user knows exactly what he or she is doing, and do not +ask any questions. @xref{patch Messages}. + +@item -F @var{lines} +Set the maximum fuzz factor to @var{lines}. @xref{Inexact}. + +@item --force +Assume that the user knows exactly what he or she is doing, and do not +ask any questions. @xref{patch Messages}. + +@item --forward +Ignore patches that @code{patch} thinks are reversed or already applied. +See also @samp{-R}. @xref{Reversed Patches}. + +@item --fuzz=@var{lines} +Set the maximum fuzz factor to @var{lines}. @xref{Inexact}. + +@item --help +Print a summary of the options that @code{patch} recognizes, then exit. + +@item --ifdef=@var{name} +Make merged if-then-else output using @var{format}. @xref{If-then-else}. + +@item --ignore-white-space +@itemx -l +Let any sequence of white space in the patch file match any sequence of +white space in the input file. @xref{Changed White Space}. + +@item -n +@itemx --normal +Interpret the patch file as a normal diff. @xref{patch Input}. + +@item -N +Ignore patches that @code{patch} thinks are reversed or already applied. +See also @samp{-R}. @xref{Reversed Patches}. + +@item -o @var{output-file} +@itemx --output=@var{output-file} +Use @var{output-file} as the output file name. @xref{patch Options}. + +@item -p@r{[}@var{number}@r{]} +Set the file name strip count to @var{number}. @xref{patch Directories}. + +@item --prefix=@var{backup-prefix} +Use @var{backup-prefix} as a prefix to the backup file name. If this +option is specified, any @samp{-b} option is ignored. @xref{Backups}. + +@item --quiet +Work silently unless an error occurs. @xref{patch Messages}. + +@item -r @var{reject-file} +Use @var{reject-file} as the reject file name. @xref{Rejects}. + +@item -R +Assume that this patch was created with the old and new files swapped. +@xref{Reversed Patches}. + +@item --reject-file=@var{reject-file} +Use @var{reject-file} as the reject file name. @xref{Rejects}. + +@item --remove-empty-files +Remove output files that are empty after the patches have been applied. +@xref{Empty Files}. + +@item --reverse +Assume that this patch was created with the old and new files swapped. +@xref{Reversed Patches}. + +@item -s +Work silently unless an error occurs. @xref{patch Messages}. + +@item -S +Ignore this patch from the patch file, but continue looking for the next +patch in the file. @xref{Multiple Patches}. + +@item --silent +Work silently unless an error occurs. @xref{patch Messages}. + +@item --skip +Ignore this patch from the patch file, but continue looking for the next +patch in the file. @xref{Multiple Patches}. + +@item --strip@r{[}=@var{number}@r{]} +Set the file name strip count to @var{number}. @xref{patch Directories}. + +@item --suffix=@var{backup-suffix} +Use @var{backup-suffix} as the backup extension instead of +@samp{.orig} or @samp{~}. @xref{Backups}. + +@item -t +Do not ask any questions. @xref{patch Messages}. + +@item -u +@itemx --unified +Interpret the patch file as a unified diff. @xref{patch Input}. + +@item -v +Output the revision header and patch level of @code{patch}. + +@item -V @var{backup-style} +Select the kind of backups to make. @xref{Backups}. + +@item --version +Output the revision header and patch level of @code{patch}, then exit. + +@item --version=control=@var{backup-style} +Select the kind of backups to make. @xref{Backups}. + +@item -x @var{number} +Set internal debugging flags. Of interest only to @code{patch} +patchers. +@end table + +@node Invoking sdiff, Incomplete Lines, Invoking patch, Top +@chapter Invoking @code{sdiff} +@cindex invoking @code{sdiff} +@cindex @code{sdiff} invocation + +The @code{sdiff} command merges two files and interactively outputs the +results. Its arguments are as follows: + +@example +sdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file} +@end example + +This merges @var{from-file} with @var{to-file}, with output to @var{outfile}. +If @var{from-file} is a directory and @var{to-file} is not, @code{sdiff} +compares the file in @var{from-file} whose file name is that of @var{to-file}, +and vice versa. @var{from-file} and @var{to-file} may not both be +directories. + +@code{sdiff} options begin with @samp{-}, so normally @var{from-file} +and @var{to-file} may not begin with @samp{-}. However, @samp{--} as an +argument by itself treats the remaining arguments as file names even if +they begin with @samp{-}. You may not use @samp{-} as an input file. + +An exit status of 0 means no differences were found, 1 means some +differences were found, and 2 means trouble. + +@code{sdiff} without @samp{-o} (or @samp{--output}) produces a +side-by-side difference. This usage is obsolete; use @samp{diff +--side-by-side} instead. + +@menu +* sdiff Options:: Summary of options to @code{diff}. +@end menu + +@node sdiff Options, , , Invoking sdiff +@section Options to @code{sdiff} +@cindex @code{sdiff} options +@cindex options for @code{sdiff} + +Below is a summary of all of the options that GNU @code{sdiff} accepts. +Each option has two equivalent names, one of which is a single +letter preceded by @samp{-}, and the other of which is a long name +preceded by @samp{--}. Multiple single letter options (unless they take +an argument) can be combined into a single command line argument. Long +named options can be abbreviated to any unique prefix of their name. + +@table @samp +@item -a +Treat all files as text and compare them line-by-line, even if they +do not appear to be text. @xref{Binary}. + +@item -b +Ignore changes in amount of white space. @xref{White Space}. + +@item -B +Ignore changes that just insert or delete blank lines. @xref{Blank +Lines}. + +@item -d +Change the algorithm to perhaps find a smaller set of changes. This +makes @code{sdiff} slower (sometimes much slower). @xref{diff +Performance}. + +@item -H +Use heuristics to speed handling of large files that have numerous +scattered small changes. @xref{diff Performance}. + +@item --expand-tabs +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. @xref{Tabs}. + +@item -i +Ignore changes in case; consider upper- and lower-case to be the same. +@xref{Case Folding}. + +@item -I @var{regexp} +Ignore changes that just insert or delete lines that match @var{regexp}. +@xref{Specified Folding}. + +@item --ignore-all-space +Ignore white space when comparing lines. @xref{White Space}. + +@item --ignore-blank-lines +Ignore changes that just insert or delete blank lines. @xref{Blank +Lines}. + +@item --ignore-case +Ignore changes in case; consider upper- and lower-case to be the same. +@xref{Case Folding}. + +@item --ignore-matching-lines=@var{regexp} +Ignore changes that just insert or delete lines that match @var{regexp}. +@xref{Specified Folding}. + +@item --ignore-space-change +Ignore changes in amount of white space. +@xref{White Space}. + +@item -l +@itemx --left-column +Print only the left column of two common lines. +@xref{Side by Side Format}. + +@item --minimal +Change the algorithm to perhaps find a smaller set of changes. This +makes @code{sdiff} slower (sometimes much slower). @xref{diff +Performance}. + +@item -o @var{file} +@itemx --output=@var{file} +Put merged output into @var{file}. This option is required for merging. + +@item -s +@itemx --suppress-common-lines +Do not print common lines. @xref{Side by Side Format}. + +@item --speed-large-files +Use heuristics to speed handling of large files that have numerous +scattered small changes. @xref{diff Performance}. + +@item -t +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. @xref{Tabs}. + +@item --text +Treat all files as text and compare them line-by-line, even if they +do not appear to be text. @xref{Binary}. + +@item -v +@itemx --version +Output the version number of @code{sdiff}. + +@item -w @var{columns} +@itemx --width=@var{columns} +Use an output width of @var{columns}. @xref{Side by Side Format}. +Note that for historical reasons, this option is @samp{-W} in @code{diff}, +@samp{-w} in @code{sdiff}. + +@item -W +Ignore horizontal white space when comparing lines. @xref{White Space}. +Note that for historical reasons, this option is @samp{-w} in @code{diff}, +@samp{-W} in @code{sdiff}. +@end table + +@node Incomplete Lines, Projects, Invoking sdiff, Top +@chapter Incomplete Lines +@cindex incomplete lines +@cindex full lines +@cindex newline treatment by @code{diff} + +When an input file ends in a non-newline character, its last line is +called an @dfn{incomplete line} because its last character is not a +newline. All other lines are called @dfn{full lines} and end in a +newline character. Incomplete lines do not match full lines unless +differences in white space are ignored (@pxref{White Space}). + +An incomplete line is normally distinguished on output from a full line +by a following line that starts with @samp{\}. However, the RCS format +(@pxref{RCS}) outputs the incomplete line as-is, without any trailing +newline or following line. The side by side format normally represents +incomplete lines as-is, but in some cases uses a @samp{\} or @samp{/} +gutter marker; @xref{Side by Side}. The if-then-else line format +preserves a line's incompleteness with @samp{%L}, and discards the +newline with @samp{%l}; @xref{Line Formats}. Finally, with the +@code{ed} and forward @code{ed} output formats (@pxref{Output Formats}) +@code{diff} cannot represent an incomplete line, so it pretends there +was a newline and reports an error. + +For example, suppose @file{F} and @file{G} are one-byte files that +contain just @samp{f} and @samp{g}, respectively. Then @samp{diff F G} +outputs + +@example +1c1 +< f +\ No newline at end of file +--- +> g +\ No newline at end of file +@end example + +@noindent +(The exact message may differ in non-English locales.) +@samp{diff -n F G} outputs the following without a trailing newline: + +@example +d1 1 +a1 1 +g +@end example + +@samp{diff -e F G} reports two errors and outputs the following: + +@example +1c +g +. +@end example + +@node Projects, Concept Index, Incomplete Lines, Top +@chapter Future Projects + +Here are some ideas for improving GNU @code{diff} and @code{patch}. The +GNU project has identified some improvements as potential programming +projects for volunteers. You can also help by reporting any bugs that +you find. + +If you are a programmer and would like to contribute something to the +GNU project, please consider volunteering for one of these projects. If +you are seriously contemplating work, please write to +@samp{gnu@@prep.ai.mit.edu} to coordinate with other volunteers. + +@menu +* Shortcomings:: Suggested projects for improvements. +* Bugs:: Reporting bugs. +@end menu + +@node Shortcomings, Bugs, , Projects +@section Suggested Projects for Improving GNU @code{diff} and @code{patch} +@cindex projects for directories + +One should be able to use GNU @code{diff} to generate a patch from any +pair of directory trees, and given the patch and a copy of one such +tree, use @code{patch} to generate a faithful copy of the other. +Unfortunately, some changes to directory trees cannot be expressed using +current patch formats; also, @code{patch} does not handle some of the +existing formats. These shortcomings motivate the following suggested +projects. + +@menu +* Changing Structure:: Handling changes to the directory structure. +* Special Files:: Handling symbolic links, device special files, etc. +* Unusual File Names:: Handling file names that contain unusual characters. +* Arbitrary Limits:: Patching non-text files. +* Large Files:: Handling files that do not fit in memory. +* Ignoring Changes:: Ignoring certain changes while showing others. +@end menu + +@node Changing Structure, Special Files, , Shortcomings +@subsection Handling Changes to the Directory Structure +@cindex directory structure changes + +@code{diff} and @code{patch} do not handle some changes to directory +structure. For example, suppose one directory tree contains a directory +named @samp{D} with some subsidiary files, and another contains a file +with the same name @samp{D}. @samp{diff -r} does not output enough +information for @code{patch} to transform the the directory subtree into +the file. + +There should be a way to specify that a file has been deleted without +having to include its entire contents in the patch file. There should +also be a way to tell @code{patch} that a file was renamed, even if +there is no way for @code{diff} to generate such information. + +These problems can be fixed by extending the @code{diff} output format +to represent changes in directory structure, and extending @code{patch} +to understand these extensions. + +@node Special Files, Unusual File Names, Changing Structure, Shortcomings +@subsection Files that are Neither Directories Nor Regular Files +@cindex special files + +Some files are neither directories nor regular files: they are unusual +files like symbolic links, device special files, named pipes, and +sockets. Currently, @code{diff} treats symbolic links like regular files; +it treats other special files like regular files if they are specified +at the top level, but simply reports their presence when comparing +directories. This means that @code{patch} cannot represent changes +to such files. For example, if you change which file a symbolic link +points to, @code{diff} outputs the difference between the two files, +instead of the change to the symbolic link. + +@c This might not be a good idea; is it wise for root to install devices +@c this way? +@code{diff} should optionally report changes to special files specially, +and @code{patch} should be extended to understand these extensions. + +@node Unusual File Names, Arbitrary Limits, Special Files, Shortcomings +@subsection File Names that Contain Unusual Characters +@cindex file names with unusual characters + +When a file name contains an unusual character like a newline or +white space, @samp{diff -r} generates a patch that @code{patch} cannot +parse. The problem is with format of @code{diff} output, not just with +@code{patch}, because with odd enough file names one can cause +@code{diff} to generate a patch that is syntactically correct but +patches the wrong files. The format of @code{diff} output should be +extended to handle all possible file names. + +@node Arbitrary Limits, Large Files, Unusual File Names, Shortcomings +@subsection Arbitrary Limits +@cindex binary file patching + +GNU @code{diff} can analyze files with arbitrarily long lines and files +that end in incomplete lines. However, @code{patch} cannot patch such +files. The @code{patch} internal limits on line lengths should be +removed, and @code{patch} should be extended to parse @code{diff} +reports of incomplete lines. + +@node Large Files, Ignoring Changes, Arbitrary Limits, Shortcomings +@subsection Handling Files that Do Not Fit in Memory +@cindex large files + +@code{diff} operates by reading both files into memory. This method +fails if the files are too large, and @code{diff} should have a fallback. + +One way to do this is to scan the files sequentially to compute hash +codes of the lines and put the lines in equivalence classes based only +on hash code. Then compare the files normally. This does produce some +false matches. + +Then scan the two files sequentially again, checking each match to see +whether it is real. When a match is not real, mark both the +``matching'' lines as changed. Then build an edit script as usual. + +The output routines would have to be changed to scan the files +sequentially looking for the text to print. + +@node Ignoring Changes,, Large Files, Shortcomings +@subsection Ignoring Certain Changes + +It would be nice to have a feature for specifying two strings, one in +@var{from-file} and one in @var{to-file}, which should be considered to +match. Thus, if the two strings are @samp{foo} and @samp{bar}, then if +two lines differ only in that @samp{foo} in file 1 corresponds to +@samp{bar} in file 2, the lines are treated as identical. + +It is not clear how general this feature can or should be, or +what syntax should be used for it. + +@node Bugs, , Shortcomings, Projects +@section Reporting Bugs +@cindex bug reports +@cindex reporting bugs + +If you think you have found a bug in GNU @code{cmp}, @code{diff}, +@code{diff3}, @code{sdiff}, or @code{patch}, please report it by +electronic mail to @samp{bug-gnu-utils@@prep.ai.mit.edu}. Send as +precise a description of the problem as you can, including sample input +files that produce the bug, if applicable. + +Because Larry Wall has not released a new version of @code{patch} since +mid 1988 and the GNU version of @code{patch} has been changed since +then, please send bug reports for @code{patch} by electronic mail to +both @samp{bug-gnu-utils@@prep.ai.mit.edu} and +@samp{lwall@@netlabs.com}. + +@node Concept Index, , Projects, Top +@unnumbered Concept Index + +@printindex cp + +@shortcontents +@contents +@bye -- cgit v1.1