\input texinfo @c -*-texinfo-*-@c %**start of header@setfilename diff.info@settitle Comparing and Merging Files@setchapternewpage odd@c %**end of header @ifinfoThis file documents the the GNU @code{diff}, @code{diff3}, @code{sdiff},and @code{cmp} commands for showing the differences between text filesand 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 ofthis manual provided the copyright notice and this permission noticeare preserved on all copies. @ignorePermission is granted to process this file through TeX and print theresults, provided the printed document carries copying permissionnotice identical to this one except for the removal of this paragraph(this paragraph not being relevant to the printed manual). @end ignorePermission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that the entireresulting derived work is distributed under the terms of a permissionnotice identical to this one. Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions,except that this permission notice may be stated in a translation approvedby 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 1filllCopyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies. Permission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that the entireresulting derived work is distributed under the terms of a permissionnotice identical to this one. Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions,except that this permission notice may be stated in a translation approvedby the Foundation.@end titlepage @node Top, , , (dir) @ifinfoThis file documents the the GNU @code{diff}, @code{diff3}, @code{sdiff},and @code{cmp} commands for showing the differences between text filesand 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. Perhapsone file is a newer version of the other file. Or maybe the two filesstarted out as identical copies but were changed by different people. You can use the @code{diff} command to show differences between twofiles, or each corresponding file in two directories. @code{diff}outputs differences between files line by line in any of severalformats, selectable by command line options. This set of differences isoften 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 numberswhere two files differ. @code{cmp} can also show all the charactersthat differ between the two files, side by side. Another way to comparetwo files character by character is the Emacs command @kbd{M-xcompare-windows}. @xref{Other Window, , Other Window, emacs, The GNUEmacs Manual}, for more information on that command. You can use the @code{diff3} command to show differences among threefiles. When two people have made independent changes to a commonoriginal, @code{diff3} can report the differences between the originaland the two changed versions, and can produce a merged file thatcontains 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 distributeupdates to text files (such as program source code) to other people.This method is especially useful when the differences are small comparedto 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 youthink of @code{diff} as subtracting one file from another to producetheir difference, you can think of @code{patch} as adding the differenceto one file to reproduce the other. This manual first concentrates on making diffs, and later shows how touse diffs to update files. GNU @code{diff} was written by Mike Haertel, David Hayes, RichardStallman, Len Tower, and Paul Eggert. Wayne Davison designed andimplemented the unified output format. The basic algorithm is describedin ``An O(ND) Difference Algorithm and its Variations'', Eugene W. Myers,@cite{Algorithmica} Vol.@: 1 No.@: 2, 1986, pp.@: 251--266; and in ``A FileComparison Program'', Webb Miller and Eugene W. Myers,@cite{Software---Practice and Experience} Vol.@: 15 No.@: 11, 1985,pp.@: 1025--1040.@c From: "Gene Myers" <gene@cs.arizona.edu>@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" <gene@cs.arizona.edu>@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} waswritten by Thomas Lord. GNU @code{cmp} was written by Torbjorn Granlundand David MacKenzie. @code{patch} was written mainly by Larry Wall; the GNU enhancements werewritten mainly by Wayne Davison and David MacKenzie. Parts of thismanual are adapted from a manual page written by Larry Wall, with hispermission. @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 weredeleted from, inserted in, or changed in one file to produce the otherfile. @code{diff} compares two files line by line, finds groups oflines that differ, and reports each group of differing lines. It canreport the differing lines in several formats, which have differentpurposes. GNU @code{diff} can show whether files are different without detailingthe differences. It also provides ways to suppress certain kinds ofdifferences that are not important to you. Most commonly, suchdifferences are changes in the amount of white space between words orlines. @code{diff} also provides ways to suppress differences inalphabetic case or in lines that match a regular expression that youprovide. These options can accumulate; for example, you can ignorechanges in both white space and alphabetic case. Another way to think of the differences between two files is as asequence of pairs of characters that can be either identical ordifferent. @code{cmp} reports the differences between two filescharacter by character, instead of line by line. As a result, it ismore useful than @code{diff} for comparing binary files. For textfiles, @code{cmp} is useful mainly when you want to know only whethertwo files are identical. To illustrate the effect that considering changes character by charactercan have compared with considering them line by line, think of whathappens if a single newline character is added to the beginning of afile. If that file is then compared with an otherwise identical filethat lacks the newline at the beginning, @code{diff} will report that ablank line has been added to the file, while @code{cmp} will report thatalmost every character of the two files differs. @code{diff3} normally compares three input files line by line, findsgroups of lines that differ, and reports each group of differing lines.Its output is designed to make it easy to inspect two different sets ofchanges 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 toboth files, interspersed with groups of differing lines called@dfn{hunks}. Comparing two identical files yields one sequence ofcommon lines and no hunks, because no lines differ. Comparing twoentirely different files yields no common lines and one large hunk thatcontains all lines of both files. In general, there are many ways tomatch up lines between two given files. @code{diff} tries to minimizethe total hunk size by finding large sequences of common linesinterspersed 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 samethree 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: @example1,2d0< a< b3a2,3> b> a@end example @noindentBut if @code{diff} notices the common line @samp{b} instead, it producesthis output: @example1c1< a---> c3c3< c---> a@end example @noindentIt is also possible to find @samp{a} as the common line. @code{diff}does not always find an optimal matching between the files; it takesshortcuts to run faster. But its output is usually close to theshortest 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 spaceat line end, and considers all other sequences of one or morewhite space characters to be equivalent. With these options,@code{diff} considers the following two lines to be equivalent, where@samp{$} denotes the line end: @exampleHere 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 wherethe other file has none. @dfn{White space} characters includetab, 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 thefollowing two lines to be equivalent, where @samp{$} denotes the lineend and @samp{^M} denotes a carriage return: @exampleHere 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 insertionsor deletions of blank lines. These options normally affect only linesthat are completely empty; they do not affect lines that look empty butcontain space or tab characters. With these options, for example, afile containing@example1. A point is that which has no part. 2. A line is breadthless length.-- Euclid, The Elements, I@end example@noindentis considered identical to a file containing@example1. 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 theiruppercase counterparts, so that, for example, it considers @samp{FunkyStuff}, @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 regularexpression, use the @samp{-I @var{regexp}} or@samp{--ignore-matching-lines=@var{regexp}} option. You should escaperegular expressions that contain shell metacharacters to prevent theshell from expanding them. For example, @samp{diff -I '^[0-9]'} ignoresall changes to lines beginning with a digit. However, @samp{-I} only ignores the insertion or deletion of lines thatcontain the regular expression if every changed line in the hunk---everyinsertion and every deletion---matches the regular expression. In otherwords, for each nonignorable change, @code{diff} prints the complete setof changes in its vicinity, including the ignorable ones. You can specify more than one regular expression for lines to ignore byusing more than one @samp{-I} option. @code{diff} tries to match eachline 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 youdon't care what the differences are, you can use the summary outputformat. In this format, instead of showing the differences between thefiles, @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 twodirectories. It is also much faster than doing the normal line by linecomparisons, because @code{diff} can stop analyzing the files as soon asit 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 nooutput. When the files differ, by default, @code{cmp} outputs the byteoffset and line number where the first difference occurs. You can usethe @samp{-s} option to suppress that information, so that @code{cmp}produces no output and reports whether the files differ using only itsexit status (@pxref{Invoking cmp}). @c Fix this.Unlike @code{diff}, @code{cmp} cannot compare directories; it can onlycompare 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 isbinary (a non-text file), it normally treats that pair of files much asif the summary output format had been selected (@pxref{Brief}), andreports only that the binary files are different. This is because lineby line comparisons are usually not meaningful for binary files. @code{diff} determines whether a file is text or binary by checking thefirst few bytes in the file; the exact number of bytes is systemdependent, but it is typically several thousand. If every character inthat part of the file is non-null, @code{diff} considers the file to betext; otherwise it considers the file to be binary. Sometimes you might want to force @code{diff} to consider files to betext. For example, you might be comparing text files that containnull characters; @code{diff} would erroneously decide that those arenon-text files. Or you might be comparing documents that are in aformat used by a word processing system that uses null characters toindicate special formatting. You can force @code{diff} to consider allfiles 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 thisoption do not in fact contain text, they will probably contain fewnewline characters, and the @code{diff} output will consist of hunksshowing differences between long lines of whatever characters the filescontain. 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 binarydata instead. This option has no effect on a Posix-compliant systemlike GNU or traditional Unix. However, many personal computeroperating systems represent the end of a line with a carriage returnfollowed by a newline. On such systems, @code{diff} normally ignoresthese carriage returns on input and generates them at the end of eachoutput line, but with the @samp{--binary} option @code{diff} treatseach carriage return as just another input character, and does notgenerate a carriage return at the end of each output line. This can beuseful when dealing with non-text files that are meant to beinterchanged 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 eachdiffering byte in the two files. With GNU @code{cmp}, you can also usethe @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 suchcomparisons are usually not useful. @code{diff3} uses the same test as@code{diff} to decide whether a file is binary. As with @code{diff}, ifthe input files contain a few non-text characters but otherwise are liketext files, you can force @code{diff3} to consider all files to be textfiles 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 toillustrate the output of @code{diff} and how various options can changeit. This is the file @file{lao}: @exampleThe 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}: @exampleThe Nameless is the origin of Heaven and Earth;The named is the mother of all things. Lines 1–500 of 3916. Load more
\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" <gene@cs.arizona.edu> @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" <gene@cs.arizona.edu> @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.