1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: diff.texi,v 1.25 2004/04/12 07:44:35 eggert Exp $
3 @comment %**start of header
6 @settitle Comparing and Merging Files
9 @comment %**end of header
11 This manual is for GNU Diffutils
12 (version @value{VERSION}, @value{UPDATED}),
13 and documents the @acronym{GNU} @command{diff}, @command{diff3},
14 @command{sdiff}, and @command{cmp} commands for showing the
15 differences between files and the @acronym{GNU} @command{patch} command for
16 using their output to update files.
18 Copyright @copyright{} 1992, 1993, 1994, 1998, 2001, 2002, 2004 Free
19 Software Foundation, Inc.
22 Permission is granted to copy, distribute and/or modify this document
23 under the terms of the GNU Free Documentation License, Version 1.1 or
24 any later version published by the Free Software Foundation; with no
25 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
26 and with the Back-Cover Texts as in (a) below. A copy of the
27 license is included in the section entitled ``GNU Free Documentation
30 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
31 this GNU Manual, like GNU software. Copies published by the Free
32 Software Foundation raise funds for GNU development.''
36 @c Debian install-info (up through at least version 1.9.20) uses only the
37 @c first dircategory. Put this one first, as it is more useful in practice.
38 @dircategory Individual utilities
40 * cmp: (diff)Invoking cmp. Compare 2 files byte by byte.
41 * diff: (diff)Invoking diff. Compare 2 files line by line.
42 * diff3: (diff)Invoking diff3. Compare 3 files line by line.
43 * patch: (diff)Invoking patch. Apply a patch to a file.
44 * sdiff: (diff)Invoking sdiff. Merge 2 files side-by-side.
47 @dircategory Text creation and manipulation
49 * Diff: (diff). Comparing and merging files.
53 @title Comparing and Merging Files
54 @subtitle for Diffutils @value{VERSION} and @code{patch} 2.5.4
55 @subtitle @value{UPDATED}
56 @author David MacKenzie, Paul Eggert, and Richard Stallman
58 @vskip 0pt plus 1filll
67 @top Comparing and Merging Files
73 * Overview:: Preliminary information.
74 * Comparison:: What file comparison means.
76 * Output Formats:: Formats for two-way difference reports.
77 * Incomplete Lines:: Lines that lack trailing newlines.
78 * Comparing Directories:: Comparing files and directories.
79 * Adjusting Output:: Making @command{diff} output prettier.
80 * diff Performance:: Making @command{diff} smarter or faster.
82 * Comparing Three Files:: Formats for three-way difference reports.
83 * diff3 Merging:: Merging from a common ancestor.
85 * Interactive Merging:: Interactive merging with @command{sdiff}.
87 * Merging with patch:: Using @command{patch} to change old files into new ones.
88 * Making Patches:: Tips for making and using patch distributions.
90 * Invoking cmp:: Compare two files byte by byte.
91 * Invoking diff:: Compare two files line by line.
92 * Invoking diff3:: Compare three files line by line.
93 * Invoking patch:: Apply a diff file to an original.
94 * Invoking sdiff:: Side-by-side merge of file differences.
96 * Standards conformance:: Conformance to the @acronym{POSIX} standard.
97 * Projects:: If you've found a bug or other shortcoming.
99 * Copying This Manual:: How to make copies of this manual.
100 * Translations:: Available translations of this manual.
106 @cindex overview of @command{diff} and @command{patch}
108 Computer users often find occasion to ask how two files differ. Perhaps
109 one file is a newer version of the other file. Or maybe the two files
110 started out as identical copies but were changed by different people.
112 You can use the @command{diff} command to show differences between two
113 files, or each corresponding file in two directories. @command{diff}
114 outputs differences between files line by line in any of several
115 formats, selectable by command line options. This set of differences is
116 often called a @dfn{diff} or @dfn{patch}. For files that are identical,
117 @command{diff} normally produces no output; for binary (non-text) files,
118 @command{diff} normally reports only that they are different.
120 You can use the @command{cmp} command to show the byte and line numbers
121 where two files differ. @command{cmp} can also show all the bytes
122 that differ between the two files, side by side. A way to compare
123 two files character by character is the Emacs command @kbd{M-x
124 compare-windows}. @xref{Other Window, , Other Window, emacs, The @acronym{GNU}
125 Emacs Manual}, for more information on that command.
127 You can use the @command{diff3} command to show differences among three
128 files. When two people have made independent changes to a common
129 original, @command{diff3} can report the differences between the original
130 and the two changed versions, and can produce a merged file that
131 contains both persons' changes together with warnings about conflicts.
133 You can use the @command{sdiff} command to merge two files interactively.
135 You can use the set of differences produced by @command{diff} to distribute
136 updates to text files (such as program source code) to other people.
137 This method is especially useful when the differences are small compared
138 to the complete files. Given @command{diff} output, you can use the
139 @command{patch} program to update, or @dfn{patch}, a copy of the file. If you
140 think of @command{diff} as subtracting one file from another to produce
141 their difference, you can think of @command{patch} as adding the difference
142 to one file to reproduce the other.
144 This manual first concentrates on making diffs, and later shows how to
145 use diffs to update files.
147 @acronym{GNU} @command{diff} was written by Paul Eggert, Mike Haertel,
148 David Hayes, Richard Stallman, and Len Tower. Wayne Davison designed and
149 implemented the unified output format. The basic algorithm is described
150 by Eugene W. Myers in ``An O(ND) Difference Algorithm and its Variations'',
151 @cite{Algorithmica} Vol.@: 1 No.@: 2, 1986, pp.@: 251--266; and in ``A File
152 Comparison Program'', Webb Miller and Eugene W. Myers,
153 @cite{Software---Practice and Experience} Vol.@: 15 No.@: 11, 1985,
155 @c From: "Gene Myers" <gene@cs.arizona.edu>
156 @c They are about the same basic algorithm; the Algorithmica
157 @c paper gives a rigorous treatment and the sub-algorithm for
158 @c delivering scripts and should be the primary reference, but
159 @c both should be mentioned.
160 The algorithm was independently discovered as described by E. Ukkonen in
161 ``Algorithms for Approximate String Matching'',
162 @cite{Information and Control} Vol.@: 64, 1985, pp.@: 100--118.
163 @c From: "Gene Myers" <gene@cs.arizona.edu>
164 @c Date: Wed, 29 Sep 1993 08:27:55 MST
165 @c Ukkonen should be given credit for also discovering the algorithm used
167 Unless the @option{--minimal} option is used, @command{diff} uses a
168 heuristic by Paul Eggert that limits the cost to @math{O(N^1.5 log N)}
169 at the price of producing suboptimal output for large inputs with many
170 differences. Related algorithms are surveyed by Alfred V. Aho in
171 section 6.3 of ``Algorithms for Finding Patterns in Strings'',
172 @cite{Handbook of Theoretical Computer Science} (Jan Van Leeuwen,
173 ed.), Vol.@: A, @cite{Algorithms and Complexity}, Elsevier/MIT Press,
174 1990, pp.@: 255--300.
176 @acronym{GNU} @command{diff3} was written by Randy Smith. @acronym{GNU}
177 @command{sdiff} was written by Thomas Lord. @acronym{GNU} @command{cmp}
178 was written by Torbj@"orn Granlund and David MacKenzie.
180 @acronym{GNU} @command{patch} was written mainly by Larry Wall and Paul Eggert;
181 several @acronym{GNU} enhancements were contributed by Wayne Davison and
182 David MacKenzie. Parts of this manual are adapted from a manual page
183 written by Larry Wall, with his permission.
186 @chapter What Comparison Means
189 There are several ways to think about the differences between two files.
190 One way to think of the differences is as a series of lines that were
191 deleted from, inserted in, or changed in one file to produce the other
192 file. @command{diff} compares two files line by line, finds groups of
193 lines that differ, and reports each group of differing lines. It can
194 report the differing lines in several formats, which have different
197 @acronym{GNU} @command{diff} can show whether files are different
198 without detailing the differences. It also provides ways to suppress
199 certain kinds of differences that are not important to you. Most
200 commonly, such differences are changes in the amount of white space
201 between words or lines. @command{diff} also provides ways to suppress
202 differences in alphabetic case or in lines that match a regular
203 expression that you provide. These options can accumulate; for
204 example, you can ignore changes in both white space and alphabetic
207 Another way to think of the differences between two files is as a
208 sequence of pairs of bytes that can be either identical or
209 different. @command{cmp} reports the differences between two files
210 byte by byte, instead of line by line. As a result, it is often
211 more useful than @command{diff} for comparing binary files. For text
212 files, @command{cmp} is useful mainly when you want to know only whether
213 two files are identical, or whether one file is a prefix of the other.
215 To illustrate the effect that considering changes byte by byte
216 can have compared with considering them line by line, think of what
217 happens if a single newline character is added to the beginning of a
218 file. If that file is then compared with an otherwise identical file
219 that lacks the newline at the beginning, @command{diff} will report that a
220 blank line has been added to the file, while @command{cmp} will report that
221 almost every byte of the two files differs.
223 @command{diff3} normally compares three input files line by line, finds
224 groups of lines that differ, and reports each group of differing lines.
225 Its output is designed to make it easy to inspect two different sets of
226 changes to the same file.
229 * Hunks:: Groups of differing lines.
230 * White Space:: Suppressing differences in white space.
231 * Blank Lines:: Suppressing differences whose lines are all blank.
232 * Specified Lines:: Suppressing differences whose lines all match a pattern.
233 * Case Folding:: Suppressing differences in alphabetic case.
234 * Brief:: Summarizing which files are different.
235 * Binary:: Comparing binary files or forcing text comparisons.
242 When comparing two files, @command{diff} finds sequences of lines common to
243 both files, interspersed with groups of differing lines called
244 @dfn{hunks}. Comparing two identical files yields one sequence of
245 common lines and no hunks, because no lines differ. Comparing two
246 entirely different files yields no common lines and one large hunk that
247 contains all lines of both files. In general, there are many ways to
248 match up lines between two given files. @command{diff} tries to minimize
249 the total hunk size by finding large sequences of common lines
250 interspersed with small hunks of differing lines.
252 For example, suppose the file @file{F} contains the three lines
253 @samp{a}, @samp{b}, @samp{c}, and the file @file{G} contains the same
254 three lines in reverse order @samp{c}, @samp{b}, @samp{a}. If
255 @command{diff} finds the line @samp{c} as common, then the command
256 @samp{diff F G} produces this output:
268 But if @command{diff} notices the common line @samp{b} instead, it produces
283 It is also possible to find @samp{a} as the common line. @command{diff}
284 does not always find an optimal matching between the files; it takes
285 shortcuts to run faster. But its output is usually close to the
286 shortest possible. You can adjust this tradeoff with the
287 @option{-d} or @option{--minimal} option (@pxref{diff Performance}).
290 @section Suppressing Differences in Blank and Tab Spacing
291 @cindex blank and tab difference suppression
292 @cindex tab and blank difference suppression
294 The @option{-E} or @option{--ignore-tab-expansion} option ignores the
295 distinction between tabs and spaces on input. A tab is considered to be
296 equivalent to the number of spaces to the next tab stop (@pxref{Tabs}).
298 The @option{-b} or @option{--ignore-space-change} option is stronger.
299 It ignores white space at line end, and considers all other sequences of
300 one or more white space characters within a line to be equivalent. With this
301 option, @command{diff} considers the following two lines to be equivalent,
302 where @samp{$} denotes the line end:
305 Here lyeth muche rychnesse in lytell space. -- John Heywood$
306 Here lyeth muche rychnesse in lytell space. -- John Heywood $
309 The @option{-w} or @option{--ignore-all-space} option is stronger still.
310 It ignores differences even if one line has white space where
311 the other line has none. @dfn{White space} characters include
312 tab, newline, vertical tab, form feed, carriage return, and space;
313 some locales may define additional characters to be white space.
314 With this option, @command{diff} considers the
315 following two lines to be equivalent, where @samp{$} denotes the line
316 end and @samp{^M} denotes a carriage return:
319 Here lyeth muche rychnesse in lytell space.-- John Heywood$
320 He relyeth much erychnes seinly tells pace. --John Heywood ^M$
324 @section Suppressing Differences Whose Lines Are All Blank
325 @cindex blank line difference suppression
327 The @option{-B} or @option{--ignore-blank-lines} option ignores changes
328 that consist entirely of blank lines. With this option, for example, a
331 1. A point is that which has no part.
333 2. A line is breadthless length.
334 -- Euclid, The Elements, I
337 is considered identical to a file containing
339 1. A point is that which has no part.
340 2. A line is breadthless length.
343 -- Euclid, The Elements, I
346 Normally this option affects only lines that are completely empty, but
347 if you also specify the @option{-b} or @option{--ignore-space-change}
348 option, or the @option{-w} or @option{--ignore-all-space} option,
349 lines are also affected if they look empty but contain white space.
350 In other words, @option{-B} is equivalent to @samp{-I '^$'} by
351 default, but it is equivalent to @option{-I '^[[:space:]]*$'} if
352 @option{-b} or @option{-w} is also specified.
354 @node Specified Lines
355 @section Suppressing Differences Whose Lines All Match a Regular Expression
356 @cindex regular expression suppression
358 To ignore insertions and deletions of lines that match a
359 @command{grep}-style regular expression, use the @option{-I
360 @var{regexp}} or @option{--ignore-matching-lines=@var{regexp}} option.
362 regular expressions that contain shell metacharacters to prevent the
363 shell from expanding them. For example, @samp{diff -I '^[[:digit:]]'} ignores
364 all changes to lines beginning with a digit.
366 However, @option{-I} only ignores the insertion or deletion of lines that
367 contain the regular expression if every changed line in the hunk---every
368 insertion and every deletion---matches the regular expression. In other
369 words, for each nonignorable change, @command{diff} prints the complete set
370 of changes in its vicinity, including the ignorable ones.
372 You can specify more than one regular expression for lines to ignore by
373 using more than one @option{-I} option. @command{diff} tries to match each
374 line against each regular expression.
377 @section Suppressing Case Differences
378 @cindex case difference suppression
380 @acronym{GNU} @command{diff} can treat lower case letters as
381 equivalent to their upper case counterparts, so that, for example, it
382 considers @samp{Funky Stuff}, @samp{funky STUFF}, and @samp{fUNKy
383 stuFf} to all be the same. To request this, use the @option{-i} or
384 @option{--ignore-case} option.
387 @section Summarizing Which Files Differ
388 @cindex summarizing which files differ
389 @cindex brief difference reports
391 When you only want to find out whether files are different, and you
392 don't care what the differences are, you can use the summary output
393 format. In this format, instead of showing the differences between the
394 files, @command{diff} simply reports whether files differ. The @option{-q}
395 or @option{--brief} option selects this output format.
397 This format is especially useful when comparing the contents of two
398 directories. It is also much faster than doing the normal line by line
399 comparisons, because @command{diff} can stop analyzing the files as soon as
400 it knows that there are any differences.
402 You can also get a brief indication of whether two files differ by using
403 @command{cmp}. For files that are identical, @command{cmp} produces no
404 output. When the files differ, by default, @command{cmp} outputs the byte
405 and line number where the first difference occurs, or reports that one
406 file is a prefix of the other. You can use
407 the @option{-s}, @option{--quiet}, or @option{--silent} option to
408 suppress that information, so that @command{cmp}
409 produces no output and reports whether the files differ using only its
410 exit status (@pxref{Invoking cmp}).
413 Unlike @command{diff}, @command{cmp} cannot compare directories; it can only
417 @section Binary Files and Forcing Text Comparisons
418 @cindex binary file diff
419 @cindex text versus binary diff
421 If @command{diff} thinks that either of the two files it is comparing is
422 binary (a non-text file), it normally treats that pair of files much as
423 if the summary output format had been selected (@pxref{Brief}), and
424 reports only that the binary files are different. This is because line
425 by line comparisons are usually not meaningful for binary files.
427 @command{diff} determines whether a file is text or binary by checking the
428 first few bytes in the file; the exact number of bytes is system
429 dependent, but it is typically several thousand. If every byte in
430 that part of the file is non-null, @command{diff} considers the file to be
431 text; otherwise it considers the file to be binary.
433 Sometimes you might want to force @command{diff} to consider files to be
434 text. For example, you might be comparing text files that contain
435 null characters; @command{diff} would erroneously decide that those are
436 non-text files. Or you might be comparing documents that are in a
437 format used by a word processing system that uses null characters to
438 indicate special formatting. You can force @command{diff} to consider all
439 files to be text files, and compare them line by line, by using the
440 @option{-a} or @option{--text} option. If the files you compare using this
441 option do not in fact contain text, they will probably contain few
442 newline characters, and the @command{diff} output will consist of hunks
443 showing differences between long lines of whatever characters the files
446 You can also force @command{diff} to report only whether files differ
447 (but not how). Use the @option{-q} or @option{--brief} option for
450 Normally, differing binary files count as trouble because the
451 resulting @command{diff} output does not capture all the differences.
452 This trouble causes @command{diff} to exit with status 2. However,
453 this trouble cannot occur with the @option{-a} or @option{--text}
454 option, or with the @option{-q} or @option{--brief} option, as these
455 options both cause @command{diff} to generate a form of output that
456 represents differences as requested.
458 In operating systems that distinguish between text and binary files,
459 @command{diff} normally reads and writes all data as text. Use the
460 @option{--binary} option to force @command{diff} to read and write binary
461 data instead. This option has no effect on a @acronym{POSIX}-compliant system
462 like @acronym{GNU} or traditional Unix. However, many personal computer
463 operating systems represent the end of a line with a carriage return
464 followed by a newline. On such systems, @command{diff} normally ignores
465 these carriage returns on input and generates them at the end of each
466 output line, but with the @option{--binary} option @command{diff} treats
467 each carriage return as just another input character, and does not
468 generate a carriage return at the end of each output line. This can be
469 useful when dealing with non-text files that are meant to be
470 interchanged with @acronym{POSIX}-compliant systems.
472 The @option{--strip-trailing-cr} causes @command{diff} to treat input
473 lines that end in carriage return followed by newline as if they end
474 in plain newline. This can be useful when comparing text that is
475 imperfectly imported from many personal computer operating systems.
476 This option affects how lines are read, which in turn affects how they
477 are compared and output.
479 If you want to compare two files byte by byte, you can use the
480 @command{cmp} program with the @option{-l} or @option{--verbose}
481 option to show the values of each differing byte in the two files.
482 With @acronym{GNU} @command{cmp}, you can also use the @option{-b} or
483 @option{--print-bytes} option to show the @acronym{ASCII} representation of
484 those bytes. @xref{Invoking cmp}, for more information.
486 If @command{diff3} thinks that any of the files it is comparing is binary
487 (a non-text file), it normally reports an error, because such
488 comparisons are usually not useful. @command{diff3} uses the same test as
489 @command{diff} to decide whether a file is binary. As with @command{diff}, if
490 the input files contain a few non-text bytes but otherwise are like
491 text files, you can force @command{diff3} to consider all files to be text
492 files and compare them line by line by using the @option{-a} or
493 @option{--text} option.
496 @chapter @command{diff} Output Formats
497 @cindex output formats
498 @cindex format of @command{diff} output
500 @command{diff} has several mutually exclusive options for output format.
501 The following sections describe each format, illustrating how
502 @command{diff} reports the differences between two sample input files.
505 * Sample diff Input:: Sample @command{diff} input files for examples.
506 * Context:: Showing differences with the surrounding text.
507 * Side by Side:: Showing differences in two columns.
508 * Normal:: Showing differences without surrounding text.
509 * Scripts:: Generating scripts for other programs.
510 * If-then-else:: Merging files with if-then-else.
513 @node Sample diff Input
514 @section Two Sample Input Files
515 @cindex @command{diff} sample input
516 @cindex sample input for @command{diff}
518 Here are two sample files that we will use in numerous examples to
519 illustrate the output of @command{diff} and how various options can change
522 This is the file @file{lao}:
525 The Way that can be told of is not the eternal Way;
526 The name that can be named is not the eternal name.
527 The Nameless is the origin of Heaven and Earth;
528 The Named is the mother of all things.
529 Therefore let there always be non-being,
530 so we may see their subtlety,
531 And let there always be being,
532 so we may see their outcome.
533 The two are the same,
534 But after they are produced,
535 they have different names.
538 This is the file @file{tzu}:
541 The Nameless is the origin of Heaven and Earth;
542 The named is the mother of all things.
544 Therefore let there always be non-being,
545 so we may see their subtlety,
546 And let there always be being,
547 so we may see their outcome.
548 The two are the same,
549 But after they are produced,
550 they have different names.
551 They both may be called deep and profound.
552 Deeper and more profound,
553 The door of all subtleties!
556 In this example, the first hunk contains just the first two lines of
557 @file{lao}, the second hunk contains the fourth line of @file{lao}
558 opposing the second and third lines of @file{tzu}, and the last hunk
559 contains just the last three lines of @file{tzu}.
562 @section Showing Differences in Their Context
563 @cindex context output format
564 @cindex @samp{!} output format
566 Usually, when you are looking at the differences between files, you will
567 also want to see the parts of the files near the lines that differ, to
568 help you understand exactly what has changed. These nearby parts of the
569 files are called the @dfn{context}.
571 @acronym{GNU} @command{diff} provides two output formats that show context
572 around the differing lines: @dfn{context format} and @dfn{unified
573 format}. It can optionally show in which function or section of the
574 file the differing lines are found.
576 If you are distributing new versions of files to other people in the
577 form of @command{diff} output, you should use one of the output formats
578 that show context so that they can apply the diffs even if they have
579 made small changes of their own to the files. @command{patch} can apply
580 the diffs in this case by searching in the files for the lines of
581 context around the differing lines; if those lines are actually a few
582 lines away from where the diff says they are, @command{patch} can adjust
583 the line numbers accordingly and still apply the diff correctly.
584 @xref{Imperfect}, for more information on using @command{patch} to apply
588 * Context Format:: An output format that shows surrounding lines.
589 * Unified Format:: A more compact output format that shows context.
590 * Sections:: Showing which sections of the files differences are in.
591 * Alternate Names:: Showing alternate file names in context headers.
595 @subsection Context Format
597 The context output format shows several lines of context around the
598 lines that differ. It is the standard format for distributing updates
601 To select this output format, use the @option{-C @var{lines}},
602 @option{--context@r{[}=@var{lines}@r{]}}, or @option{-c} option. The
603 argument @var{lines} that some of these options take is the number of
604 lines of context to show. If you do not specify @var{lines}, it
605 defaults to three. For proper operation, @command{patch} typically needs
606 at least two lines of context.
609 * Example Context:: Sample output in context format.
610 * Less Context:: Another sample with less context.
611 * Detailed Context:: A detailed description of the context output format.
614 @node Example Context
615 @subsubsection An Example of Context Format
617 Here is the output of @samp{diff -c lao tzu} (@pxref{Sample diff Input},
618 for the complete contents of the two files). Notice that up to three
619 lines that are not different are shown around each line that is
620 different; they are the context lines. Also notice that the first two
621 hunks have run together, because their contents overlap.
624 *** lao 2002-02-21 23:30:39.942229878 -0800
625 --- tzu 2002-02-21 23:30:50.442260588 -0800
628 - The Way that can be told of is not the eternal Way;
629 - The name that can be named is not the eternal name.
630 The Nameless is the origin of Heaven and Earth;
631 ! The Named is the mother of all things.
632 Therefore let there always be non-being,
633 so we may see their subtlety,
634 And let there always be being,
636 The Nameless is the origin of Heaven and Earth;
637 ! The named is the mother of all things.
639 Therefore let there always be non-being,
640 so we may see their subtlety,
641 And let there always be being,
645 The two are the same,
646 But after they are produced,
647 they have different names.
648 + They both may be called deep and profound.
649 + Deeper and more profound,
650 + The door of all subtleties!
654 @subsubsection An Example of Context Format with Less Context
656 Here is the output of @samp{diff -C 1 lao tzu} (@pxref{Sample diff
657 Input}, for the complete contents of the two files). Notice that at
658 most one context line is reported here.
661 *** lao 2002-02-21 23:30:39.942229878 -0800
662 --- tzu 2002-02-21 23:30:50.442260588 -0800
665 - The Way that can be told of is not the eternal Way;
666 - The name that can be named is not the eternal name.
667 The Nameless is the origin of Heaven and Earth;
668 ! The Named is the mother of all things.
669 Therefore let there always be non-being,
671 The Nameless is the origin of Heaven and Earth;
672 ! The named is the mother of all things.
674 Therefore let there always be non-being,
678 they have different names.
679 + They both may be called deep and profound.
680 + Deeper and more profound,
681 + The door of all subtleties!
684 @node Detailed Context
685 @subsubsection Detailed Description of Context Format
687 The context output format starts with a two-line header, which looks
691 *** @var{from-file} @var{from-file-modification-time}
692 --- @var{to-file} @var{to-file-modification time}
697 @cindex time stamp format, context diffs
698 The time stamp normally looks like @samp{2002-02-21 23:30:39.942229878
699 -0800} to indicate the date, time with fractional seconds, and time
700 zone in @uref{ftp://ftp.isi.edu/in-notes/rfc2822.txt, Internet RFC
701 2822 format}. (The fractional seconds are omitted on hosts that do
702 not support fractional time stamps.) However, a traditional time
703 stamp like @samp{Thu Feb 21 23:30:39 2002} is used if the
704 @env{LC_TIME} locale category is either @samp{C} or @samp{POSIX}.
706 You can change the header's content with the
707 @option{--label=@var{label}} option; see @ref{Alternate Names}.
709 Next come one or more hunks of differences; each hunk shows one area
710 where the files differ. Context format hunks look like this:
714 *** @var{from-file-line-numbers} ****
716 @var{from-file-line}@dots{}
717 --- @var{to-file-line-numbers} ----
719 @var{to-file-line}@dots{}
722 If a hunk contains two or more lines, its line numbers look like
723 @samp{@var{start},@var{end}}. Otherwise only its end line number
724 appears. An empty hunk is considered to end at the line that precedes
727 The lines of context around the lines that differ start with two space
728 characters. The lines that differ between the two files start with one
729 of the following indicator characters, followed by a space character:
733 A line that is part of a group of one or more lines that changed between
734 the two files. There is a corresponding group of lines marked with
735 @samp{!} in the part of this hunk for the other file.
738 An ``inserted'' line in the second file that corresponds to nothing in
742 A ``deleted'' line in the first file that corresponds to nothing in the
746 If all of the changes in a hunk are insertions, the lines of
747 @var{from-file} are omitted. If all of the changes are deletions, the
748 lines of @var{to-file} are omitted.
751 @subsection Unified Format
752 @cindex unified output format
753 @cindex @samp{+-} output format
755 The unified output format is a variation on the context format that is
756 more compact because it omits redundant context lines. To select this
757 output format, use the @option{-U @var{lines}},
758 @option{--unified@r{[}=@var{lines}@r{]}}, or @option{-u}
759 option. The argument @var{lines} is the number of lines of context to
760 show. When it is not given, it defaults to three.
762 At present, only @acronym{GNU} @command{diff} can produce this format and
763 only @acronym{GNU} @command{patch} can automatically apply diffs in this
764 format. For proper operation, @command{patch} typically needs at
765 least three lines of context.
768 * Example Unified:: Sample output in unified format.
769 * Detailed Unified:: A detailed description of unified format.
772 @node Example Unified
773 @subsubsection An Example of Unified Format
775 Here is the output of the command @samp{diff -u lao tzu}
776 (@pxref{Sample diff Input}, for the complete contents of the two files):
779 --- lao 2002-02-21 23:30:39.942229878 -0800
780 +++ tzu 2002-02-21 23:30:50.442260588 -0800
782 -The Way that can be told of is not the eternal Way;
783 -The name that can be named is not the eternal name.
784 The Nameless is the origin of Heaven and Earth;
785 -The Named is the mother of all things.
786 +The named is the mother of all things.
788 Therefore let there always be non-being,
789 so we may see their subtlety,
790 And let there always be being,
792 The two are the same,
793 But after they are produced,
794 they have different names.
795 +They both may be called deep and profound.
796 +Deeper and more profound,
797 +The door of all subtleties!
800 @node Detailed Unified
801 @subsubsection Detailed Description of Unified Format
803 The unified output format starts with a two-line header, which looks
807 --- @var{from-file} @var{from-file-modification-time}
808 +++ @var{to-file} @var{to-file-modification-time}
812 @cindex time stamp format, unified diffs
813 The time stamp looks like @samp{2002-02-21 23:30:39.942229878 -0800}
814 to indicate the date, time with fractional seconds, and time zone.
815 The fractional seconds are omitted on hosts that do not support
816 fractional time stamps.
818 You can change the header's content with the
819 @option{--label=@var{label}} option; see @xref{Alternate Names}.
821 Next come one or more hunks of differences; each hunk shows one area
822 where the files differ. Unified format hunks look like this:
825 @@@@ @var{from-file-line-numbers} @var{to-file-line-numbers} @@@@
826 @var{line-from-either-file}
827 @var{line-from-either-file}@dots{}
830 If a hunk contains just one line, only its start line number appears.
831 Otherwise its line numbers look like @samp{@var{start},@var{count}}.
832 An empty hunk is considered to start at the line that follows the hunk.
834 If a hunk and its context contain two or more lines, its
835 line numbers look like @samp{@var{start},@var{count}}. Otherwise only
836 its end line number appears. An empty hunk is considered to end at
837 the line that precedes the hunk.
839 The lines common to both files begin with a space character. The lines
840 that actually differ between the two files have one of the following
841 indicator characters in the left print column:
845 A line was added here to the first file.
848 A line was removed here from the first file.
852 @subsection Showing Which Sections Differences Are in
854 @cindex section headings
856 Sometimes you might want to know which part of the files each change
857 falls in. If the files are source code, this could mean which
858 function was changed. If the files are documents, it could mean which
859 chapter or appendix was changed. @acronym{GNU} @command{diff} can
860 show this by displaying the nearest section heading line that precedes
861 the differing lines. Which lines are ``section headings'' is
862 determined by a regular expression.
865 * Specified Headings:: Showing headings that match regular expressions.
866 * C Function Headings:: Showing headings of C functions.
869 @node Specified Headings
870 @subsubsection Showing Lines That Match Regular Expressions
871 @cindex specified headings
872 @cindex regular expression matching headings
874 To show in which sections differences occur for files that are not
875 source code for C or similar languages, use the @option{-F @var{regexp}}
876 or @option{--show-function-line=@var{regexp}} option. @command{diff}
877 considers lines that match the @command{grep}-style regular expression
878 @var{regexp} to be the beginning
879 of a section of the file. Here are suggested regular expressions for
880 some common languages:
882 @c Please add to this list, e.g. Fortran, Pascal, Perl, Python.
892 This option does not automatically select an output format; in order to
893 use it, you must select the context format (@pxref{Context Format}) or
894 unified format (@pxref{Unified Format}). In other output formats it
897 The @option{-F} or @option{--show-function-line} option finds the nearest
898 unchanged line that precedes each hunk of differences and matches the
899 given regular expression. Then it adds that line to the end of the
900 line of asterisks in the context format, or to the @samp{@@@@} line in
901 unified format. If no matching line exists, this option leaves the output for
902 that hunk unchanged. If that line is more than 40 characters long, it
903 outputs only the first 40 characters. You can specify more than one
904 regular expression for such lines; @command{diff} tries to match each line
905 against each regular expression, starting with the last one given. This
906 means that you can use @option{-p} and @option{-F} together, if you wish.
908 @node C Function Headings
909 @subsubsection Showing C Function Headings
910 @cindex C function headings
911 @cindex function headings, C
913 To show in which functions differences occur for C and similar
914 languages, you can use the @option{-p} or @option{--show-c-function} option.
915 This option automatically defaults to the context output format
916 (@pxref{Context Format}), with the default number of lines of context.
917 You can override that number with @option{-C @var{lines}} elsewhere in the
918 command line. You can override both the format and the number with
919 @option{-U @var{lines}} elsewhere in the command line.
921 The @option{-p} or @option{--show-c-function} option is equivalent to
922 @option{-F '^[[:alpha:]$_]'} if the unified format is specified, otherwise
923 @option{-c -F '^[[:alpha:]$_]'} (@pxref{Specified Headings}). @acronym{GNU}
924 @command{diff} provides this option for the sake of convenience.
926 @node Alternate Names
927 @subsection Showing Alternate File Names
928 @cindex alternate file names
929 @cindex file name alternates
931 If you are comparing two files that have meaningless or uninformative
932 names, you might want @command{diff} to show alternate names in the header
933 of the context and unified output formats. To do this, use the
934 @option{--label=@var{label}} option. The first time
935 you give this option, its argument replaces the name and date of the
936 first file in the header; the second time, its argument replaces the
937 name and date of the second file. If you give this option more than
938 twice, @command{diff} reports an error. The @option{--label} option does not
939 affect the file names in the @command{pr} header when the @option{-l} or
940 @option{--paginate} option is used (@pxref{Pagination}).
942 Here are the first two lines of the output from @samp{diff -C 2
943 --label=original --label=modified lao tzu}:
951 @section Showing Differences Side by Side
953 @cindex two-column output
954 @cindex columnar output
956 @command{diff} can produce a side by side difference listing of two files.
957 The files are listed in two columns with a gutter between them. The
958 gutter contains one of the following markers:
962 The corresponding lines are in common. That is, either the lines are
963 identical, or the difference is ignored because of one of the
964 @option{--ignore} options (@pxref{White Space}).
967 The corresponding lines differ, and they are either both complete
971 The files differ and only the first file contains the line.
974 The files differ and only the second file contains the line.
977 Only the first file contains the line, but the difference is ignored.
980 Only the second file contains the line, but the difference is ignored.
983 The corresponding lines differ, and only the first line is incomplete.
986 The corresponding lines differ, and only the second line is incomplete.
989 Normally, an output line is incomplete if and only if the lines that it
990 contains are incomplete; @xref{Incomplete Lines}. However, when an
991 output line represents two differing lines, one might be incomplete
992 while the other is not. In this case, the output line is complete,
993 but its the gutter is marked @samp{\} if the first line is incomplete,
994 @samp{/} if the second line is.
996 Side by side format is sometimes easiest to read, but it has limitations.
997 It generates much wider output than usual, and truncates lines that are
998 too long to fit. Also, it relies on lining up output more heavily than
999 usual, so its output looks particularly bad if you use varying
1000 width fonts, nonstandard tab stops, or nonprinting characters.
1002 You can use the @command{sdiff} command to interactively merge side by side
1003 differences. @xref{Interactive Merging}, for more information on merging files.
1006 * Side by Side Format:: Controlling side by side output format.
1007 * Example Side by Side:: Sample side by side output.
1010 @node Side by Side Format
1011 @subsection Controlling Side by Side Format
1012 @cindex side by side format
1014 The @option{-y} or @option{--side-by-side} option selects side by side
1015 format. Because side by side output lines contain two input lines, the
1016 output is wider than usual: normally 130 print columns, which can fit
1017 onto a traditional printer line. You can set the width of the output
1018 with the @option{-W @var{columns}} or @option{--width=@var{columns}}
1019 option. The output is split into two halves of equal width, separated by a
1020 small gutter to mark differences; the right half is aligned to a tab
1021 stop so that tabs line up. Input lines that are too long to fit in half
1022 of an output line are truncated for output.
1024 The @option{--left-column} option prints only the left column of two
1025 common lines. The @option{--suppress-common-lines} option suppresses
1026 common lines entirely.
1028 @node Example Side by Side
1029 @subsection An Example of Side by Side Format
1031 Here is the output of the command @samp{diff -y -W 72 lao tzu}
1032 (@pxref{Sample diff Input}, for the complete contents of the two files).
1035 The Way that can be told of is n <
1036 The name that can be named is no <
1037 The Nameless is the origin of He The Nameless is the origin of He
1038 The Named is the mother of all t | The named is the mother of all t
1040 Therefore let there always be no Therefore let there always be no
1041 so we may see their subtlety, so we may see their subtlety,
1042 And let there always be being, And let there always be being,
1043 so we may see their outcome. so we may see their outcome.
1044 The two are the same, The two are the same,
1045 But after they are produced, But after they are produced,
1046 they have different names. they have different names.
1047 > They both may be called deep and
1048 > Deeper and more profound,
1049 > The door of all subtleties!
1053 @section Showing Differences Without Context
1054 @cindex normal output format
1055 @cindex @samp{<} output format
1057 The ``normal'' @command{diff} output format shows each hunk of differences
1058 without any surrounding context. Sometimes such output is the clearest
1059 way to see how lines have changed, without the clutter of nearby
1060 unchanged lines (although you can get similar results with the context
1061 or unified formats by using 0 lines of context). However, this format
1062 is no longer widely used for sending out patches; for that purpose, the
1063 context format (@pxref{Context Format}) and the unified format
1064 (@pxref{Unified Format}) are superior. Normal format is the default for
1065 compatibility with older versions of @command{diff} and the @acronym{POSIX}
1066 standard. Use the @option{--normal} option to select this output
1070 * Example Normal:: Sample output in the normal format.
1071 * Detailed Normal:: A detailed description of normal output format.
1074 @node Example Normal
1075 @subsection An Example of Normal Format
1077 Here is the output of the command @samp{diff lao tzu}
1078 (@pxref{Sample diff Input}, for the complete contents of the two files).
1079 Notice that it shows only the lines that are different between the two
1084 < The Way that can be told of is not the eternal Way;
1085 < The name that can be named is not the eternal name.
1087 < The Named is the mother of all things.
1089 > The named is the mother of all things.
1092 > They both may be called deep and profound.
1093 > Deeper and more profound,
1094 > The door of all subtleties!
1097 @node Detailed Normal
1098 @subsection Detailed Description of Normal Format
1100 The normal output format consists of one or more hunks of differences;
1101 each hunk shows one area where the files differ. Normal format hunks
1105 @var{change-command}
1106 < @var{from-file-line}
1107 < @var{from-file-line}@dots{}
1109 > @var{to-file-line}
1110 > @var{to-file-line}@dots{}
1113 There are three types of change commands. Each consists of a line
1114 number or comma-separated range of lines in the first file, a single
1115 character indicating the kind of change to make, and a line number or
1116 comma-separated range of lines in the second file. All line numbers are
1117 the original line numbers in each file. The types of change commands
1121 @item @var{l}a@var{r}
1122 Add the lines in range @var{r} of the second file after line @var{l} of
1123 the first file. For example, @samp{8a12,15} means append lines 12--15
1124 of file 2 after line 8 of file 1; or, if changing file 2 into file 1,
1125 delete lines 12--15 of file 2.
1127 @item @var{f}c@var{t}
1128 Replace the lines in range @var{f} of the first file with lines in range
1129 @var{t} of the second file. This is like a combined add and delete, but
1130 more compact. For example, @samp{5,7c8,10} means change lines 5--7 of
1131 file 1 to read as lines 8--10 of file 2; or, if changing file 2 into
1132 file 1, change lines 8--10 of file 2 to read as lines 5--7 of file 1.
1134 @item @var{r}d@var{l}
1135 Delete the lines in range @var{r} from the first file; line @var{l} is where
1136 they would have appeared in the second file had they not been deleted.
1137 For example, @samp{5,7d3} means delete lines 5--7 of file 1; or, if
1138 changing file 2 into file 1, append lines 5--7 of file 1 after line 3 of
1143 @section Making Edit Scripts
1144 @cindex script output formats
1146 Several output modes produce command scripts for editing @var{from-file}
1147 to produce @var{to-file}.
1150 * ed Scripts:: Using @command{diff} to produce commands for @command{ed}.
1151 * Forward ed:: Making forward @command{ed} scripts.
1152 * RCS:: A special @command{diff} output format used by @acronym{RCS}.
1156 @subsection @command{ed} Scripts
1157 @cindex @command{ed} script output format
1159 @command{diff} can produce commands that direct the @command{ed} text editor
1160 to change the first file into the second file. Long ago, this was the
1161 only output mode that was suitable for editing one file into another
1162 automatically; today, with @command{patch}, it is almost obsolete. Use the
1163 @option{-e} or @option{--ed} option to select this output format.
1165 Like the normal format (@pxref{Normal}), this output format does not
1166 show any context; unlike the normal format, it does not include the
1167 information necessary to apply the diff in reverse (to produce the first
1168 file if all you have is the second file and the diff).
1170 If the file @file{d} contains the output of @samp{diff -e old new}, then
1171 the command @samp{(cat d && echo w) | ed - old} edits @file{old} to make
1172 it a copy of @file{new}. More generally, if @file{d1}, @file{d2},
1173 @dots{}, @file{dN} contain the outputs of @samp{diff -e old new1},
1174 @samp{diff -e new1 new2}, @dots{}, @samp{diff -e newN-1 newN},
1175 respectively, then the command @samp{(cat d1 d2 @dots{} dN && echo w) |
1176 ed - old} edits @file{old} to make it a copy of @file{newN}.
1179 * Example ed:: A sample @command{ed} script.
1180 * Detailed ed:: A detailed description of @command{ed} format.
1184 @subsubsection Example @command{ed} Script
1186 Here is the output of @samp{diff -e lao tzu} (@pxref{Sample
1187 diff Input}, for the complete contents of the two files):
1191 They both may be called deep and profound.
1192 Deeper and more profound,
1193 The door of all subtleties!
1196 The named is the mother of all things.
1203 @subsubsection Detailed Description of @command{ed} Format
1205 The @command{ed} output format consists of one or more hunks of
1206 differences. The changes closest to the ends of the files come first so
1207 that commands that change the number of lines do not affect how
1208 @command{ed} interprets line numbers in succeeding commands. @command{ed}
1209 format hunks look like this:
1212 @var{change-command}
1214 @var{to-file-line}@dots{}
1218 Because @command{ed} uses a single period on a line to indicate the
1219 end of input, @acronym{GNU} @command{diff} protects lines of changes
1220 that contain a single period on a line by writing two periods instead,
1221 then writing a subsequent @command{ed} command to change the two
1222 periods into one. The @command{ed} format cannot represent an
1223 incomplete line, so if the second file ends in a changed incomplete
1224 line, @command{diff} reports an error and then pretends that a newline
1227 There are three types of change commands. Each consists of a line
1228 number or comma-separated range of lines in the first file and a single
1229 character indicating the kind of change to make. All line numbers are
1230 the original line numbers in the file. The types of change commands
1235 Add text from the second file after line @var{l} in the first file. For
1236 example, @samp{8a} means to add the following lines after line 8 of file
1240 Replace the lines in range @var{r} in the first file with the following
1241 lines. Like a combined add and delete, but more compact. For example,
1242 @samp{5,7c} means change lines 5--7 of file 1 to read as the text file
1246 Delete the lines in range @var{r} from the first file. For example,
1247 @samp{5,7d} means delete lines 5--7 of file 1.
1251 @subsection Forward @command{ed} Scripts
1252 @cindex forward @command{ed} script output format
1254 @command{diff} can produce output that is like an @command{ed} script, but
1255 with hunks in forward (front to back) order. The format of the commands
1256 is also changed slightly: command characters precede the lines they
1257 modify, spaces separate line numbers in ranges, and no attempt is made
1258 to disambiguate hunk lines consisting of a single period. Like
1259 @command{ed} format, forward @command{ed} format cannot represent incomplete
1262 Forward @command{ed} format is not very useful, because neither @command{ed}
1263 nor @command{patch} can apply diffs in this format. It exists mainly for
1264 compatibility with older versions of @command{diff}. Use the @option{-f} or
1265 @option{--forward-ed} option to select it.
1268 @subsection @acronym{RCS} Scripts
1269 @cindex @acronym{RCS} script output format
1271 The @acronym{RCS} output format is designed specifically for use by
1272 the Revision Control System, which is a set of free programs used for
1273 organizing different versions and systems of files. Use the
1274 @option{-n} or @option{--rcs} option to select this output format. It
1275 is like the forward @command{ed} format (@pxref{Forward ed}), but it
1276 can represent arbitrary changes to the contents of a file because it
1277 avoids the forward @command{ed} format's problems with lines
1278 consisting of a single period and with incomplete lines. Instead of
1279 ending text sections with a line consisting of a single period, each
1280 command specifies the number of lines it affects; a combination of the
1281 @samp{a} and @samp{d} commands are used instead of @samp{c}. Also, if
1282 the second file ends in a changed incomplete line, then the output
1283 also ends in an incomplete line.
1285 Here is the output of @samp{diff -n lao tzu} (@pxref{Sample
1286 diff Input}, for the complete contents of the two files):
1292 The named is the mother of all things.
1295 They both may be called deep and profound.
1296 Deeper and more profound,
1297 The door of all subtleties!
1301 @section Merging Files with If-then-else
1302 @cindex merged output format
1303 @cindex if-then-else output format
1304 @cindex C if-then-else output format
1305 @cindex @command{ifdef} output format
1307 You can use @command{diff} to merge two files of C source code. The output
1308 of @command{diff} in this format contains all the lines of both files.
1309 Lines common to both files are output just once; the differing parts are
1310 separated by the C preprocessor directives @code{#ifdef @var{name}} or
1311 @code{#ifndef @var{name}}, @code{#else}, and @code{#endif}. When
1312 compiling the output, you select which version to use by either defining
1313 or leaving undefined the macro @var{name}.
1315 To merge two files, use @command{diff} with the @option{-D @var{name}} or
1316 @option{--ifdef=@var{name}} option. The argument @var{name} is the C
1317 preprocessor identifier to use in the @code{#ifdef} and @code{#ifndef}
1320 For example, if you change an instance of @code{wait (&s)} to
1321 @code{waitpid (-1, &s, 0)} and then merge the old and new files with
1322 the @option{--ifdef=HAVE_WAITPID} option, then the affected part of your code
1323 might look like this:
1327 #ifndef HAVE_WAITPID
1328 if ((w = wait (&s)) < 0 && errno != EINTR)
1329 #else /* HAVE_WAITPID */
1330 if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR)
1331 #endif /* HAVE_WAITPID */
1333 @} while (w != child);
1336 You can specify formats for languages other than C by using line group
1337 formats and line formats, as described in the next sections.
1340 * Line Group Formats:: Formats for general if-then-else line groups.
1341 * Line Formats:: Formats for each line in a line group.
1342 * Example If-then-else:: Sample if-then-else format output.
1343 * Detailed If-then-else:: A detailed description of if-then-else format.
1346 @node Line Group Formats
1347 @subsection Line Group Formats
1348 @cindex line group formats
1349 @cindex formats for if-then-else line groups
1351 Line group formats let you specify formats suitable for many
1352 applications that allow if-then-else input, including programming
1353 languages and text formatting languages. A line group format specifies
1354 the output format for a contiguous group of similar lines.
1356 For example, the following command compares the TeX files @file{old}
1357 and @file{new}, and outputs a merged file in which old regions are
1358 surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new
1359 regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines.
1363 --old-group-format='\begin@{em@}
1366 --new-group-format='\begin@{bf@}
1372 The following command is equivalent to the above example, but it is a
1373 little more verbose, because it spells out the default line group formats.
1377 --old-group-format='\begin@{em@}
1380 --new-group-format='\begin@{bf@}
1383 --unchanged-group-format='%=' \
1384 --changed-group-format='\begin@{em@}
1392 Here is a more advanced example, which outputs a diff listing with
1393 headers containing line numbers in a ``plain English'' style.
1397 --unchanged-group-format='' \
1398 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
1400 --new-group-format='-------- %dN line%(N=1?:s) added after %de:
1402 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
1408 To specify a line group format, use @command{diff} with one of the options
1409 listed below. You can specify up to four line group formats, one for
1410 each kind of line group. You should quote @var{format}, because it
1411 typically contains shell metacharacters.
1414 @item --old-group-format=@var{format}
1415 These line groups are hunks containing only lines from the first file.
1416 The default old group format is the same as the changed group format if
1417 it is specified; otherwise it is a format that outputs the line group as-is.
1419 @item --new-group-format=@var{format}
1420 These line groups are hunks containing only lines from the second
1421 file. The default new group format is same as the changed group
1422 format if it is specified; otherwise it is a format that outputs the
1425 @item --changed-group-format=@var{format}
1426 These line groups are hunks containing lines from both files. The
1427 default changed group format is the concatenation of the old and new
1430 @item --unchanged-group-format=@var{format}
1431 These line groups contain lines common to both files. The default
1432 unchanged group format is a format that outputs the line group as-is.
1435 In a line group format, ordinary characters represent themselves;
1436 conversion specifications start with @samp{%} and have one of the
1441 stands for the lines from the first file, including the trailing newline.
1442 Each line is formatted according to the old line format (@pxref{Line Formats}).
1445 stands for the lines from the second file, including the trailing newline.
1446 Each line is formatted according to the new line format.
1449 stands for the lines common to both files, including the trailing newline.
1450 Each line is formatted according to the unchanged line format.
1453 stands for @samp{%}.
1456 where @var{C} is a single character, stands for @var{C}.
1457 @var{C} may not be a backslash or an apostrophe.
1458 For example, @samp{%c':'} stands for a colon, even inside
1459 the then-part of an if-then-else format, which a colon would
1463 where @var{O} is a string of 1, 2, or 3 octal digits,
1464 stands for the character with octal code @var{O}.
1465 For example, @samp{%c'\0'} stands for a null character.
1467 @item @var{F}@var{n}
1468 where @var{F} is a @code{printf} conversion specification and @var{n} is one
1469 of the following letters, stands for @var{n}'s value formatted with @var{F}.
1473 The line number of the line just before the group in the old file.
1476 The line number of the first line in the group in the old file;
1480 The line number of the last line in the group in the old file.
1483 The line number of the line just after the group in the old file;
1487 The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
1490 Likewise, for lines in the new file.
1495 The @code{printf} conversion specification can be @samp{%d},
1496 @samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal,
1497 lower case hexadecimal, or upper case hexadecimal output
1498 respectively. After the @samp{%} the following options can appear in
1499 sequence: a series of zero or more flags; an integer
1500 specifying the minimum field width; and a period followed by an
1501 optional integer specifying the minimum number of digits.
1502 The flags are @samp{-} for left-justification, @samp{'} for separating
1503 the digit into groups as specified by the @env{LC_NUMERIC} locale category,
1504 and @samp{0} for padding with zeros instead of spaces.
1505 For example, @samp{%5dN} prints the number of new lines in the group
1506 in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
1508 @item (@var{A}=@var{B}?@var{T}:@var{E})
1509 If @var{A} equals @var{B} then @var{T} else @var{E}.
1510 @var{A} and @var{B} are each either a decimal constant
1511 or a single letter interpreted as above.
1512 This format spec is equivalent to @var{T} if
1513 @var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}.
1515 For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
1516 @samp{no lines} if @var{N} (the number of lines in the group in the
1517 new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
1522 @subsection Line Formats
1523 @cindex line formats
1525 Line formats control how each line taken from an input file is
1526 output as part of a line group in if-then-else format.
1528 For example, the following command outputs text with a one-character
1529 change indicator to the left of the text. The first character of output
1530 is @samp{-} for deleted lines, @samp{|} for added lines, and a space for
1531 unchanged lines. The formats contain newline characters where newlines
1532 are desired on output.
1536 --old-line-format='-%l
1538 --new-line-format='|%l
1540 --unchanged-line-format=' %l
1545 To specify a line format, use one of the following options. You should
1546 quote @var{format}, since it often contains shell metacharacters.
1549 @item --old-line-format=@var{format}
1550 formats lines just from the first file.
1552 @item --new-line-format=@var{format}
1553 formats lines just from the second file.
1555 @item --unchanged-line-format=@var{format}
1556 formats lines common to both files.
1558 @item --line-format=@var{format}
1559 formats all lines; in effect, it sets all three above options simultaneously.
1562 In a line format, ordinary characters represent themselves;
1563 conversion specifications start with @samp{%} and have one of the
1568 stands for the contents of the line, not counting its trailing
1569 newline (if any). This format ignores whether the line is incomplete;
1570 @xref{Incomplete Lines}.
1573 stands for the contents of the line, including its trailing newline
1574 (if any). If a line is incomplete, this format preserves its
1578 stands for @samp{%}.
1581 where @var{C} is a single character, stands for @var{C}.
1582 @var{C} may not be a backslash or an apostrophe.
1583 For example, @samp{%c':'} stands for a colon.
1586 where @var{O} is a string of 1, 2, or 3 octal digits,
1587 stands for the character with octal code @var{O}.
1588 For example, @samp{%c'\0'} stands for a null character.
1591 where @var{F} is a @code{printf} conversion specification,
1592 stands for the line number formatted with @var{F}.
1593 For example, @samp{%.5dn} prints the line number using the
1594 @code{printf} format @code{"%.5d"}. @xref{Line Group Formats}, for
1595 more about printf conversion specifications.
1599 The default line format is @samp{%l} followed by a newline character.
1601 If the input contains tab characters and it is important that they line
1602 up on output, you should ensure that @samp{%l} or @samp{%L} in a line
1603 format is just after a tab stop (e.g.@: by preceding @samp{%l} or
1604 @samp{%L} with a tab character), or you should use the @option{-t} or
1605 @option{--expand-tabs} option.
1607 Taken together, the line and line group formats let you specify many
1608 different formats. For example, the following command uses a format
1609 similar to normal @command{diff} format. You can tailor this command
1610 to get fine control over @command{diff} output.
1614 --old-line-format='< %l
1616 --new-line-format='> %l
1618 --old-group-format='%df%(f=l?:,%dl)d%dE
1620 --new-group-format='%dea%dF%(F=L?:,%dL)
1622 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
1625 --unchanged-group-format='' \
1629 @node Example If-then-else
1630 @subsection An Example of If-then-else Format
1632 Here is the output of @samp{diff -DTWO lao tzu} (@pxref{Sample
1633 diff Input}, for the complete contents of the two files):
1637 The Way that can be told of is not the eternal Way;
1638 The name that can be named is not the eternal name.
1640 The Nameless is the origin of Heaven and Earth;
1642 The Named is the mother of all things.
1644 The named is the mother of all things.
1647 Therefore let there always be non-being,
1648 so we may see their subtlety,
1649 And let there always be being,
1650 so we may see their outcome.
1651 The two are the same,
1652 But after they are produced,
1653 they have different names.
1655 They both may be called deep and profound.
1656 Deeper and more profound,
1657 The door of all subtleties!
1661 @node Detailed If-then-else
1662 @subsection Detailed Description of If-then-else Format
1664 For lines common to both files, @command{diff} uses the unchanged line
1665 group format. For each hunk of differences in the merged output
1666 format, if the hunk contains only lines from the first file,
1667 @command{diff} uses the old line group format; if the hunk contains only
1668 lines from the second file, @command{diff} uses the new group format;
1669 otherwise, @command{diff} uses the changed group format.
1671 The old, new, and unchanged line formats specify the output format of
1672 lines from the first file, lines from the second file, and lines common
1673 to both files, respectively.
1675 The option @option{--ifdef=@var{name}} is equivalent to
1676 the following sequence of options using shell syntax:
1679 --old-group-format='#ifndef @var{name}
1680 %<#endif /* ! @var{name} */
1682 --new-group-format='#ifdef @var{name}
1683 %>#endif /* @var{name} */
1685 --unchanged-group-format='%=' \
1686 --changed-group-format='#ifndef @var{name}
1687 %<#else /* @var{name} */
1688 %>#endif /* @var{name} */
1692 You should carefully check the @command{diff} output for proper nesting.
1693 For example, when using the @option{-D @var{name}} or
1694 @option{--ifdef=@var{name}} option, you should check that if the
1695 differing lines contain any of the C preprocessor directives
1696 @samp{#ifdef}, @samp{#ifndef}, @samp{#else}, @samp{#elif}, or
1697 @samp{#endif}, they are nested properly and match. If they don't, you
1698 must make corrections manually. It is a good idea to carefully check
1699 the resulting code anyway to make sure that it really does what you
1700 want it to; depending on how the input files were produced, the output
1701 might contain duplicate or otherwise incorrect code.
1703 The @command{patch} @option{-D @var{name}} option behaves like
1704 the @command{diff} @option{-D @var{name}} option, except it operates on
1705 a file and a diff to produce a merged file; @xref{patch Options}.
1707 @node Incomplete Lines
1708 @chapter Incomplete Lines
1709 @cindex incomplete lines
1711 @cindex newline treatment by @command{diff}
1713 When an input file ends in a non-newline character, its last line is
1714 called an @dfn{incomplete line} because its last character is not a
1715 newline. All other lines are called @dfn{full lines} and end in a
1716 newline character. Incomplete lines do not match full lines unless
1717 differences in white space are ignored (@pxref{White Space}).
1719 An incomplete line is normally distinguished on output from a full
1720 line by a following line that starts with @samp{\}. However, the
1721 @acronym{RCS} format (@pxref{RCS}) outputs the incomplete line as-is,
1722 without any trailing newline or following line. The side by side
1723 format normally represents incomplete lines as-is, but in some cases
1724 uses a @samp{\} or @samp{/} gutter marker; @xref{Side by Side}. The
1725 if-then-else line format preserves a line's incompleteness with
1726 @samp{%L}, and discards the newline with @samp{%l}; @xref{Line
1727 Formats}. Finally, with the @command{ed} and forward @command{ed}
1728 output formats (@pxref{Output Formats}) @command{diff} cannot
1729 represent an incomplete line, so it pretends there was a newline and
1732 For example, suppose @file{F} and @file{G} are one-byte files that
1733 contain just @samp{f} and @samp{g}, respectively. Then @samp{diff F G}
1739 \ No newline at end of file
1742 \ No newline at end of file
1746 (The exact message may differ in non-English locales.)
1747 @samp{diff -n F G} outputs the following without a trailing newline:
1756 @samp{diff -e F G} reports two errors and outputs the following:
1764 @node Comparing Directories
1765 @chapter Comparing Directories
1768 You can use @command{diff} to compare some or all of the files in two
1769 directory trees. When both file name arguments to @command{diff} are
1770 directories, it compares each file that is contained in both
1771 directories, examining file names in alphabetical order as specified by
1772 the @env{LC_COLLATE} locale category. Normally
1773 @command{diff} is silent about pairs of files that contain no differences,
1774 but if you use the @option{-s} or @option{--report-identical-files} option,
1775 it reports pairs of identical files. Normally @command{diff} reports
1776 subdirectories common to both directories without comparing
1777 subdirectories' files, but if you use the @option{-r} or
1778 @option{--recursive} option, it compares every corresponding pair of files
1779 in the directory trees, as many levels deep as they go.
1781 For file names that are in only one of the directories, @command{diff}
1782 normally does not show the contents of the file that exists; it reports
1783 only that the file exists in that directory and not in the other. You
1784 can make @command{diff} act as though the file existed but was empty in the
1785 other directory, so that it outputs the entire contents of the file that
1786 actually exists. (It is output as either an insertion or a
1787 deletion, depending on whether it is in the first or the second
1788 directory given.) To do this, use the @option{-N} or @option{--new-file}
1791 If the older directory contains one or more large files that are not in
1792 the newer directory, you can make the patch smaller by using the
1793 @option{--unidirectional-new-file} option instead of @option{-N}.
1794 This option is like @option{-N} except that it only inserts the contents
1795 of files that appear in the second directory but not the first (that is,
1796 files that were added). At the top of the patch, write instructions for
1797 the user applying the patch to remove the files that were deleted before
1798 applying the patch. @xref{Making Patches}, for more discussion of
1799 making patches for distribution.
1801 To ignore some files while comparing directories, use the @option{-x
1802 @var{pattern}} or @option{--exclude=@var{pattern}} option. This option
1803 ignores any files or subdirectories whose base names match the shell
1804 pattern @var{pattern}. Unlike in the shell, a period at the start of
1805 the base of a file name matches a wildcard at the start of a pattern.
1806 You should enclose @var{pattern} in quotes so that the shell does not
1807 expand it. For example, the option @option{-x '*.[ao]'} ignores any file
1808 whose name ends with @samp{.a} or @samp{.o}.
1810 This option accumulates if you specify it more than once. For example,
1811 using the options @option{-x 'RCS' -x '*,v'} ignores any file or
1812 subdirectory whose base name is @samp{RCS} or ends with @samp{,v}.
1814 If you need to give this option many times, you can instead put the
1815 patterns in a file, one pattern per line, and use the @option{-X
1816 @var{file}} or @option{--exclude-from=@var{file}} option. Trailing
1817 white space and empty lines are ignored in the pattern file.
1819 If you have been comparing two directories and stopped partway through,
1820 later you might want to continue where you left off. You can do this by
1821 using the @option{-S @var{file}} or @option{--starting-file=@var{file}}
1822 option. This compares only the file @var{file} and all alphabetically
1823 later files in the topmost directory level.
1825 If two directories differ only in that file names are lower case in
1826 one directory and upper case in the upper, @command{diff} normally
1827 reports many differences because it compares file names in a
1828 case sensitive way. With the @option{--ignore-file-name-case} option,
1829 @command{diff} ignores case differences in file names, so that for example
1830 the contents of the file @file{Tao} in one directory are compared to
1831 the contents of the file @file{TAO} in the other. The
1832 @option{--no-ignore-file-name-case} option cancels the effect of the
1833 @option{--ignore-file-name-case} option, reverting to the default
1836 If an @option{-x @var{pattern}} or @option{--exclude=@var{pattern}}
1837 option, or an @option{-X @var{file}} or
1838 @option{--exclude-from=@var{file}} option,
1839 is specified while the @option{--ignore-file-name-case} option is in
1840 effect, case is ignored when excluding file names matching the
1843 @node Adjusting Output
1844 @chapter Making @command{diff} Output Prettier
1846 @command{diff} provides several ways to adjust the appearance of its output.
1847 These adjustments can be applied to any output format.
1850 * Tabs:: Preserving the alignment of tab stops.
1851 * Pagination:: Page numbering and time-stamping @command{diff} output.
1855 @section Preserving Tab Stop Alignment
1856 @cindex tab stop alignment
1857 @cindex aligning tab stops
1859 The lines of text in some of the @command{diff} output formats are
1860 preceded by one or two characters that indicate whether the text is
1861 inserted, deleted, or changed. The addition of those characters can
1862 cause tabs to move to the next tab stop, throwing off the alignment of
1863 columns in the line. @acronym{GNU} @command{diff} provides two ways
1864 to make tab-aligned columns line up correctly.
1866 The first way is to have @command{diff} convert all tabs into the correct
1867 number of spaces before outputting them; select this method with the
1868 @option{-t} or @option{--expand-tabs} option. To use this form of output with
1869 @command{patch}, you must give @command{patch} the @option{-l} or
1870 @option{--ignore-white-space} option (@pxref{Changed White Space}, for more
1871 information). @command{diff} normally assumes that tab stops are set
1872 every 8 print columns, but this can be altered by the
1873 @option{--tabsize=@var{columns}} option.
1875 The other method for making tabs line up correctly is to add a tab
1876 character instead of a space after the indicator character at the
1877 beginning of the line. This ensures that all following tab characters
1878 are in the same position relative to tab stops that they were in the
1879 original files, so that the output is aligned correctly. Its
1880 disadvantage is that it can make long lines too long to fit on one line
1881 of the screen or the paper. It also does not work with the unified
1882 output format, which does not have a space character after the change
1883 type indicator character. Select this method with the @option{-T} or
1884 @option{--initial-tab} option.
1887 @section Paginating @command{diff} Output
1888 @cindex paginating @command{diff} output
1890 It can be convenient to have long output page-numbered and time-stamped.
1891 The @option{-l} or @option{--paginate} option does this by sending the
1892 @command{diff} output through the @command{pr} program. Here is what the page
1893 header might look like for @samp{diff -lc lao tzu}:
1896 2002-02-22 14:20 diff -lc lao tzu Page 1
1899 @node diff Performance
1900 @chapter @command{diff} Performance Tradeoffs
1901 @cindex performance of @command{diff}
1903 @acronym{GNU} @command{diff} runs quite efficiently; however, in some
1904 circumstances you can cause it to run faster or produce a more compact
1907 One way to improve @command{diff} performance is to use hard or
1908 symbolic links to files instead of copies. This improves performance
1909 because @command{diff} normally does not need to read two hard or
1910 symbolic links to the same file, since their contents must be
1911 identical. For example, suppose you copy a large directory hierarchy,
1912 make a few changes to the copy, and then often use @samp{diff -r} to
1913 compare the original to the copy. If the original files are
1914 read-only, you can greatly improve performance by creating the copy
1915 using hard or symbolic links (e.g., with @acronym{GNU} @samp{cp -lR} or
1916 @samp{cp -sR}). Before editing a file in the copy for the first time,
1917 you should break the link and replace it with a regular copy.
1919 You can also affect the performance of @acronym{GNU} @command{diff} by
1920 giving it options that change the way it compares files.
1921 Performance has more than one dimension. These options improve one
1922 aspect of performance at the cost of another, or they improve
1923 performance in some cases while hurting it in others.
1925 The way that @acronym{GNU} @command{diff} determines which lines have
1926 changed always comes up with a near-minimal set of differences.
1927 Usually it is good enough for practical purposes. If the
1928 @command{diff} output is large, you might want @command{diff} to use a
1929 modified algorithm that sometimes produces a smaller set of
1930 differences. The @option{-d} or @option{--minimal} option does this;
1931 however, it can also cause @command{diff} to run more slowly than
1932 usual, so it is not the default behavior.
1934 When the files you are comparing are large and have small groups of
1935 changes scattered throughout them, you can use the
1936 @option{--speed-large-files} option to make a different modification to
1937 the algorithm that @command{diff} uses. If the input files have a constant
1938 small density of changes, this option speeds up the comparisons without
1939 changing the output. If not, @command{diff} might produce a larger set of
1940 differences; however, the output will still be correct.
1942 Normally @command{diff} discards the prefix and suffix that is common to
1943 both files before it attempts to find a minimal set of differences.
1944 This makes @command{diff} run faster, but occasionally it may produce
1945 non-minimal output. The @option{--horizon-lines=@var{lines}} option
1946 prevents @command{diff} from discarding the last @var{lines} lines of the
1947 prefix and the first @var{lines} lines of the suffix. This gives
1948 @command{diff} further opportunities to find a minimal output.
1950 Suppose a run of changed lines includes a sequence of lines at one end
1951 and there is an identical sequence of lines just outside the other end.
1952 The @command{diff} command is free to choose which identical sequence is
1953 included in the hunk. In this case, @command{diff} normally shifts the
1954 hunk's boundaries when this merges adjacent hunks, or shifts a hunk's
1955 lines towards the end of the file. Merging hunks can make the output
1956 look nicer in some cases.
1958 @node Comparing Three Files
1959 @chapter Comparing Three Files
1960 @cindex comparing three files
1961 @cindex format of @command{diff3} output
1963 Use the program @command{diff3} to compare three files and show any
1964 differences among them. (@command{diff3} can also merge files; see
1965 @ref{diff3 Merging}).
1967 The ``normal'' @command{diff3} output format shows each hunk of
1968 differences without surrounding context. Hunks are labeled depending
1969 on whether they are two-way or three-way, and lines are annotated by
1970 their location in the input files.
1972 @xref{Invoking diff3}, for more information on how to run @command{diff3}.
1975 * Sample diff3 Input:: Sample @command{diff3} input for examples.
1976 * Example diff3 Normal:: Sample output in the normal format.
1977 * diff3 Hunks:: The format of normal output format.
1978 * Detailed diff3 Normal:: A detailed description of normal output format.
1981 @node Sample diff3 Input
1982 @section A Third Sample Input File
1983 @cindex @command{diff3} sample input
1984 @cindex sample input for @command{diff3}
1986 Here is a third sample file that will be used in examples to illustrate
1987 the output of @command{diff3} and how various options can change it. The
1988 first two files are the same that we used for @command{diff} (@pxref{Sample
1989 diff Input}). This is the third sample file, called @file{tao}:
1992 The Way that can be told of is not the eternal Way;
1993 The name that can be named is not the eternal name.
1994 The Nameless is the origin of Heaven and Earth;
1995 The named is the mother of all things.
1997 Therefore let there always be non-being,
1998 so we may see their subtlety,
1999 And let there always be being,
2000 so we may see their result.
2001 The two are the same,
2002 But after they are produced,
2003 they have different names.
2005 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2008 @node Example diff3 Normal
2009 @section An Example of @command{diff3} Normal Format
2011 Here is the output of the command @samp{diff3 lao tzu tao}
2012 (@pxref{Sample diff3 Input}, for the complete contents of the files).
2013 Notice that it shows only the lines that are different among the three
2020 The Way that can be told of is not the eternal Way;
2021 The name that can be named is not the eternal name.
2025 The Named is the mother of all things.
2028 The named is the mother of all things.
2033 so we may see their outcome.
2035 so we may see their result.
2039 They both may be called deep and profound.
2040 Deeper and more profound,
2041 The door of all subtleties!
2044 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2047 @node Detailed diff3 Normal
2048 @section Detailed Description of @command{diff3} Normal Format
2050 Each hunk begins with a line marked @samp{====}. Three-way hunks have
2051 plain @samp{====} lines, and two-way hunks have @samp{1}, @samp{2}, or
2052 @samp{3} appended to specify which of the three input files differ in
2053 that hunk. The hunks contain copies of two or three sets of input
2054 lines each preceded by one or two commands identifying where the lines
2057 Normally, two spaces precede each copy of an input line to distinguish
2058 it from the commands. But with the @option{-T} or @option{--initial-tab}
2059 option, @command{diff3} uses a tab instead of two spaces; this lines up
2060 tabs correctly. @xref{Tabs}, for more information.
2062 Commands take the following forms:
2065 @item @var{file}:@var{l}a
2066 This hunk appears after line @var{l} of file @var{file}, and
2067 contains no lines in that file. To edit this file to yield the other
2068 files, one must append hunk lines taken from the other files. For
2069 example, @samp{1:11a} means that the hunk follows line 11 in the first
2070 file and contains no lines from that file.
2072 @item @var{file}:@var{r}c
2073 This hunk contains the lines in the range @var{r} of file @var{file}.
2074 The range @var{r} is a comma-separated pair of line numbers, or just one
2075 number if the range is a singleton. To edit this file to yield the
2076 other files, one must change the specified lines to be the lines taken
2077 from the other files. For example, @samp{2:11,13c} means that the hunk
2078 contains lines 11 through 13 from the second file.
2081 If the last line in a set of input lines is incomplete
2082 (@pxref{Incomplete Lines}), it is distinguished on output from a full
2083 line by a following line that starts with @samp{\}.
2086 @section @command{diff3} Hunks
2087 @cindex hunks for @command{diff3}
2088 @cindex @command{diff3} hunks
2090 Groups of lines that differ in two or three of the input files are
2091 called @dfn{diff3 hunks}, by analogy with @command{diff} hunks
2092 (@pxref{Hunks}). If all three input files differ in a @command{diff3}
2093 hunk, the hunk is called a @dfn{three-way hunk}; if just two input files
2094 differ, it is a @dfn{two-way hunk}.
2096 As with @command{diff}, several solutions are possible. When comparing the
2097 files @samp{A}, @samp{B}, and @samp{C}, @command{diff3} normally finds
2098 @command{diff3} hunks by merging the two-way hunks output by the two
2099 commands @samp{diff A B} and @samp{diff A C}. This does not necessarily
2100 minimize the size of the output, but exceptions should be rare.
2102 For example, suppose @file{F} contains the three lines @samp{a},
2103 @samp{b}, @samp{f}, @file{G} contains the lines @samp{g}, @samp{b},
2104 @samp{g}, and @file{H} contains the lines @samp{a}, @samp{b},
2105 @samp{h}. @samp{diff3 F G H} might output the following:
2124 because it found a two-way hunk containing @samp{a} in the first and
2125 third files and @samp{g} in the second file, then the single line
2126 @samp{b} common to all three files, then a three-way hunk containing
2127 the last line of each file.
2130 @chapter Merging From a Common Ancestor
2131 @cindex merging from a common ancestor
2133 When two people have made changes to copies of the same file,
2134 @command{diff3} can produce a merged output that contains both sets of
2135 changes together with warnings about conflicts.
2137 One might imagine programs with names like @command{diff4} and @command{diff5}
2138 to compare more than three files simultaneously, but in practice the
2139 need rarely arises. You can use @command{diff3} to merge three or more
2140 sets of changes to a file by merging two change sets at a time.
2142 @command{diff3} can incorporate changes from two modified versions into a
2143 common preceding version. This lets you merge the sets of changes
2144 represented by the two newer files. Specify the common ancestor version
2145 as the second argument and the two newer versions as the first and third
2146 arguments, like this:
2149 diff3 @var{mine} @var{older} @var{yours}
2153 You can remember the order of the arguments by noting that they are in
2158 You can think of this as subtracting @var{older} from @var{yours} and
2159 adding the result to @var{mine}, or as merging into @var{mine} the
2160 changes that would turn @var{older} into @var{yours}. This merging is
2161 well-defined as long as @var{mine} and @var{older} match in the
2162 neighborhood of each such change. This fails to be true when all three
2163 input files differ or when only @var{older} differs; we call this
2164 a @dfn{conflict}. When all three input files differ, we call the
2165 conflict an @dfn{overlap}.
2167 @command{diff3} gives you several ways to handle overlaps and conflicts.
2168 You can omit overlaps or conflicts, or select only overlaps,
2169 or mark conflicts with special @samp{<<<<<<<} and @samp{>>>>>>>} lines.
2171 @command{diff3} can output the merge results as an @command{ed} script that
2172 that can be applied to the first file to yield the merged output.
2173 However, it is usually better to have @command{diff3} generate the merged
2174 output directly; this bypasses some problems with @command{ed}.
2177 * Which Changes:: Selecting changes to incorporate.
2178 * Marking Conflicts:: Marking conflicts.
2179 * Bypassing ed:: Generating merged output directly.
2180 * Merging Incomplete Lines:: How @command{diff3} merges incomplete lines.
2181 * Saving the Changed File:: Emulating System V behavior.
2185 @section Selecting Which Changes to Incorporate
2186 @cindex overlapping change, selection of
2187 @cindex unmerged change
2189 You can select all unmerged changes from @var{older} to @var{yours} for merging
2190 into @var{mine} with the @option{-e} or @option{--ed} option. You can
2191 select only the nonoverlapping unmerged changes with @option{-3} or
2192 @option{--easy-only}, and you can select only the overlapping changes with
2193 @option{-x} or @option{--overlap-only}.
2195 The @option{-e}, @option{-3} and @option{-x} options select only
2196 @dfn{unmerged changes}, i.e.@: changes where @var{mine} and @var{yours}
2197 differ; they ignore changes from @var{older} to @var{yours} where
2198 @var{mine} and @var{yours} are identical, because they assume that such
2199 changes have already been merged. If this assumption is not a safe
2200 one, you can use the @option{-A} or @option{--show-all} option
2201 (@pxref{Marking Conflicts}).
2203 Here is the output of the command @command{diff3} with each of these three
2204 options (@pxref{Sample diff3 Input}, for the complete contents of the files).
2205 Notice that @option{-e} outputs the union of the disjoint sets of changes
2206 output by @option{-3} and @option{-x}.
2208 Output of @samp{diff3 -e lao tzu tao}:
2212 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2215 so we may see their result.
2219 Output of @samp{diff3 -3 lao tzu tao}:
2222 so we may see their result.
2226 Output of @samp{diff3 -x lao tzu tao}:
2230 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2234 @node Marking Conflicts
2235 @section Marking Conflicts
2236 @cindex conflict marking
2237 @cindex @samp{<<<<<<<} for marking conflicts
2239 @command{diff3} can mark conflicts in the merged output by
2240 bracketing them with special marker lines. A conflict
2241 that comes from two files @var{A} and @var{B} is marked as follows:
2245 @r{lines from @var{A}}
2247 @r{lines from @var{B}}
2251 A conflict that comes from three files @var{A}, @var{B} and @var{C} is
2256 @r{lines from @var{A}}
2258 @r{lines from @var{B}}
2260 @r{lines from @var{C}}
2264 The @option{-A} or @option{--show-all} option acts like the @option{-e}
2265 option, except that it brackets conflicts, and it outputs all changes
2266 from @var{older} to @var{yours}, not just the unmerged changes. Thus,
2267 given the sample input files (@pxref{Sample diff3 Input}), @samp{diff3
2268 -A lao tzu tao} puts brackets around the conflict where only @file{tzu}
2274 The Way that can be told of is not the eternal Way;
2275 The name that can be named is not the eternal name.
2279 And it outputs the three-way conflict as follows:
2284 They both may be called deep and profound.
2285 Deeper and more profound,
2286 The door of all subtleties!
2289 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2293 The @option{-E} or @option{--show-overlap} option outputs less information
2294 than the @option{-A} or @option{--show-all} option, because it outputs only
2295 unmerged changes, and it never outputs the contents of the second
2296 file. Thus the @option{-E} option acts like the @option{-e} option,
2297 except that it brackets the first and third files from three-way
2298 overlapping changes. Similarly, @option{-X} acts like @option{-x}, except
2299 it brackets all its (necessarily overlapping) changes. For example,
2300 for the three-way overlapping change above, the @option{-E} and @option{-X}
2301 options output the following:
2307 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2311 If you are comparing files that have meaningless or uninformative names,
2312 you can use the @option{--label=@var{label}}
2313 option to show alternate names in the @samp{<<<<<<<}, @samp{|||||||}
2314 and @samp{>>>>>>>} brackets. This option can be given up to three
2315 times, once for each input file. Thus @samp{diff3 -A --label X
2316 --label Y --label Z A
2317 B C} acts like @samp{diff3 -A A B C}, except that the output looks like
2318 it came from files named @samp{X}, @samp{Y} and @samp{Z} rather than
2319 from files named @samp{A}, @samp{B} and @samp{C}.
2322 @section Generating the Merged Output Directly
2323 @cindex merged @command{diff3} format
2325 With the @option{-m} or @option{--merge} option, @command{diff3} outputs the
2326 merged file directly. This is more efficient than using @command{ed} to
2327 generate it, and works even with non-text files that @command{ed} would
2328 reject. If you specify @option{-m} without an @command{ed} script option,
2329 @option{-A} is assumed.
2331 For example, the command @samp{diff3 -m lao tzu tao}
2332 (@pxref{Sample diff3 Input} for a copy of the input files) would output
2338 The Way that can be told of is not the eternal Way;
2339 The name that can be named is not the eternal name.
2341 The Nameless is the origin of Heaven and Earth;
2342 The Named is the mother of all things.
2343 Therefore let there always be non-being,
2344 so we may see their subtlety,
2345 And let there always be being,
2346 so we may see their result.
2347 The two are the same,
2348 But after they are produced,
2349 they have different names.
2352 They both may be called deep and profound.
2353 Deeper and more profound,
2354 The door of all subtleties!
2357 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2361 @node Merging Incomplete Lines
2362 @section How @command{diff3} Merges Incomplete Lines
2363 @cindex incomplete line merging
2365 With @option{-m}, incomplete lines (@pxref{Incomplete Lines}) are simply
2366 copied to the output as they are found; if the merged output ends in an
2367 conflict and one of the input files ends in an incomplete
2368 line, succeeding @samp{|||||||}, @samp{=======} or @samp{>>>>>>>}
2369 brackets appear somewhere other than the start of a line because
2370 they are appended to the incomplete line.
2372 Without @option{-m}, if an @command{ed} script option is specified and an
2373 incomplete line is found, @command{diff3} generates a warning and acts as
2374 if a newline had been present.
2376 @node Saving the Changed File
2377 @section Saving the Changed File
2378 @cindex System V @command{diff3} compatibility
2380 Traditional Unix @command{diff3} generates an @command{ed} script without the
2381 trailing @samp{w} and @samp{q} commands that save the changes.
2382 System V @command{diff3} generates these extra commands. @acronym{GNU}
2383 @command{diff3} normally behaves like traditional Unix
2384 @command{diff3}, but with the @option{-i} option it behaves like
2385 System V @command{diff3} and appends the @samp{w} and @samp{q}
2388 The @option{-i} option requires one of the @command{ed} script options
2389 @option{-AeExX3}, and is incompatible with the merged output option
2392 @node Interactive Merging
2393 @chapter Interactive Merging with @command{sdiff}
2394 @cindex diff merging
2395 @cindex interactive merging
2397 With @command{sdiff}, you can merge two files interactively based on a
2398 side-by-side @option{-y} format comparison (@pxref{Side by Side}). Use
2399 @option{-o @var{file}} or @option{--output=@var{file}} to specify where to
2400 put the merged text. @xref{Invoking sdiff}, for more details on the
2401 options to @command{sdiff}.
2403 Another way to merge files interactively is to use the Emacs Lisp
2404 package @command{emerge}. @xref{emerge, , emerge, emacs, The
2405 @acronym{GNU} Emacs Manual}, for more information.
2408 * sdiff Option Summary:: Summary of @command{sdiff} options.
2409 * Merge Commands:: Merging two files interactively.
2412 @node sdiff Option Summary
2413 @section Specifying @command{diff} Options to @command{sdiff}
2414 @cindex @command{sdiff} output format
2416 The following @command{sdiff} options have the same meaning as for
2417 @command{diff}. @xref{diff Options}, for the use of these options.
2421 -B -E -I @var{regexp}
2424 --ignore-blank-lines --ignore-case
2425 --ignore-matching-lines=@var{regexp} --ignore-space-change
2426 --ignore-tab-expansion
2427 --left-column --minimal --speed-large-files
2428 --strip-trailing-cr --suppress-common-lines
2429 --tabsize=@var{columns} --text --version --width=@var{columns}
2432 For historical reasons, @command{sdiff} has alternate names for some
2433 options. The @option{-l} option is equivalent to the
2434 @option{--left-column} option, and similarly @option{-s} is equivalent
2435 to @option{--suppress-common-lines}. The meaning of the @command{sdiff}
2436 @option{-w} and @option{-W} options is interchanged from that of
2437 @command{diff}: with @command{sdiff}, @option{-w @var{columns}} is
2438 equivalent to @option{--width=@var{columns}}, and @option{-W} is
2439 equivalent to @option{--ignore-all-space}. @command{sdiff} without the
2440 @option{-o} option is equivalent to @command{diff} with the @option{-y}
2441 or @option{--side-by-side} option (@pxref{Side by Side}).
2443 @node Merge Commands
2444 @section Merge Commands
2445 @cindex merge commands
2446 @cindex merging interactively
2448 Groups of common lines, with a blank gutter, are copied from the first
2449 file to the output. After each group of differing lines, @command{sdiff}
2450 prompts with @samp{%} and pauses, waiting for one of the following
2451 commands. Follow each command with @key{RET}.
2455 Discard both versions.
2456 Invoke a text editor on an empty temporary file,
2457 then copy the resulting file to the output.
2460 Concatenate the two versions, edit the result in a temporary file,
2461 then copy the edited result to the output.
2464 Like @samp{eb}, except precede each version with a header that
2465 shows what file and lines the version came from.
2469 Edit a copy of the left version, then copy the result to the output.
2473 Edit a copy of the right version, then copy the result to the output.
2477 Copy the left version to the output.
2484 Copy the right version to the output.
2487 Silently copy common lines.
2490 Verbosely copy common lines. This is the default.
2494 The text editor invoked is specified by the @env{EDITOR} environment
2495 variable if it is set. The default is system-dependent.
2497 @node Merging with patch
2498 @chapter Merging with @command{patch}
2500 @command{patch} takes comparison output produced by @command{diff} and applies
2501 the differences to a copy of the original file, producing a patched
2502 version. With @command{patch}, you can distribute just the changes to a
2503 set of files instead of distributing the entire file set; your
2504 correspondents can apply @command{patch} to update their copy of the files
2505 with your changes. @command{patch} automatically determines the diff
2506 format, skips any leading or trailing headers, and uses the headers to
2507 determine which file to patch. This lets your correspondents feed a
2508 mail message containing a difference listing directly to
2511 @command{patch} detects and warns about common problems like forward
2512 patches. It saves any patches that it could not apply. It can also maintain a
2513 @code{patchlevel.h} file to ensure that your correspondents apply
2514 diffs in the proper order.
2516 @command{patch} accepts a series of diffs in its standard input, usually
2517 separated by headers that specify which file to patch. It applies
2518 @command{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not
2519 exactly match the original file, @command{patch} uses heuristics to try to
2520 patch the file as well as it can. If no approximate match can be found,
2521 @command{patch} rejects the hunk and skips to the next hunk. @command{patch}
2522 normally replaces each file @var{f} with its new version, putting reject
2523 hunks (if any) into @samp{@var{f}.rej}.
2525 @xref{Invoking patch}, for detailed information on the options to
2529 * patch Input:: Selecting the type of @command{patch} input.
2530 * Revision Control:: Getting files from @acronym{RCS}, @acronym{SCCS}, etc.
2531 * Imperfect:: Dealing with imperfect patches.
2532 * Creating and Removing:: Creating and removing files with a patch.
2533 * Patching Time Stamps:: Updating time stamps on patched files.
2534 * Multiple Patches:: Handling multiple patches in a file.
2535 * patch Directories:: Changing directory and stripping directories.
2536 * Backups:: Whether backup files are made.
2537 * Backup Names:: Backup file names.
2538 * Reject Names:: Reject file names.
2539 * patch Messages:: Messages and questions @command{patch} can produce.
2540 * patch and POSIX:: Conformance to the @acronym{POSIX} standard.
2541 * patch and Tradition:: @acronym{GNU} versus traditional @command{patch}.
2545 @section Selecting the @command{patch} Input Format
2546 @cindex @command{patch} input format
2548 @command{patch} normally determines which @command{diff} format the patch
2549 file uses by examining its contents. For patch files that contain
2550 particularly confusing leading text, you might need to use one of the
2551 following options to force @command{patch} to interpret the patch file as a
2552 certain format of diff. The output formats listed here are the only
2553 ones that @command{patch} can understand.
2562 @command{ed} script.
2573 @node Revision Control
2574 @section Revision Control
2575 @cindex revision control
2576 @cindex version control
2577 @cindex @acronym{RCS}
2579 @cindex @acronym{SCCS}
2581 If a nonexistent input file is under a revision control system
2582 supported by @command{patch}, @command{patch} normally asks the user
2583 whether to get (or check out) the file from the revision control
2584 system. Patch currently supports @acronym{RCS}, ClearCase and
2585 @acronym{SCCS}. Under @acronym{RCS} and @acronym{SCCS},
2586 @command{patch} also asks when the input file is read-only and matches
2587 the default version in the revision control system.
2590 The @option{-g @var{num}} or @option{--get=@var{num}} option affects access
2591 to files under supported revision control systems. If @var{num} is
2592 positive, @command{patch} gets the file without asking the user; if
2593 zero, @command{patch} neither asks the user nor gets the file; and if
2594 negative, @command{patch} asks the user before getting the file. The
2595 default value of @var{num} is given by the value of the
2596 @env{PATCH_GET} environment variable if it is set; if not, the default
2597 value is zero if @command{patch} is conforming to @acronym{POSIX}, negative
2598 otherwise. @xref{patch and POSIX}.
2600 @vindex VERSION_CONTROL
2601 The choice of revision control system is unaffected by the
2602 @env{VERSION_CONTROL} environment variable (@pxref{Backup Names}).
2605 @section Applying Imperfect Patches
2606 @cindex imperfect patch application
2608 @command{patch} tries to skip any leading text in the patch file,
2609 apply the diff, and then skip any trailing text. Thus you can feed a
2610 mail message directly to @command{patch}, and it should work. If the
2611 entire diff is indented by a constant amount of white space,
2612 @command{patch} automatically ignores the indentation. If a context
2613 diff contains trailing carriage return on each line, @command{patch}
2614 automatically ignores the carriage return. If a context diff has been
2615 encapsulated by prepending @w{@samp{- }} to lines beginning with @samp{-}
2616 as per @uref{ftp://ftp.isi.edu/in-notes/rfc934.txt, Internet RFC 934},
2617 @command{patch} automatically unencapsulates the input.
2619 However, certain other types of imperfect input require user
2620 intervention or testing.
2623 * Changed White Space:: When tabs and spaces don't match exactly.
2624 * Reversed Patches:: Applying reversed patches correctly.
2625 * Inexact:: Helping @command{patch} find close matches.
2626 * Dry Runs:: Predicting what @command{patch} will do.
2629 @node Changed White Space
2630 @subsection Applying Patches with Changed White Space
2631 @cindex white space in patches
2633 Sometimes mailers, editors, or other programs change spaces into tabs,
2634 or vice versa. If this happens to a patch file or an input file, the
2635 files might look the same, but @command{patch} will not be able to match
2636 them properly. If this problem occurs, use the @option{-l} or
2637 @option{--ignore-white-space} option, which makes @command{patch} compare
2638 blank characters (i.e.@: spaces and tabs) loosely so that any nonempty
2639 sequence of blanks in the patch file matches any nonempty sequence of
2640 blanks in the input files. Non-blank
2641 characters must still match exactly. Each line of the context must
2642 still match a line in the input file.
2644 @node Reversed Patches
2645 @subsection Applying Reversed Patches
2646 @cindex reversed patches
2648 Sometimes people run @command{diff} with the new file first instead of
2649 second. This creates a diff that is ``reversed''. To apply such
2650 patches, give @command{patch} the @option{-R} or @option{--reverse} option.
2651 @command{patch} then attempts to swap each hunk around before applying it.
2652 Rejects come out in the swapped format.
2654 Often @command{patch} can guess that the patch is reversed. If the first
2655 hunk of a patch fails, @command{patch} reverses the hunk to see if it can
2656 apply it that way. If it can, @command{patch} asks you if you want to have
2657 the @option{-R} option set; if it can't, @command{patch} continues to apply
2658 the patch normally. This method cannot detect a reversed patch if it is
2659 a normal diff and the first command is an append (which should have been
2660 a delete) since appends always succeed, because a null context matches
2661 anywhere. But most patches add or change lines rather than delete them,
2662 so most reversed normal diffs begin with a delete, which fails, and
2663 @command{patch} notices.
2665 If you apply a patch that you have already applied, @command{patch} thinks
2666 it is a reversed patch and offers to un-apply the patch. This could be
2667 construed as a feature. If you did this inadvertently and you don't
2668 want to un-apply the patch, just answer @samp{n} to this offer and to
2669 the subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the
2670 @command{patch} process.
2673 @subsection Helping @command{patch} Find Inexact Matches
2674 @cindex inexact patches
2675 @cindex fuzz factor when patching
2677 For context diffs, and to a lesser extent normal diffs, @command{patch} can
2678 detect when the line numbers mentioned in the patch are incorrect, and
2679 it attempts to find the correct place to apply each hunk of the patch.
2680 As a first guess, it takes the line number mentioned in the hunk, plus
2681 or minus any offset used in applying the previous hunk. If that is not
2682 the correct place, @command{patch} scans both forward and backward for a
2683 set of lines matching the context given in the hunk.
2685 First @command{patch} looks for a place where all lines of the context
2686 match. If it cannot find such a place, and it is reading a context or
2687 unified diff, and the maximum fuzz factor is set to 1 or more, then
2688 @command{patch} makes another scan, ignoring the first and last line of
2689 context. If that fails, and the maximum fuzz factor is set to 2 or
2690 more, it makes another scan, ignoring the first two and last two lines
2691 of context are ignored. It continues similarly if the maximum fuzz
2694 The @option{-F @var{lines}} or @option{--fuzz=@var{lines}} option sets the
2695 maximum fuzz factor to @var{lines}. This option only applies to context
2696 and unified diffs; it ignores up to @var{lines} lines while looking for
2697 the place to install a hunk. Note that a larger fuzz factor increases
2698 the odds of making a faulty patch. The default fuzz factor is 2; there
2699 is no point to setting it to more than the number of lines of context
2700 in the diff, ordinarily 3.
2702 If @command{patch} cannot find a place to install a hunk of the patch, it
2703 writes the hunk out to a reject file (@pxref{Reject Names}, for information
2704 on how reject files are named). It writes out rejected hunks in context
2705 format no matter what form the input patch is in. If the input is a
2706 normal or @command{ed} diff, many of the contexts are simply null. The
2707 line numbers on the hunks in the reject file may be different from those
2708 in the patch file: they show the approximate location where @command{patch}
2709 thinks the failed hunks belong in the new file rather than in the old
2712 If the @option{--verbose} option is given, then
2713 as it completes each hunk @command{patch} tells you whether the hunk
2714 succeeded or failed, and if it failed, on which line (in the new file)
2715 @command{patch} thinks the hunk should go. If this is different from the
2716 line number specified in the diff, it tells you the offset. A single
2717 large offset @emph{may} indicate that @command{patch} installed a hunk in
2718 the wrong place. @command{patch} also tells you if it used a fuzz factor
2719 to make the match, in which case you should also be slightly suspicious.
2721 @command{patch} cannot tell if the line numbers are off in an @command{ed}
2722 script, and can only detect wrong line numbers in a normal diff when it
2723 finds a change or delete command. It may have the same problem with a
2724 context diff using a fuzz factor equal to or greater than the number of
2725 lines of context shown in the diff (typically 3). In these cases, you
2726 should probably look at a context diff between your original and patched
2727 input files to see if the changes make sense. Compiling without errors
2728 is a pretty good indication that the patch worked, but not a guarantee.
2730 A patch against an empty file applies to a nonexistent file, and vice
2731 versa. @xref{Creating and Removing}.
2733 @command{patch} usually produces the correct results, even when it must
2734 make many guesses. However, the results are guaranteed only when
2735 the patch is applied to an exact copy of the file that the patch was
2739 @subsection Predicting what @command{patch} will do
2740 @cindex testing @command{patch}
2741 @cindex dry runs for @command{patch}
2743 It may not be obvious in advance what @command{patch} will do with a
2744 complicated or poorly formatted patch. If you are concerned that the
2745 input might cause @command{patch} to modify the wrong files, you can
2746 use the @option{--dry-run} option, which causes @command{patch} to
2747 print the results of applying patches without actually changing any
2748 files. You can then inspect the diagnostics generated by the dry run
2749 to see whether @command{patch} will modify the files that you expect.
2750 If the patch does not do what you want, you can modify the patch (or
2751 the other options to @command{patch}) and try another dry run. Once
2752 you are satisfied with the proposed patch you can apply it by invoking
2753 @command{patch} as before, but this time without the
2754 @option{--dry-run} option.
2756 @node Creating and Removing
2757 @section Creating and Removing Files
2758 @cindex creating files
2759 @cindex empty files, removing
2760 @cindex removing empty files
2762 Sometimes when comparing two directories, a file may exist in one
2763 directory but not the other. If you give @command{diff} the
2764 @option{-N} or @option{--new-file} option, or if you supply an old or
2765 new file that is named @file{/dev/null} or is empty and is dated the
2766 Epoch (1970-01-01 00:00:00 UTC), @command{diff} outputs a patch that
2767 adds or deletes the contents of this file. When given such a patch,
2768 @command{patch} normally creates a new file or removes the old file.
2769 However, when conforming to @acronym{POSIX} (@pxref{patch and POSIX}),
2770 @command{patch} does not remove the old file, but leaves it empty.
2771 The @option{-E} or @option{--remove-empty-files} option causes
2772 @command{patch} to remove output files that are empty after applying a
2773 patch, even if the patch does not appear to be one that removed the
2776 If the patch appears to create a file that already exists,
2777 @command{patch} asks for confirmation before applying the patch.
2779 @node Patching Time Stamps
2780 @section Updating Time Stamps on Patched Files
2781 @cindex time stamps on patched files
2783 When @command{patch} updates a file, it normally sets the file's
2784 last-modified time stamp to the current time of day. If you are using
2785 @command{patch} to track a software distribution, this can cause
2786 @command{make} to incorrectly conclude that a patched file is out of
2787 date. For example, if @file{syntax.c} depends on @file{syntax.y}, and
2788 @command{patch} updates @file{syntax.c} and then @file{syntax.y}, then
2789 @file{syntax.c} will normally appear to be out of date with respect to
2790 @file{syntax.y} even though its contents are actually up to date.
2792 The @option{-Z} or @option{--set-utc} option causes @command{patch} to
2793 set a patched file's modification and access times to the time stamps
2794 given in context diff headers. If the context diff headers do not
2795 specify a time zone, they are assumed to use Coordinated Universal
2796 Time (@acronym{UTC}, often known as @acronym{GMT}).
2798 The @option{-T} or @option{--set-time} option acts like @option{-Z} or
2799 @option{--set-utc}, except that it assumes that the context diff
2800 headers' time stamps use local time instead of @acronym{UTC}. This option
2801 is not recommended, because patches using local time cannot easily be
2802 used by people in other time zones, and because local time stamps are
2803 ambiguous when local clocks move backwards during daylight-saving time
2804 adjustments. If the context diff headers specify a time zone, this
2805 option is equivalent to @option{-Z} or @option{--set-utc}.
2807 @command{patch} normally refrains from setting a file's time stamps if
2808 the file's original last-modified time stamp does not match the time
2809 given in the diff header, of if the file's contents do not exactly
2810 match the patch. However, if the @option{-f} or @option{--force}
2811 option is given, the file's time stamps are set regardless.
2813 Due to the limitations of the current @command{diff} format,
2814 @command{patch} cannot update the times of files whose contents have
2815 not changed. Also, if you set file time stamps to values other than
2816 the current time of day, you should also remove (e.g., with @samp{make
2817 clean}) all files that depend on the patched files, so that later
2818 invocations of @command{make} do not get confused by the patched
2821 @node Multiple Patches
2822 @section Multiple Patches in a File
2823 @cindex multiple patches
2824 @cindex intuiting file names from patches
2826 If the patch file contains more than one patch, and if you do not
2827 specify an input file on the command line, @command{patch} tries to
2828 apply each patch as if they came from separate patch files. This
2829 means that it determines the name of the file to patch for each patch,
2830 and that it examines the leading text before each patch for file names
2831 and prerequisite revision level (@pxref{Making Patches}, for more on
2834 @command{patch} uses the following rules to intuit a file name from
2835 the leading text before a patch. First, @command{patch} takes an
2836 ordered list of candidate file names as follows:
2840 If the header is that of a context diff, @command{patch} takes the old
2841 and new file names in the header. A name is ignored if it does not
2842 have enough slashes to satisfy the @option{-p@var{num}} or
2843 @option{--strip=@var{num}} option. The name @file{/dev/null} is also
2847 If there is an @samp{Index:} line in the leading garbage and if either
2848 the old and new names are both absent or if @command{patch} is
2849 conforming to @acronym{POSIX}, @command{patch} takes the name in the
2853 For the purpose of the following rules, the candidate file names are
2854 considered to be in the order (old, new, index), regardless of the
2855 order that they appear in the header.
2859 Then @command{patch} selects a file name from the candidate list as
2864 If some of the named files exist, @command{patch} selects the first
2865 name if conforming to @acronym{POSIX}, and the best name otherwise.
2868 If @command{patch} is not ignoring @acronym{RCS}, ClearCase, and @acronym{SCCS}
2869 (@pxref{Revision Control}), and no named files exist but an @acronym{RCS},
2870 ClearCase, or @acronym{SCCS} master is found, @command{patch} selects the
2871 first named file with an @acronym{RCS}, ClearCase, or @acronym{SCCS} master.
2874 If no named files exist, no @acronym{RCS}, ClearCase, or @acronym{SCCS} master
2875 was found, some names are given, @command{patch} is not conforming to
2876 @acronym{POSIX}, and the patch appears to create a file, @command{patch}
2877 selects the best name requiring the creation of the fewest
2881 If no file name results from the above heuristics, you are asked for
2882 the name of the file to patch, and @command{patch} selects that name.
2885 To determine the @dfn{best} of a nonempty list of file names,
2886 @command{patch} first takes all the names with the fewest path name
2887 components; of those, it then takes all the names with the shortest
2888 basename; of those, it then takes all the shortest names; finally, it
2889 takes the first remaining name.
2891 @xref{patch and POSIX}, to see whether @command{patch} is conforming
2894 @node patch Directories
2895 @section Applying Patches in Other Directories
2896 @cindex directories and patch
2897 @cindex patching directories
2899 The @option{-d @var{directory}} or @option{--directory=@var{directory}}
2900 option to @command{patch} makes directory @var{directory} the current
2901 directory for interpreting both file names in the patch file, and file
2902 names given as arguments to other options (such as @option{-B} and
2903 @option{-o}). For example, while in a mail reading program, you can patch
2904 a file in the @file{/usr/src/emacs} directory directly from a message
2905 containing the patch like this:
2908 | patch -d /usr/src/emacs
2911 Sometimes the file names given in a patch contain leading directories,
2912 but you keep your files in a directory different from the one given in
2913 the patch. In those cases, you can use the
2914 @option{-p@var{number}} or @option{--strip=@var{number}}
2915 option to set the file name strip count to @var{number}. The strip
2916 count tells @command{patch} how many slashes, along with the directory
2917 names between them, to strip from the front of file names. A sequence
2918 of one or more adjacent slashes is counted as a single slash. By
2919 default, @command{patch} strips off all leading directories, leaving
2920 just the base file names.
2922 For example, suppose the file name in the patch file is
2923 @file{/gnu/src/emacs/etc/NEWS}. Using @option{-p0} gives the
2924 entire file name unmodified, @option{-p1} gives
2925 @file{gnu/src/emacs/etc/NEWS} (no leading slash), @option{-p4} gives
2926 @file{etc/NEWS}, and not specifying @option{-p} at all gives @file{NEWS}.
2928 @command{patch} looks for each file (after any slashes have been stripped)
2929 in the current directory, or if you used the @option{-d @var{directory}}
2930 option, in that directory.
2933 @section Backup Files
2934 @cindex backup file strategy
2936 Normally, @command{patch} creates a backup file if the patch does not
2937 exactly match the original input file, because in that case the
2938 original data might not be recovered if you undo the patch with
2939 @samp{patch -R} (@pxref{Reversed Patches}). However, when conforming
2940 to @acronym{POSIX}, @command{patch} does not create backup files by
2941 default. @xref{patch and POSIX}.
2943 The @option{-b} or @option{--backup} option causes @command{patch} to
2944 make a backup file regardless of whether the patch matches the
2945 original input. The @option{--backup-if-mismatch} option causes
2946 @command{patch} to create backup files for mismatches files; this is
2947 the default when not conforming to @acronym{POSIX}. The
2948 @option{--no-backup-if-mismatch} option causes @command{patch} to not
2949 create backup files, even for mismatched patches; this is the default
2950 when conforming to @acronym{POSIX}.
2952 When backing up a file that does not exist, an empty, unreadable
2953 backup file is created as a placeholder to represent the nonexistent
2957 @section Backup File Names
2958 @cindex backup file names
2960 Normally, @command{patch} renames an original input file into a backup
2961 file by appending to its name the extension @samp{.orig}, or @samp{~}
2962 if using @samp{.orig} would make the backup file name too
2963 long.@footnote{A coding error in @acronym{GNU} @command{patch} version
2964 2.5.4 causes it to always use @samp{~}, but this should be fixed in
2965 the next release.} The @option{-z @var{backup-suffix}} or
2966 @option{--suffix=@var{backup-suffix}} option causes @command{patch} to
2967 use @var{backup-suffix} as the backup extension instead.
2969 @vindex SIMPLE_BACKUP_SUFFIX
2970 Alternately, you can specify the extension for backup files with the
2971 @env{SIMPLE_BACKUP_SUFFIX} environment variable, which the options
2974 @command{patch} can also create numbered backup files the way
2975 @acronym{GNU} Emacs does. With this method, instead of having a
2976 single backup of each file, @command{patch} makes a new backup file
2977 name each time it patches a file. For example, the backups of a file
2978 named @file{sink} would be called, successively, @file{sink.~1~},
2979 @file{sink.~2~}, @file{sink.~3~}, etc.
2981 @vindex PATCH_VERSION_CONTROL
2982 @vindex VERSION_CONTROL
2983 The @option{-V @var{backup-style}} or
2984 @option{--version-control=@var{backup-style}} option takes as an
2985 argument a method for creating backup file names. You can alternately
2986 control the type of backups that @command{patch} makes with the
2987 @env{PATCH_VERSION_CONTROL} environment variable, which the
2988 @option{-V} option overrides. If @env{PATCH_VERSION_CONTROL} is not
2989 set, the @env{VERSION_CONTROL} environment variable is used instead.
2990 Please note that these options and variables control backup file
2991 names; they do not affect the choice of revision control system
2992 (@pxref{Revision Control}).
2994 The values of these environment variables and the argument to the
2995 @option{-V} option are like the @acronym{GNU} Emacs @code{version-control}
2996 variable (@pxref{Backup Names, , , emacs, The @acronym{GNU} Emacs Manual},
2997 for more information on backup versions in Emacs). They also
2998 recognize synonyms that are more descriptive. The valid values are
2999 listed below; unique abbreviations are acceptable.
3004 Always make numbered backups.
3008 Make numbered backups of files that already have them, simple backups of
3009 the others. This is the default.
3013 Always make simple backups.
3016 You can also tell @command{patch} to prepend a prefix, such as a
3017 directory name, to produce backup file names. The @option{-B
3018 @var{prefix}} or @option{--prefix=@var{prefix}} option makes backup
3019 files by prepending @var{prefix} to them. The @option{-Y
3020 @var{prefix}} or @option{--basename-prefix=@var{prefix}} prepends
3021 @var{prefix} to the last file name component of backup file names
3022 instead; for example, @option{-Y ~} causes the backup name for
3023 @file{dir/file.c} to be @file{dir/~file.c}. If you use either of
3024 these prefix options, the suffix-based options are ignored.
3026 If you specify the output file with the @option{-o} option, that file is
3027 the one that is backed up, not the input file.
3029 Options that affect the names of backup files do not affect whether
3030 backups are made. For example, if you specify the
3031 @option{--no-backup-if-mismatch} option, none of the options described
3032 in this section have any affect, because no backups are made.
3035 @section Reject File Names
3036 @cindex reject file names
3038 The names for reject files (files containing patches that
3039 @command{patch} could not find a place to apply) are normally the name
3040 of the output file with @samp{.rej} appended (or @samp{#} if using
3041 @samp{.rej} would make the backup file name too long).
3043 Alternatively, you can tell @command{patch} to place all of the rejected
3044 patches in a single file. The @option{-r @var{reject-file}} or
3045 @option{--reject-file=@var{reject-file}} option uses @var{reject-file} as
3046 the reject file name.
3048 @node patch Messages
3049 @section Messages and Questions from @command{patch}
3050 @cindex @command{patch} messages and questions
3051 @cindex diagnostics from @command{patch}
3052 @cindex messages from @command{patch}
3054 @command{patch} can produce a variety of messages, especially if it
3055 has trouble decoding its input. In a few situations where it's not
3056 sure how to proceed, @command{patch} normally prompts you for more
3057 information from the keyboard. There are options to produce more or
3058 fewer messages, to have it not ask for keyboard input, and to
3059 affect the way that file names are quoted in messages.
3062 * More or Fewer Messages:: Controlling the verbosity of @command{patch}.
3063 * patch and Keyboard Input:: Inhibiting keyboard input.
3064 * patch Quoting Style:: Quoting file names in diagnostics.
3067 @command{patch} exits with status 0 if all hunks are applied successfully,
3068 1 if some hunks cannot be applied, and 2 if there is more serious trouble.
3069 When applying a set of patches in a loop, you should check the
3070 exit status, so you don't apply a later patch to a partially patched
3073 @node More or Fewer Messages
3074 @subsection Controlling the Verbosity of @command{patch}
3075 @cindex verbose messages from @command{patch}
3076 @cindex inhibit messages from @command{patch}
3078 You can cause @command{patch} to produce more messages by using the
3079 @option{--verbose} option. For example, when you give this option,
3080 the message @samp{Hmm...} indicates that @command{patch} is reading text in
3081 the patch file, attempting to determine whether there is a patch in that
3082 text, and if so, what kind of patch it is.
3084 You can inhibit all terminal output from @command{patch}, unless an error
3085 occurs, by using the @option{-s}, @option{--quiet}, or @option{--silent}
3088 @node patch and Keyboard Input
3089 @subsection Inhibiting Keyboard Input
3090 @cindex keyboard input to @command{patch}
3092 There are two ways you can prevent @command{patch} from asking you any
3093 questions. The @option{-f} or @option{--force} option assumes that you know
3094 what you are doing. It causes @command{patch} to do the following:
3098 Skip patches that do not contain file names in their headers.
3101 Patch files even though they have the wrong version for the
3102 @samp{Prereq:} line in the patch;
3105 Assume that patches are not reversed even if they look like they are.
3109 The @option{-t} or @option{--batch} option is similar to @option{-f}, in that
3110 it suppresses questions, but it makes somewhat different assumptions:
3114 Skip patches that do not contain file names in their headers
3115 (the same as @option{-f}).
3118 Skip patches for which the file has the wrong version for the
3119 @samp{Prereq:} line in the patch;
3122 Assume that patches are reversed if they look like they are.
3125 @node patch Quoting Style
3126 @subsection @command{patch} Quoting Style
3127 @cindex quoting style
3129 When @command{patch} outputs a file name in a diagnostic message, it
3130 can format the name in any of several ways. This can be useful to
3131 output file names unambiguously, even if they contain punctuation or
3132 special characters like newlines. The
3133 @option{--quoting-style=@var{word}} option controls how names are
3134 output. The @var{word} should be one of the following:
3140 Quote names for the shell if they contain shell metacharacters or would
3141 cause ambiguous output.
3143 Quote names for the shell, even if they would normally not require quoting.
3145 Quote names as for a C language string.
3147 Quote as with @samp{c} except omit the surrounding double-quote
3149 @c The following are not yet implemented in patch 2.5.4.
3151 @c Quote as with @samp{c} except use quotation marks appropriate for the
3154 @c @c Use @t instead of @samp to avoid duplicate quoting in some output styles.
3155 @c Like @samp{clocale}, but quote @t{`like this'} instead of @t{"like
3156 @c this"} in the default C locale. This looks nicer on many displays.
3159 @vindex QUOTING_STYLE
3160 You can specify the default value of the @option{--quoting-style}
3161 option with the environment variable @env{QUOTING_STYLE}. If that
3162 environment variable is not set, the default value is @samp{shell},
3163 but this default may change in a future version of @command{patch}.
3165 @node patch and POSIX
3166 @section @command{patch} and the @acronym{POSIX} Standard
3167 @cindex @acronym{POSIX}
3169 @vindex POSIXLY_CORRECT
3170 If you specify the @option{--posix} option, or set the
3171 @env{POSIXLY_CORRECT} environment variable, @command{patch} conforms
3172 more strictly to the @acronym{POSIX} standard, as follows:
3176 Take the first existing file from the list (old, new, index)
3177 when intuiting file names from diff headers. @xref{Multiple Patches}.
3180 Do not remove files that are removed by a diff.
3181 @xref{Creating and Removing}.
3184 Do not ask whether to get files from @acronym{RCS}, ClearCase, or
3185 @acronym{SCCS}. @xref{Revision Control}.
3188 Require that all options precede the files in the command line.
3191 Do not backup files, even when there is a mismatch. @xref{Backups}.
3195 @node patch and Tradition
3196 @section @acronym{GNU} @command{patch} and Traditional @command{patch}
3197 @cindex traditional @command{patch}
3199 The current version of @acronym{GNU} @command{patch} normally follows the
3200 @acronym{POSIX} standard. @xref{patch and POSIX}, for the few exceptions
3201 to this general rule.
3203 Unfortunately, @acronym{POSIX} redefined the behavior of @command{patch} in
3204 several important ways. You should be aware of the following
3205 differences if you must interoperate with traditional @command{patch},
3206 or with @acronym{GNU} @command{patch} version 2.1 and earlier.
3210 In traditional @command{patch}, the @option{-p} option's operand was
3211 optional, and a bare @option{-p} was equivalent to @option{-p0}. The
3212 @option{-p} option now requires an operand, and @option{-p@ 0} is now
3213 equivalent to @option{-p0}. For maximum compatibility, use options
3214 like @option{-p0} and @option{-p1}.
3216 Also, traditional @command{patch} simply counted slashes when
3217 stripping path prefixes; @command{patch} now counts pathname
3218 components. That is, a sequence of one or more adjacent slashes now
3219 counts as a single slash. For maximum portability, avoid sending
3220 patches containing @file{//} in file names.
3223 In traditional @command{patch}, backups were enabled by default. This
3224 behavior is now enabled with the @option{-b} or @option{--backup}
3227 Conversely, in @acronym{POSIX} @command{patch}, backups are never made,
3228 even when there is a mismatch. In @acronym{GNU} @command{patch}, this
3229 behavior is enabled with the @option{--no-backup-if-mismatch} option,
3230 or by conforming to @acronym{POSIX}.
3232 The @option{-b@ @var{suffix}} option of traditional @command{patch} is
3233 equivalent to the @samp{-b -z@ @var{suffix}} options of @acronym{GNU}
3237 Traditional @command{patch} used a complicated (and incompletely
3238 documented) method to intuit the name of the file to be patched from
3239 the patch header. This method did not conform to @acronym{POSIX}, and had
3240 a few gotchas. Now @command{patch} uses a different, equally
3241 complicated (but better documented) method that is optionally
3242 @acronym{POSIX}-conforming; we hope it has fewer gotchas. The two methods
3243 are compatible if the file names in the context diff header and the
3244 @samp{Index:} line are all identical after prefix-stripping. Your
3245 patch is normally compatible if each header's file names all contain
3246 the same number of slashes.
3249 When traditional @command{patch} asked the user a question, it sent
3250 the question to standard error and looked for an answer from the first
3251 file in the following list that was a terminal: standard error,
3252 standard output, @file{/dev/tty}, and standard input. Now
3253 @command{patch} sends questions to standard output and gets answers
3254 from @file{/dev/tty}. Defaults for some answers have been changed so
3255 that @command{patch} never goes into an infinite loop when using
3259 Traditional @command{patch} exited with a status value that counted
3260 the number of bad hunks, or with status 1 if there was real trouble.
3261 Now @command{patch} exits with status 1 if some hunks failed, or with
3262 2 if there was real trouble.
3265 Limit yourself to the following options when sending instructions
3266 meant to be executed by anyone running @acronym{GNU} @command{patch},
3267 traditional @command{patch}, or a @command{patch} that conforms to
3268 @acronym{POSIX}. Spaces are significant in the following list, and
3269 operands are required.
3273 @option{-d @var{dir}}
3274 @option{-D @var{define}}
3279 @option{-o @var{outfile}}
3280 @option{-p@var{num}}
3282 @option{-r @var{rejectfile}}
3287 @node Making Patches
3288 @chapter Tips for Making and Using Patches
3290 Use some common sense when making and using patches. For example,
3291 when sending bug fixes to a program's maintainer, send several small
3292 patches, one per independent subject, instead of one large,
3293 harder-to-digest patch that covers all the subjects.
3295 Here are some other things you should keep in mind if you are going to
3296 distribute patches for updating a software package.
3299 * Tips for Patch Producers:: Advice for making patches.
3300 * Tips for Patch Consumers:: Advice for using patches.
3301 * Avoiding Common Mistakes:: Avoiding common mistakes when using @command{patch}.
3302 * Generating Smaller Patches:: How to generate smaller patches.
3305 @node Tips for Patch Producers
3306 @section Tips for Patch Producers
3307 @cindex patch producer tips
3309 To create a patch that changes an older version of a package into a
3310 newer version, first make a copy of the older and newer versions in
3311 adjacent subdirectories. It is common to do that by unpacking
3312 @command{tar} archives of the two versions.
3314 To generate the patch, use the command @samp{diff -Naur @var{old}
3315 @var{new}} where @var{old} and @var{new} identify the old and new
3316 directories. The names @var{old} and @var{new} should not contain any
3317 slashes. The @option{-N} option lets the patch create and remove
3318 files; @option{-a} lets the patch update non-text files; @option{-u}
3319 generates useful time stamps and enough context; and @option{-r} lets
3320 the patch update subdirectories. Here is an example command, using
3321 Bourne shell syntax:
3324 diff -Naur gcc-3.0.3 gcc-3.0.4
3327 Tell your recipients how to apply the patches. This should include
3328 which working directory to use, and which @command{patch} options to
3329 use; the option @samp{-p1} is recommended. Test your procedure by
3330 pretending to be a recipient and applying your patches to a copy of
3333 @xref{Avoiding Common Mistakes}, for how to avoid common mistakes when
3336 @node Tips for Patch Consumers
3337 @section Tips for Patch Consumers
3338 @cindex patch consumer tips
3340 A patch producer should tell recipients how to apply the patches, so
3341 the first rule of thumb for a patch consumer is to follow the
3342 instructions supplied with the patch.
3344 @acronym{GNU} @command{diff} can analyze files with arbitrarily long lines
3345 and files that end in incomplete lines. However, older versions of
3346 @command{patch} cannot patch such files. If you are having trouble
3347 applying such patches, try upgrading to a recent version of @acronym{GNU}
3350 @node Avoiding Common Mistakes
3351 @section Avoiding Common Mistakes
3352 @cindex common mistakes with patches
3353 @cindex patch, common mistakes
3355 When producing a patch for multiple files, apply @command{diff} to
3356 directories whose names do not have slashes. This reduces confusion
3357 when the patch consumer specifies the @option{-p@var{number}} option,
3358 since this option can have surprising results when the old and new
3359 file names have different numbers of slashes. For example, do not
3360 send a patch with a header that looks like this:
3363 diff -Naur v2.0.29/prog/README prog/README
3364 --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
3365 +++ prog/README 2002-03-17 20:49:32.442260588 -0800
3369 because the two file names have different numbers of slashes, and
3370 different versions of @command{patch} interpret the file names
3371 differently. To avoid confusion, send output that looks like this
3375 diff -Naur v2.0.29/prog/README v2.0.30/prog/README
3376 --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
3377 +++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800
3380 Make sure you have specified the file names correctly, either in a
3381 context diff header or with an @samp{Index:} line. Take care to not send out
3382 reversed patches, since these make people wonder whether they have
3383 already applied the patch.
3385 Avoid sending patches that compare backup file names like
3386 @file{README.orig} or @file{README~}, since this might confuse
3387 @command{patch} into patching a backup file instead of the real file.
3388 Instead, send patches that compare the same base file names in
3389 different directories, e.g.@: @file{old/README} and @file{new/README}.
3391 To save people from partially applying a patch before other patches that
3392 should have gone before it, you can make the first patch in the patch
3393 file update a file with a name like @file{patchlevel.h} or
3394 @file{version.c}, which contains a patch level or version number. If
3395 the input file contains the wrong version number, @command{patch} will
3396 complain immediately.
3398 An even clearer way to prevent this problem is to put a @samp{Prereq:}
3399 line before the patch. If the leading text in the patch file contains a
3400 line that starts with @samp{Prereq:}, @command{patch} takes the next word
3401 from that line (normally a version number) and checks whether the next
3402 input file contains that word, preceded and followed by either
3403 white space or a newline. If not, @command{patch} prompts you for
3404 confirmation before proceeding. This makes it difficult to accidentally
3405 apply patches in the wrong order.
3407 @node Generating Smaller Patches
3408 @section Generating Smaller Patches
3409 @cindex patches, shrinking
3411 The simplest way to generate a patch is to use @samp{diff -Naur}
3412 (@pxref{Tips for Patch Producers}), but you might be able to reduce
3413 the size of the patch by renaming or removing some files before making
3414 the patch. If the older version of the package contains any files
3415 that the newer version does not, or if any files have been renamed
3416 between the two versions, make a list of @command{rm} and @command{mv}
3417 commands for the user to execute in the old version directory before
3418 applying the patch. Then run those commands yourself in the scratch
3421 If there are any files that you don't need to include in the patch
3422 because they can easily be rebuilt from other files (for example,
3423 @file{TAGS} and output from @command{yacc} and @command{makeinfo}),
3424 exclude them from the patch by giving @command{diff} the @option{-x
3425 @var{pattern}} option (@pxref{Comparing Directories}). If you want
3426 your patch to modify a derived file because your recipients lack tools
3427 to build it, make sure that the patch for the derived file follows any
3428 patches for files that it depends on, so that the recipients' time
3429 stamps will not confuse @command{make}.
3431 Now you can create the patch using @samp{diff -Naur}. Make sure to
3432 specify the scratch directory first and the newer directory second.
3434 Add to the top of the patch a note telling the user any @command{rm} and
3435 @command{mv} commands to run before applying the patch. Then you can
3436 remove the scratch directory.
3438 You can also shrink the patch size by using fewer lines of context,
3439 but bear in mind that @command{patch} typically needs at least two
3440 lines for proper operation when patches do not exactly match the input
3444 @chapter Invoking @command{cmp}
3445 @cindex invoking @command{cmp}
3446 @cindex @command{cmp} invocation
3448 The @command{cmp} command compares two files, and if they differ,
3449 tells the first byte and line number where they differ or reports
3450 that one file is a prefix of the other. Bytes and
3451 lines are numbered starting with 1. The arguments of @command{cmp}
3455 cmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file} @r{[}@var{from-skip} @r{[}@var{to-skip}@r{]}@r{]}@r{]}
3458 The file name @file{-} is always the standard input. @command{cmp}
3459 also uses the standard input if one file name is omitted. The
3460 @var{from-skip} and @var{to-skip} operands specify how many bytes to
3461 ignore at the start of each file; they are equivalent to the
3462 @option{--ignore-initial=@var{from-skip}:@var{to-skip}} option.
3464 By default, @command{cmp} outputs nothing if the two files have the
3465 same contents. If one file is a prefix of the other, @command{cmp}
3466 prints to standard error a message of the following form:
3469 cmp: EOF on @var{shorter-file}
3472 Otherwise, @command{cmp} prints to standard output a message of the
3476 @var{from-file} @var{to-file} differ: char @var{byte-number}, line @var{line-number}
3479 The message formats can differ outside the @acronym{POSIX} locale.
3480 Also, @acronym{POSIX} allows the @acronym{EOF} message to be followed
3481 by a blank and some additional information.
3483 An exit status of 0 means no differences were found, 1 means some
3484 differences were found, and 2 means trouble.
3487 * cmp Options:: Summary of options to @command{cmp}.
3491 @section Options to @command{cmp}
3492 @cindex @command{cmp} options
3493 @cindex options for @command{cmp}
3495 Below is a summary of all of the options that @acronym{GNU}
3496 @command{cmp} accepts. Most options have two equivalent names, one of
3497 which is a single letter preceded by @samp{-}, and the other of which
3498 is a long name preceded by @samp{--}. Multiple single letter options
3499 (unless they take an argument) can be combined into a single command
3500 line word: @option{-bl} is equivalent to @option{-b -l}.
3504 @itemx --print-bytes
3505 Print the differing bytes. Display control bytes as a
3506 @samp{^} followed by a letter of the alphabet and precede bytes
3507 that have the high bit set with @samp{M-} (which stands for ``meta'').
3510 Output a summary of usage and then exit.
3513 @itemx --ignore-initial=@var{skip}
3514 Ignore any differences in the first @var{skip} bytes of the input
3515 files. Treat files with fewer than @var{skip} bytes as if they are
3516 empty. If @var{skip} is of the form
3517 @option{@var{from-skip}:@var{to-skip}}, skip the first @var{from-skip}
3518 bytes of the first input file and the first @var{to-skip} bytes of the
3523 Output the (decimal) byte numbers and (octal) values of all differing bytes,
3524 instead of the default standard output.
3526 @item -n @var{count}
3527 @itemx --bytes=@var{count}
3528 Compare at most @var{count} input bytes.
3533 Do not print anything; only return an exit status indicating whether
3538 Output version information and then exit.
3541 In the above table, operands that are byte counts are normally
3542 decimal, but may be preceded by @samp{0} for octal and @samp{0x} for
3545 A byte count can be followed by a suffix to specify a multiple of that
3546 count; in this case an omitted integer is understood to be 1. A bare
3547 size letter, or one followed by @samp{iB}, specifies a multiple using
3548 powers of 1024. A size letter followed by @samp{B} specifies powers
3549 of 1000 instead. For example, @option{-n 4M} and @option{-n 4MiB} are
3550 equivalent to @option{-n 4194304}, whereas @option{-n 4MB} is
3551 equivalent to @option{-n 4000000}. This notation is upward compatible
3552 with the @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI
3553 prefixes} for decimal multiples and with the
3554 @uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2
3555 prefixes for binary multiples}.
3557 The following suffixes are defined. Large sizes like @code{1Y} may be
3558 rejected by your computer due to limitations of its arithmetic.
3562 @cindex kilobyte, definition of
3563 kilobyte: @math{10^3 = 1000}.
3567 @cindex kibibyte, definition of
3568 kibibyte: @math{2^10 = 1024}. @samp{K} is special: the SI prefix is
3569 @samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and
3570 @acronym{POSIX} use @samp{k} to mean @samp{KiB}.
3572 @cindex megabyte, definition of
3573 megabyte: @math{10^6 = 1,000,000}.
3576 @cindex mebibyte, definition of
3577 mebibyte: @math{2^20 = 1,048,576}.
3579 @cindex gigabyte, definition of
3580 gigabyte: @math{10^9 = 1,000,000,000}.
3583 @cindex gibibyte, definition of
3584 gibibyte: @math{2^30 = 1,073,741,824}.
3586 @cindex terabyte, definition of
3587 terabyte: @math{10^12 = 1,000,000,000,000}.
3590 @cindex tebibyte, definition of
3591 tebibyte: @math{2^40 = 1,099,511,627,776}.
3593 @cindex petabyte, definition of
3594 petabyte: @math{10^15 = 1,000,000,000,000,000}.
3597 @cindex pebibyte, definition of
3598 pebibyte: @math{2^50 = 1,125,899,906,842,624}.
3600 @cindex exabyte, definition of
3601 exabyte: @math{10^18 = 1,000,000,000,000,000,000}.
3604 @cindex exbibyte, definition of
3605 exbibyte: @math{2^60 = 1,152,921,504,606,846,976}.
3607 @cindex zettabyte, definition of
3608 zettabyte: @math{10^21 = 1,000,000,000,000,000,000,000}
3611 @math{2^70 = 1,180,591,620,717,411,303,424}.
3612 (@samp{Zi} is a GNU extension to IEC 60027-2.)
3614 @cindex yottabyte, definition of
3615 yottabyte: @math{10^24 = 1,000,000,000,000,000,000,000,000}.
3618 @math{2^80 = 1,208,925,819,614,629,174,706,176}.
3619 (@samp{Yi} is a GNU extension to IEC 60027-2.)
3623 @chapter Invoking @command{diff}
3624 @cindex invoking @command{diff}
3625 @cindex @command{diff} invocation
3627 The format for running the @command{diff} command is:
3630 diff @var{options}@dots{} @var{files}@dots{}
3633 In the simplest case, two file names @var{from-file} and
3634 @var{to-file} are given, and @command{diff} compares the contents of
3635 @var{from-file} and @var{to-file}. A file name of @file{-} stands for
3636 text read from the standard input. As a special case, @samp{diff - -}
3637 compares a copy of standard input to itself.
3639 If one file is a directory and the other is not, @command{diff} compares
3640 the file in the directory whose name is that of the non-directory.
3641 The non-directory file must not be @file{-}.
3643 If two file names are given and both are directories,
3644 @command{diff} compares corresponding files in both directories, in
3645 alphabetical order; this comparison is not recursive unless the
3646 @option{-r} or @option{--recursive} option is given. @command{diff} never
3647 compares the actual contents of a directory as if it were a file. The
3648 file that is fully specified may not be standard input, because standard
3649 input is nameless and the notion of ``file with the same name'' does not
3652 If the @option{--from-file=@var{file}} option is given, the number of
3653 file names is arbitrary, and @var{file} is compared to each named file.
3654 Similarly, if the @option{--to-file=@var{file}} option is given, each
3655 named file is compared to @var{file}.
3657 @command{diff} options begin with @samp{-}, so normally file names
3658 may not begin with @samp{-}. However, @option{--} as an
3659 argument by itself treats the remaining arguments as file names even if
3660 they begin with @samp{-}.
3662 An exit status of 0 means no differences were found, 1 means some
3663 differences were found, and 2 means trouble. Normally, differing
3664 binary files count as trouble, but this can be altered by using the
3665 @option{-a} or @option{--text} option, or the @option{-q} or
3666 @option{--brief} option.
3669 * diff Options:: Summary of options to @command{diff}.
3673 @section Options to @command{diff}
3674 @cindex @command{diff} options
3675 @cindex options for @command{diff}
3677 Below is a summary of all of the options that @acronym{GNU}
3678 @command{diff} accepts. Most options have two equivalent names, one
3679 of which is a single letter preceded by @samp{-}, and the other of
3680 which is a long name preceded by @samp{--}. Multiple single letter
3681 options (unless they take an argument) can be combined into a single
3682 command line word: @option{-ac} is equivalent to @option{-a -c}. Long
3683 named options can be abbreviated to any unique prefix of their name.
3684 Brackets ([ and ]) indicate that an option takes an optional argument.
3689 Treat all files as text and compare them line-by-line, even if they
3690 do not seem to be text. @xref{Binary}.
3693 @itemx --ignore-space-change
3694 Ignore changes in amount of white space. @xref{White Space}.
3697 @itemx --ignore-blank-lines
3698 Ignore changes that just insert or delete blank lines. @xref{Blank
3702 Read and write data in binary mode. @xref{Binary}.
3705 Use the context output format, showing three lines of context.
3706 @xref{Context Format}.
3708 @item -C @var{lines}
3709 @itemx --context@r{[}=@var{lines}@r{]}
3710 Use the context output format, showing @var{lines} (an integer) lines of
3711 context, or three if @var{lines} is not given. @xref{Context Format}.
3712 For proper operation, @command{patch} typically needs at least two lines of
3715 On older systems, @command{diff} supports an obsolete option
3716 @option{-@var{lines}} that has effect when combined with @option{-c}
3717 or @option{-p}. @acronym{POSIX} 1003.1-2001 (@pxref{Standards
3718 conformance}) does not allow this; use @option{-C @var{lines}}
3721 @item --changed-group-format=@var{format}
3722 Use @var{format} to output a line group containing differing lines from
3723 both files in if-then-else format. @xref{Line Group Formats}.
3727 Change the algorithm perhaps find a smaller set of changes. This makes
3728 @command{diff} slower (sometimes much slower). @xref{diff Performance}.
3731 @itemx --ifdef=@var{name}
3732 Make merged @samp{#ifdef} format output, conditional on the preprocessor
3733 macro @var{name}. @xref{If-then-else}.
3737 Make output that is a valid @command{ed} script. @xref{ed Scripts}.
3740 @itemx --ignore-tab-expansion
3741 Ignore changes due to tab expansion.
3746 Make output that looks vaguely like an @command{ed} script but has changes
3747 in the order they appear in the file. @xref{Forward ed}.
3749 @item -F @var{regexp}
3750 @itemx --show-function-line=@var{regexp}
3751 In context and unified format, for each hunk of differences, show some
3752 of the last preceding line that matches @var{regexp}. @xref{Specified
3755 @item --from-file=@var{file}
3756 Compare @var{file} to each operand; @var{file} may be a directory.
3759 Output a summary of usage and then exit.
3761 @item --horizon-lines=@var{lines}
3762 Do not discard the last @var{lines} lines of the common prefix
3763 and the first @var{lines} lines of the common suffix.
3764 @xref{diff Performance}.
3767 @itemx --ignore-case
3768 Ignore changes in case; consider upper- and lower-case letters
3769 equivalent. @xref{Case Folding}.
3771 @item -I @var{regexp}
3772 @itemx --ignore-matching-lines=@var{regexp}
3773 Ignore changes that just insert or delete lines that match @var{regexp}.
3774 @xref{Specified Lines}.
3776 @item --ignore-file-name-case
3777 Ignore case when comparing file names during recursive comparison.
3778 @xref{Comparing Directories}.
3782 Pass the output through @command{pr} to paginate it. @xref{Pagination}.
3784 @item --label=@var{label}
3785 Use @var{label} instead of the file name in the context format
3786 (@pxref{Context Format}) and unified format (@pxref{Unified Format})
3787 headers. @xref{RCS}.
3790 Print only the left column of two common lines in side by side format.
3791 @xref{Side by Side Format}.
3793 @item --line-format=@var{format}
3794 Use @var{format} to output all input lines in if-then-else format.
3795 @xref{Line Formats}.
3799 Output @acronym{RCS}-format diffs; like @option{-f} except that each command
3800 specifies the number of lines affected. @xref{RCS}.
3804 In directory comparison, if a file is found in only one directory,
3805 treat it as present but empty in the other directory. @xref{Comparing
3808 @item --new-group-format=@var{format}
3809 Use @var{format} to output a group of lines taken from just the second
3810 file in if-then-else format. @xref{Line Group Formats}.
3812 @item --new-line-format=@var{format}
3813 Use @var{format} to output a line taken from just the second file in
3814 if-then-else format. @xref{Line Formats}.
3816 @item --old-group-format=@var{format}
3817 Use @var{format} to output a group of lines taken from just the first
3818 file in if-then-else format. @xref{Line Group Formats}.
3820 @item --old-line-format=@var{format}
3821 Use @var{format} to output a line taken from just the first file in
3822 if-then-else format. @xref{Line Formats}.
3825 @itemx --show-c-function
3826 Show which C function each change is in. @xref{C Function Headings}.
3830 Report only whether the files differ, not the details of the
3831 differences. @xref{Brief}.
3835 When comparing directories, recursively compare any subdirectories
3836 found. @xref{Comparing Directories}.
3839 @itemx --report-identical-files
3840 Report when two files are the same. @xref{Comparing Directories}.
3843 @itemx --starting-file=@var{file}
3844 When comparing directories, start with the file @var{file}. This is
3845 used for resuming an aborted comparison. @xref{Comparing Directories}.
3847 @item --speed-large-files
3848 Use heuristics to speed handling of large files that have numerous
3849 scattered small changes. @xref{diff Performance}.
3851 @item --strip-trailing-cr
3852 Strip any trailing carriage return at the end of an input line.
3855 @item --suppress-common-lines
3856 Do not print common lines in side by side format.
3857 @xref{Side by Side Format}.
3860 @itemx --expand-tabs
3861 Expand tabs to spaces in the output, to preserve the alignment of tabs
3862 in the input files. @xref{Tabs}.
3865 @itemx --initial-tab
3866 Output a tab rather than a space before the text of a line in normal or
3867 context format. This causes the alignment of tabs in the line to look
3868 normal. @xref{Tabs}.
3870 @item --tabsize=@var{columns}
3871 Assume that tab stops are set every @var{columns} (default 8) print
3872 columns. @xref{Tabs}.
3874 @item --to-file=@var{file}
3875 Compare each operand to @var{file}; @var{file} may be a directory.
3878 Use the unified output format, showing three lines of context.
3879 @xref{Unified Format}.
3881 @item --unchanged-group-format=@var{format}
3882 Use @var{format} to output a group of common lines taken from both files
3883 in if-then-else format. @xref{Line Group Formats}.
3885 @item --unchanged-line-format=@var{format}
3886 Use @var{format} to output a line common to both files in if-then-else
3887 format. @xref{Line Formats}.
3889 @item --unidirectional-new-file
3890 When comparing directories, if a file appears only in the second
3891 directory of the two, treat it as present but empty in the other.
3892 @xref{Comparing Directories}.
3894 @item -U @var{lines}
3895 @itemx --unified@r{[}=@var{lines}@r{]}
3896 Use the unified output format, showing @var{lines} (an integer) lines of
3897 context, or three if @var{lines} is not given. @xref{Unified Format}.
3898 For proper operation, @command{patch} typically needs at least two lines of
3901 On older systems, @command{diff} supports an obsolete option
3902 @option{-@var{lines}} that has effect when combined with @option{-u}.
3903 @acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not allow
3904 this; use @option{-U @var{lines}} instead.
3908 Output version information and then exit.
3911 @itemx --ignore-all-space
3912 Ignore white space when comparing lines. @xref{White Space}.
3914 @item -W @var{columns}
3915 @itemx --width=@var{columns}
3916 Output at most @var{columns} (default 130) print columns per line in
3917 side by side format. @xref{Side by Side Format}.
3919 @item -x @var{pattern}
3920 @itemx --exclude=@var{pattern}
3921 When comparing directories, ignore files and subdirectories whose basenames
3922 match @var{pattern}. @xref{Comparing Directories}.
3925 @itemx --exclude-from=@var{file}
3926 When comparing directories, ignore files and subdirectories whose basenames
3927 match any pattern contained in @var{file}. @xref{Comparing Directories}.
3930 @itemx --side-by-side
3931 Use the side by side output format. @xref{Side by Side Format}.
3934 @node Invoking diff3
3935 @chapter Invoking @command{diff3}
3936 @cindex invoking @command{diff3}
3937 @cindex @command{diff3} invocation
3939 The @command{diff3} command compares three files and outputs descriptions
3940 of their differences. Its arguments are as follows:
3943 diff3 @var{options}@dots{} @var{mine} @var{older} @var{yours}
3946 The files to compare are @var{mine}, @var{older}, and @var{yours}.
3947 At most one of these three file names may be @file{-},
3948 which tells @command{diff3} to read the standard input for that file.
3950 An exit status of 0 means @command{diff3} was successful, 1 means some
3951 conflicts were found, and 2 means trouble.
3954 * diff3 Options:: Summary of options to @command{diff3}.
3958 @section Options to @command{diff3}
3959 @cindex @command{diff3} options
3960 @cindex options for @command{diff3}
3962 Below is a summary of all of the options that @acronym{GNU} @command{diff3}
3963 accepts. Multiple single letter options (unless they take an argument)
3964 can be combined into a single command line argument.
3969 Treat all files as text and compare them line-by-line, even if they
3970 do not appear to be text. @xref{Binary}.
3974 Incorporate all unmerged changes from @var{older} to @var{yours} into
3975 @var{mine}, surrounding conflicts with bracket lines.
3976 @xref{Marking Conflicts}.
3978 @item --diff-program=@var{program}
3979 Use the compatible comparison program @var{program} to compare files
3980 instead of @command{diff}.
3984 Generate an @command{ed} script that incorporates all the changes from
3985 @var{older} to @var{yours} into @var{mine}. @xref{Which Changes}.
3988 @itemx --show-overlap
3989 Like @option{-e}, except bracket lines from overlapping changes' first
3991 @xref{Marking Conflicts}.
3992 With @option{-E}, an overlapping change looks like this:
3996 @r{lines from @var{mine}}
3998 @r{lines from @var{yours}}
4003 Output a summary of usage and then exit.
4006 Generate @samp{w} and @samp{q} commands at the end of the @command{ed}
4007 script for System V compatibility. This option must be combined with
4008 one of the @option{-AeExX3} options, and may not be combined with @option{-m}.
4009 @xref{Saving the Changed File}.
4011 @item --label=@var{label}
4012 Use the label @var{label} for the brackets output by the @option{-A},
4013 @option{-E} and @option{-X} options. This option may be given up to three
4014 times, one for each input file. The default labels are the names of
4015 the input files. Thus @samp{diff3 --label X --label Y --label Z -m A
4017 @samp{diff3 -m A B C}, except that the output looks like it came from
4018 files named @samp{X}, @samp{Y} and @samp{Z} rather than from files
4019 named @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}.
4023 Apply the edit script to the first file and send the result to standard
4024 output. Unlike piping the output from @command{diff3} to @command{ed}, this
4025 works even for binary files and incomplete lines. @option{-A} is assumed
4026 if no edit script option is specified. @xref{Bypassing ed}.
4028 @item --strip-trailing-cr
4029 Strip any trailing carriage return at the end of an input line.
4033 @itemx --initial-tab
4034 Output a tab rather than two spaces before the text of a line in normal format.
4035 This causes the alignment of tabs in the line to look normal. @xref{Tabs}.
4039 Output version information and then exit.
4042 @itemx --overlap-only
4043 Like @option{-e}, except output only the overlapping changes.
4044 @xref{Which Changes}.
4047 Like @option{-E}, except output only the overlapping changes.
4048 In other words, like @option{-x}, except bracket changes as in @option{-E}.
4049 @xref{Marking Conflicts}.
4053 Like @option{-e}, except output only the nonoverlapping changes.
4054 @xref{Which Changes}.
4057 @node Invoking patch
4058 @chapter Invoking @command{patch}
4059 @cindex invoking @command{patch}
4060 @cindex @command{patch} invocation
4062 Normally @command{patch} is invoked like this:
4065 patch <@var{patchfile}
4068 The full format for invoking @command{patch} is:
4071 patch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]}
4074 You can also specify where to read the patch from with the @option{-i
4075 @var{patchfile}} or @option{--input=@var{patchfile}} option.
4076 If you do not specify @var{patchfile}, or if @var{patchfile} is
4077 @file{-}, @command{patch} reads the patch (that is, the @command{diff} output)
4078 from the standard input.
4080 If you do not specify an input file on the command line, @command{patch}
4081 tries to intuit from the @dfn{leading text} (any text in the patch
4082 that comes before the @command{diff} output) which file to edit.
4083 @xref{Multiple Patches}.
4085 By default, @command{patch} replaces the original input file with the
4086 patched version, possibly after renaming the original file into a
4087 backup file (@pxref{Backup Names}, for a description of how
4088 @command{patch} names backup files). You can also specify where to
4089 put the output with the @option{-o @var{file}} or
4090 @option{--output=@var{file}} option; however, do not use this option
4091 if @var{file} is one of the input files.
4094 * patch Options:: Summary table of options to @command{patch}.
4098 @section Options to @command{patch}
4099 @cindex @command{patch} options
4100 @cindex options for @command{patch}
4102 Here is a summary of all of the options that @acronym{GNU} @command{patch}
4103 accepts. @xref{patch and Tradition}, for which of these options are
4104 safe to use in older versions of @command{patch}.
4106 Multiple single-letter options that do not take an argument can be
4107 combined into a single command line argument with only one dash.
4112 Back up the original contents of each file, even if backups would
4113 normally not be made. @xref{Backups}.
4115 @item -B @var{prefix}
4116 @itemx --prefix=@var{prefix}
4117 Prepend @var{prefix} to backup file names. @xref{Backup Names}.
4119 @item --backup-if-mismatch
4120 Back up the original contents of each file if the patch does not
4121 exactly match the file. This is the default behavior when not
4122 conforming to @acronym{POSIX}. @xref{Backups}.
4125 Read and write all files in binary mode, except for standard output
4126 and @file{/dev/tty}. This option has no effect on
4127 @acronym{POSIX}-conforming systems like @acronym{GNU}/Linux. On systems where
4128 this option makes a difference, the patch should be generated by
4129 @samp{diff -a --binary}. @xref{Binary}.
4133 Interpret the patch file as a context diff. @xref{patch Input}.
4135 @item -d @var{directory}
4136 @itemx --directory=@var{directory}
4137 Make directory @var{directory} the current directory for interpreting
4138 both file names in the patch file, and file names given as arguments to
4139 other options. @xref{patch Directories}.
4142 @itemx --ifdef=@var{name}
4143 Make merged if-then-else output using @var{name}. @xref{If-then-else}.
4146 Print the results of applying the patches without actually changing
4147 any files. @xref{Dry Runs}.
4151 Interpret the patch file as an @command{ed} script. @xref{patch Input}.
4154 @itemx --remove-empty-files
4155 Remove output files that are empty after the patches have been applied.
4156 @xref{Creating and Removing}.
4160 Assume that the user knows exactly what he or she is doing, and do not
4161 ask any questions. @xref{patch Messages}.
4163 @item -F @var{lines}
4164 @itemx --fuzz=@var{lines}
4165 Set the maximum fuzz factor to @var{lines}. @xref{Inexact}.
4168 @itemx --get=@var{num}
4169 If @var{num} is positive, get input files from a revision control
4170 system as necessary; if zero, do not get the files; if negative, ask
4171 the user whether to get the files. @xref{Revision Control}.
4174 Output a summary of usage and then exit.
4176 @item -i @var{patchfile}
4177 @itemx --input=@var{patchfile}
4178 Read the patch from @var{patchfile} rather than from standard input.
4179 @xref{patch Options}.
4182 @itemx --ignore-white-space
4183 Let any sequence of blanks (spaces or tabs) in the patch file match
4184 any sequence of blanks in the input file. @xref{Changed White Space}.
4188 Interpret the patch file as a normal diff. @xref{patch Input}.
4192 Ignore patches that @command{patch} thinks are reversed or already applied.
4193 See also @option{-R}. @xref{Reversed Patches}.
4195 @item --no-backup-if-mismatch
4196 Do not back up the original contents of files. This is the default
4197 behavior when conforming to @acronym{POSIX}. @xref{Backups}.
4200 @itemx --output=@var{file}
4201 Use @var{file} as the output file name. @xref{patch Options}.
4203 @item -p@var{number}
4204 @itemx --strip=@var{number}
4205 Set the file name strip count to @var{number}. @xref{patch Directories}.
4208 Conform to @acronym{POSIX}, as if the @env{POSIXLY_CORRECT} environment
4209 variable had been set. @xref{patch and POSIX}.
4211 @item --quoting-style=@var{word}
4212 Use style @var{word} to quote names in diagnostics, as if the
4213 @env{QUOTING_STYLE} environment variable had been set to @var{word}.
4214 @xref{patch Quoting Style}.
4216 @item -r @var{reject-file}
4217 @itemx --reject-file=@var{reject-file}
4218 Use @var{reject-file} as the reject file name. @xref{Reject Names}.
4222 Assume that this patch was created with the old and new files swapped.
4223 @xref{Reversed Patches}.
4228 Work silently unless an error occurs. @xref{patch Messages}.
4232 Do not ask any questions. @xref{patch Messages}.
4236 Set the modification and access times of patched files from time
4237 stamps given in context diff headers, assuming that the context diff
4238 headers use local time. @xref{Patching Time Stamps}.
4242 Interpret the patch file as a unified diff. @xref{patch Input}.
4246 Output version information and then exit.
4248 @item -V @var{backup-style}
4249 @itemx --version=control=@var{backup-style}
4250 Select the naming convention for backup file names. @xref{Backup Names}.
4253 Print more diagnostics than usual. @xref{patch Messages}.
4255 @item -x @var{number}
4256 @itemx --debug=@var{number}
4257 Set internal debugging flags. Of interest only to @command{patch}
4260 @item -Y @var{prefix}
4261 @itemx --basename-prefix=@var{prefix}
4262 Prepend @var{prefix} to base names of backup files. @xref{Backup Names}.
4264 @item -z @var{suffix}
4265 @itemx --suffix=@var{suffix}
4266 Use @var{suffix} as the backup extension instead of @samp{.orig} or
4267 @samp{~}. @xref{Backup Names}.
4271 Set the modification and access times of patched files from time
4272 stamps given in context diff headers, assuming that the context diff
4273 headers use @acronym{UTC}. @xref{Patching Time Stamps}.
4277 @node Invoking sdiff
4278 @chapter Invoking @command{sdiff}
4279 @cindex invoking @command{sdiff}
4280 @cindex @command{sdiff} invocation
4282 The @command{sdiff} command merges two files and interactively outputs the
4283 results. Its arguments are as follows:
4286 sdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file}
4289 This merges @var{from-file} with @var{to-file}, with output to @var{outfile}.
4290 If @var{from-file} is a directory and @var{to-file} is not, @command{sdiff}
4291 compares the file in @var{from-file} whose file name is that of @var{to-file},
4292 and vice versa. @var{from-file} and @var{to-file} may not both be
4295 @command{sdiff} options begin with @samp{-}, so normally @var{from-file}
4296 and @var{to-file} may not begin with @samp{-}. However, @option{--} as an
4297 argument by itself treats the remaining arguments as file names even if
4298 they begin with @samp{-}. You may not use @file{-} as an input file.
4300 @command{sdiff} without @option{-o} (or @option{--output}) produces a
4301 side-by-side difference. This usage is obsolete; use the @option{-y}
4302 or @option{--side-by-side} option of @command{diff} instead.
4304 An exit status of 0 means no differences were found, 1 means some
4305 differences were found, and 2 means trouble.
4308 * sdiff Options:: Summary of options to @command{diff}.
4312 @section Options to @command{sdiff}
4313 @cindex @command{sdiff} options
4314 @cindex options for @command{sdiff}
4316 Below is a summary of all of the options that @acronym{GNU}
4317 @command{sdiff} accepts. Each option has two equivalent names, one of
4318 which is a single letter preceded by @samp{-}, and the other of which
4319 is a long name preceded by @samp{--}. Multiple single letter options
4320 (unless they take an argument) can be combined into a single command
4321 line argument. Long named options can be abbreviated to any unique
4322 prefix of their name.
4327 Treat all files as text and compare them line-by-line, even if they
4328 do not appear to be text. @xref{Binary}.
4331 @itemx --ignore-space-change
4332 Ignore changes in amount of white space. @xref{White Space}.
4335 @itemx --ignore-blank-lines
4336 Ignore changes that just insert or delete blank lines. @xref{Blank
4341 Change the algorithm to perhaps find a smaller set of changes. This
4342 makes @command{sdiff} slower (sometimes much slower). @xref{diff
4345 @item --diff-program=@var{program}
4346 Use the compatible comparison program @var{program} to compare files
4347 instead of @command{diff}.
4350 @itemx --ignore-tab-expansion
4351 Ignore changes due to tab expansion.
4355 Output a summary of usage and then exit.
4358 @itemx --ignore-case
4359 Ignore changes in case; consider upper- and lower-case to be the same.
4360 @xref{Case Folding}.
4362 @item -I @var{regexp}
4363 @itemx --ignore-matching-lines=@var{regexp}
4364 Ignore changes that just insert or delete lines that match @var{regexp}.
4365 @xref{Specified Lines}.
4368 @itemx --left-column
4369 Print only the left column of two common lines.
4370 @xref{Side by Side Format}.
4373 @itemx --output=@var{file}
4374 Put merged output into @var{file}. This option is required for merging.
4377 @itemx --suppress-common-lines
4378 Do not print common lines. @xref{Side by Side Format}.
4380 @item --speed-large-files
4381 Use heuristics to speed handling of large files that have numerous
4382 scattered small changes. @xref{diff Performance}.
4384 @item --strip-trailing-cr
4385 Strip any trailing carriage return at the end of an input line.
4389 @itemx --expand-tabs
4390 Expand tabs to spaces in the output, to preserve the alignment of tabs
4391 in the input files. @xref{Tabs}.
4393 @item --tabsize=@var{columns}
4394 Assume that tab stops are set every @var{columns} (default 8) print
4395 columns. @xref{Tabs}.
4399 Output version information and then exit.
4401 @item -w @var{columns}
4402 @itemx --width=@var{columns}
4403 Output at most @var{columns} (default 130) print columns per line.
4404 @xref{Side by Side Format}. Note that for historical reasons, this
4405 option is @option{-W} in @command{diff}, @option{-w} in @command{sdiff}.
4408 @itemx --ignore-all-space
4409 Ignore white space when comparing lines. @xref{White Space}.
4410 Note that for historical reasons, this option is @option{-w} in @command{diff},
4411 @option{-W} in @command{sdiff}.
4414 @node Standards conformance
4415 @chapter Standards conformance
4416 @cindex @acronym{POSIX}
4418 @vindex POSIXLY_CORRECT
4419 In a few cases, the @acronym{GNU} utilities' default behavior is
4420 incompatible with the @acronym{POSIX} standard. To suppress these
4421 incompatibilities, define the @env{POSIXLY_CORRECT} environment
4422 variable. Unless you are checking for @acronym{POSIX} conformance, you
4423 probably do not need to define @env{POSIXLY_CORRECT}.
4425 Normally options and operands can appear in any order, and programs act
4426 as if all the options appear before any operands. For example,
4427 @samp{diff lao tzu -C 2} acts like @samp{diff -C 2 lao tzu}, since
4428 @samp{2} is an option-argument of @option{-C}. However, if the
4429 @env{POSIXLY_CORRECT} environment variable is set, options must appear
4430 before operands, unless otherwise specified for a particular command.
4432 Newer versions of @acronym{POSIX} are occasionally incompatible with older
4433 versions. For example, older versions of @acronym{POSIX} allowed the
4434 command @samp{diff -c -10} to have the same meaning as @samp{diff -C
4435 10}, but @acronym{POSIX} 1003.1-2001 @samp{diff} no longer allows
4436 digit-string options like @option{-10}.
4438 @vindex _POSIX2_VERSION
4439 The @acronym{GNU} utilities normally conform to the version of @acronym{POSIX}
4440 that is standard for your system. To cause them to conform to a
4441 different version of @acronym{POSIX}, define the @env{_POSIX2_VERSION}
4442 environment variable to a value of the form @var{yyyymm} specifying
4443 the year and month the standard was adopted. Two values are currently
4444 supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
4445 @acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX}
4446 1003.1-2001. For example, if you are running older software that
4447 assumes an older version of @acronym{POSIX} and uses @samp{diff -c -10},
4448 you can work around the compatibility problems by setting
4449 @samp{_POSIX2_VERSION=199209} in your environment.
4452 @chapter Future Projects
4454 Here are some ideas for improving @acronym{GNU} @command{diff} and
4455 @command{patch}. The @acronym{GNU} project has identified some
4456 improvements as potential programming projects for volunteers. You
4457 can also help by reporting any bugs that you find.
4459 If you are a programmer and would like to contribute something to the
4460 @acronym{GNU} project, please consider volunteering for one of these
4461 projects. If you are seriously contemplating work, please write to
4462 @email{gvc@@gnu.org} to coordinate with other volunteers.
4465 * Shortcomings:: Suggested projects for improvements.
4466 * Bugs:: Reporting bugs.
4470 @section Suggested Projects for Improving @acronym{GNU} @command{diff} and @command{patch}
4471 @cindex projects for directories
4473 One should be able to use @acronym{GNU} @command{diff} to generate a
4474 patch from any pair of directory trees, and given the patch and a copy
4475 of one such tree, use @command{patch} to generate a faithful copy of
4476 the other. Unfortunately, some changes to directory trees cannot be
4477 expressed using current patch formats; also, @command{patch} does not
4478 handle some of the existing formats. These shortcomings motivate the
4479 following suggested projects.
4482 * Internationalization:: Handling multibyte and varying-width characters.
4483 * Changing Structure:: Handling changes to the directory structure.
4484 * Special Files:: Handling symbolic links, device special files, etc.
4485 * Unusual File Names:: Handling file names that contain unusual characters.
4486 * Time Stamp Order:: Outputting diffs in time stamp order.
4487 * Ignoring Changes:: Ignoring certain changes while showing others.
4488 * Speedups:: Improving performance.
4491 @node Internationalization
4492 @subsection Handling Multibyte and Varying-Width Characters
4493 @cindex multibyte characters
4494 @cindex varying-width characters
4496 @command{diff}, @command{diff3} and @command{sdiff} treat each line of
4497 input as a string of unibyte characters. This can mishandle multibyte
4498 characters in some cases. For example, when asked to ignore spaces,
4499 @command{diff} does not properly ignore a multibyte space character.
4501 Also, @command{diff} currently assumes that each byte is one column
4502 wide, and this assumption is incorrect in some locales, e.g., locales
4503 that use UTF-8 encoding. This causes problems with the @option{-y} or
4504 @option{--side-by-side} option of @command{diff}.
4506 These problems need to be fixed without unduly affecting the
4507 performance of the utilities in unibyte environments.
4509 The IBM GNU/Linux Technology Center Internationalization Team has
4511 @uref{http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz,patches
4512 to support internationalized @command{diff}}.
4513 Unfortunately, these patches are incomplete and are to an older
4514 version of @command{diff}, so more work needs to be done in this area.
4516 @node Changing Structure
4517 @subsection Handling Changes to the Directory Structure
4518 @cindex directory structure changes
4520 @command{diff} and @command{patch} do not handle some changes to directory
4521 structure. For example, suppose one directory tree contains a directory
4522 named @samp{D} with some subsidiary files, and another contains a file
4523 with the same name @samp{D}. @samp{diff -r} does not output enough
4524 information for @command{patch} to transform the directory subtree into
4527 There should be a way to specify that a file has been removed without
4528 having to include its entire contents in the patch file. There should
4529 also be a way to tell @command{patch} that a file was renamed, even if
4530 there is no way for @command{diff} to generate such information.
4531 There should be a way to tell @command{patch} that a file's time stamp
4532 has changed, even if its contents have not changed.
4534 These problems can be fixed by extending the @command{diff} output format
4535 to represent changes in directory structure, and extending @command{patch}
4536 to understand these extensions.
4539 @subsection Files that are Neither Directories Nor Regular Files
4540 @cindex special files
4542 Some files are neither directories nor regular files: they are unusual
4543 files like symbolic links, device special files, named pipes, and
4544 sockets. Currently, @command{diff} treats symbolic links as if they
4545 were the pointed-to files, except that a recursive @command{diff}
4546 reports an error if it detects infinite loops of symbolic links (e.g.,
4547 symbolic links to @file{..}). @command{diff} treats other special
4548 files like regular files if they are specified at the top level, but
4549 simply reports their presence when comparing directories. This means
4550 that @command{patch} cannot represent changes to such files. For
4551 example, if you change which file a symbolic link points to,
4552 @command{diff} outputs the difference between the two files, instead
4553 of the change to the symbolic link.
4555 @c This might not be a good idea; is it wise for root to install devices
4557 @command{diff} should optionally report changes to special files specially,
4558 and @command{patch} should be extended to understand these extensions.
4560 @node Unusual File Names
4561 @subsection File Names that Contain Unusual Characters
4562 @cindex file names with unusual characters
4564 When a file name contains an unusual character like a newline or
4565 white space, @samp{diff -r} generates a patch that @command{patch} cannot
4566 parse. The problem is with format of @command{diff} output, not just with
4567 @command{patch}, because with odd enough file names one can cause
4568 @command{diff} to generate a patch that is syntactically correct but
4569 patches the wrong files. The format of @command{diff} output should be
4570 extended to handle all possible file names.
4572 @node Time Stamp Order
4573 @subsection Outputting Diffs in Time Stamp Order
4575 Applying @command{patch} to a multiple-file diff can result in files
4576 whose time stamps are out of order. @acronym{GNU} @command{patch} has
4577 options to restore the time stamps of the updated files
4578 (@pxref{Patching Time Stamps}), but sometimes it is useful to generate
4579 a patch that works even if the recipient does not have @acronym{GNU} patch,
4580 or does not use these options. One way to do this would be to
4581 implement a @command{diff} option to output diffs in time stamp order.
4583 @node Ignoring Changes
4584 @subsection Ignoring Certain Changes
4586 It would be nice to have a feature for specifying two strings, one in
4587 @var{from-file} and one in @var{to-file}, which should be considered to
4588 match. Thus, if the two strings are @samp{foo} and @samp{bar}, then if
4589 two lines differ only in that @samp{foo} in file 1 corresponds to
4590 @samp{bar} in file 2, the lines are treated as identical.
4592 It is not clear how general this feature can or should be, or
4593 what syntax should be used for it.
4595 A partial substitute is to filter one or both files before comparing,
4599 sed 's/foo/bar/g' file1 | diff - file2
4602 However, this outputs the filtered text, not the original.
4605 @subsection Improving Performance
4607 When comparing two large directory structures, one of which was
4608 originally copied from the other with time stamps preserved (e.g.,
4609 with @samp{cp -pR}), it would greatly improve performance if an option
4610 told @command{diff} to assume that two files with the same size and
4611 time stamps have the same content. @xref{diff Performance}.
4614 @section Reporting Bugs
4616 @cindex reporting bugs
4618 If you think you have found a bug in @acronym{GNU} @command{cmp},
4619 @command{diff}, @command{diff3}, or @command{sdiff}, please report it
4620 by electronic mail to the
4621 @uref{http://mail.gnu.org/mailman/listinfo/bug-gnu-utils,GNU utilities
4622 bug report mailing list} @email{bug-gnu-utils@@gnu.org}. Please send
4623 bug reports for @acronym{GNU} @command{patch} to
4624 @email{bug-patch@@gnu.org}. Send as precise a description of the
4625 problem as you can, including the output of the @option{--version}
4626 option and sample input files that produce the bug, if applicable. If
4627 you have a nontrivial fix for the bug, please send it as well. If you
4628 have a patch, please send it too. It may simplify the maintainer's
4629 job if the patch is relative to a recent test release, which you can
4630 find in the directory @uref{ftp://alpha.gnu.org/gnu/diffutils/}.
4632 @node Copying This Manual
4633 @appendix Copying This Manual
4636 * GNU Free Documentation License:: License for copying this manual.
4642 @appendix Translations of This Manual
4644 Nishio Futoshi of the GNUjdoc project has prepared a Japanese
4645 translation of this manual. Its most recent version can be found at
4646 @uref{http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/}.