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.
2468 Edit a copy of the left version, then copy the result to the output.
2471 Edit a copy of the right version, then copy the result to the output.
2474 Copy the left version to the output.
2480 Copy the right version to the output.
2483 Silently copy common lines.
2486 Verbosely copy common lines. This is the default.
2490 The text editor invoked is specified by the @env{EDITOR} environment
2491 variable if it is set. The default is system-dependent.
2493 @node Merging with patch
2494 @chapter Merging with @command{patch}
2496 @command{patch} takes comparison output produced by @command{diff} and applies
2497 the differences to a copy of the original file, producing a patched
2498 version. With @command{patch}, you can distribute just the changes to a
2499 set of files instead of distributing the entire file set; your
2500 correspondents can apply @command{patch} to update their copy of the files
2501 with your changes. @command{patch} automatically determines the diff
2502 format, skips any leading or trailing headers, and uses the headers to
2503 determine which file to patch. This lets your correspondents feed a
2504 mail message containing a difference listing directly to
2507 @command{patch} detects and warns about common problems like forward
2508 patches. It saves any patches that it could not apply. It can also maintain a
2509 @code{patchlevel.h} file to ensure that your correspondents apply
2510 diffs in the proper order.
2512 @command{patch} accepts a series of diffs in its standard input, usually
2513 separated by headers that specify which file to patch. It applies
2514 @command{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not
2515 exactly match the original file, @command{patch} uses heuristics to try to
2516 patch the file as well as it can. If no approximate match can be found,
2517 @command{patch} rejects the hunk and skips to the next hunk. @command{patch}
2518 normally replaces each file @var{f} with its new version, putting reject
2519 hunks (if any) into @samp{@var{f}.rej}.
2521 @xref{Invoking patch}, for detailed information on the options to
2525 * patch Input:: Selecting the type of @command{patch} input.
2526 * Revision Control:: Getting files from @acronym{RCS}, @acronym{SCCS}, etc.
2527 * Imperfect:: Dealing with imperfect patches.
2528 * Creating and Removing:: Creating and removing files with a patch.
2529 * Patching Time Stamps:: Updating time stamps on patched files.
2530 * Multiple Patches:: Handling multiple patches in a file.
2531 * patch Directories:: Changing directory and stripping directories.
2532 * Backups:: Whether backup files are made.
2533 * Backup Names:: Backup file names.
2534 * Reject Names:: Reject file names.
2535 * patch Messages:: Messages and questions @command{patch} can produce.
2536 * patch and POSIX:: Conformance to the @acronym{POSIX} standard.
2537 * patch and Tradition:: @acronym{GNU} versus traditional @command{patch}.
2541 @section Selecting the @command{patch} Input Format
2542 @cindex @command{patch} input format
2544 @command{patch} normally determines which @command{diff} format the patch
2545 file uses by examining its contents. For patch files that contain
2546 particularly confusing leading text, you might need to use one of the
2547 following options to force @command{patch} to interpret the patch file as a
2548 certain format of diff. The output formats listed here are the only
2549 ones that @command{patch} can understand.
2558 @command{ed} script.
2569 @node Revision Control
2570 @section Revision Control
2571 @cindex revision control
2572 @cindex version control
2573 @cindex @acronym{RCS}
2575 @cindex @acronym{SCCS}
2577 If a nonexistent input file is under a revision control system
2578 supported by @command{patch}, @command{patch} normally asks the user
2579 whether to get (or check out) the file from the revision control
2580 system. Patch currently supports @acronym{RCS}, ClearCase and
2581 @acronym{SCCS}. Under @acronym{RCS} and @acronym{SCCS},
2582 @command{patch} also asks when the input file is read-only and matches
2583 the default version in the revision control system.
2586 The @option{-g @var{num}} or @option{--get=@var{num}} option affects access
2587 to files under supported revision control systems. If @var{num} is
2588 positive, @command{patch} gets the file without asking the user; if
2589 zero, @command{patch} neither asks the user nor gets the file; and if
2590 negative, @command{patch} asks the user before getting the file. The
2591 default value of @var{num} is given by the value of the
2592 @env{PATCH_GET} environment variable if it is set; if not, the default
2593 value is zero if @command{patch} is conforming to @acronym{POSIX}, negative
2594 otherwise. @xref{patch and POSIX}.
2596 @vindex VERSION_CONTROL
2597 The choice of revision control system is unaffected by the
2598 @env{VERSION_CONTROL} environment variable (@pxref{Backup Names}).
2601 @section Applying Imperfect Patches
2602 @cindex imperfect patch application
2604 @command{patch} tries to skip any leading text in the patch file,
2605 apply the diff, and then skip any trailing text. Thus you can feed a
2606 mail message directly to @command{patch}, and it should work. If the
2607 entire diff is indented by a constant amount of white space,
2608 @command{patch} automatically ignores the indentation. If a context
2609 diff contains trailing carriage return on each line, @command{patch}
2610 automatically ignores the carriage return. If a context diff has been
2611 encapsulated by prepending @w{@samp{- }} to lines beginning with @samp{-}
2612 as per @uref{ftp://ftp.isi.edu/in-notes/rfc934.txt, Internet RFC 934},
2613 @command{patch} automatically unencapsulates the input.
2615 However, certain other types of imperfect input require user
2616 intervention or testing.
2619 * Changed White Space:: When tabs and spaces don't match exactly.
2620 * Reversed Patches:: Applying reversed patches correctly.
2621 * Inexact:: Helping @command{patch} find close matches.
2622 * Dry Runs:: Predicting what @command{patch} will do.
2625 @node Changed White Space
2626 @subsection Applying Patches with Changed White Space
2627 @cindex white space in patches
2629 Sometimes mailers, editors, or other programs change spaces into tabs,
2630 or vice versa. If this happens to a patch file or an input file, the
2631 files might look the same, but @command{patch} will not be able to match
2632 them properly. If this problem occurs, use the @option{-l} or
2633 @option{--ignore-white-space} option, which makes @command{patch} compare
2634 blank characters (i.e.@: spaces and tabs) loosely so that any nonempty
2635 sequence of blanks in the patch file matches any nonempty sequence of
2636 blanks in the input files. Non-blank
2637 characters must still match exactly. Each line of the context must
2638 still match a line in the input file.
2640 @node Reversed Patches
2641 @subsection Applying Reversed Patches
2642 @cindex reversed patches
2644 Sometimes people run @command{diff} with the new file first instead of
2645 second. This creates a diff that is ``reversed''. To apply such
2646 patches, give @command{patch} the @option{-R} or @option{--reverse} option.
2647 @command{patch} then attempts to swap each hunk around before applying it.
2648 Rejects come out in the swapped format.
2650 Often @command{patch} can guess that the patch is reversed. If the first
2651 hunk of a patch fails, @command{patch} reverses the hunk to see if it can
2652 apply it that way. If it can, @command{patch} asks you if you want to have
2653 the @option{-R} option set; if it can't, @command{patch} continues to apply
2654 the patch normally. This method cannot detect a reversed patch if it is
2655 a normal diff and the first command is an append (which should have been
2656 a delete) since appends always succeed, because a null context matches
2657 anywhere. But most patches add or change lines rather than delete them,
2658 so most reversed normal diffs begin with a delete, which fails, and
2659 @command{patch} notices.
2661 If you apply a patch that you have already applied, @command{patch} thinks
2662 it is a reversed patch and offers to un-apply the patch. This could be
2663 construed as a feature. If you did this inadvertently and you don't
2664 want to un-apply the patch, just answer @samp{n} to this offer and to
2665 the subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the
2666 @command{patch} process.
2669 @subsection Helping @command{patch} Find Inexact Matches
2670 @cindex inexact patches
2671 @cindex fuzz factor when patching
2673 For context diffs, and to a lesser extent normal diffs, @command{patch} can
2674 detect when the line numbers mentioned in the patch are incorrect, and
2675 it attempts to find the correct place to apply each hunk of the patch.
2676 As a first guess, it takes the line number mentioned in the hunk, plus
2677 or minus any offset used in applying the previous hunk. If that is not
2678 the correct place, @command{patch} scans both forward and backward for a
2679 set of lines matching the context given in the hunk.
2681 First @command{patch} looks for a place where all lines of the context
2682 match. If it cannot find such a place, and it is reading a context or
2683 unified diff, and the maximum fuzz factor is set to 1 or more, then
2684 @command{patch} makes another scan, ignoring the first and last line of
2685 context. If that fails, and the maximum fuzz factor is set to 2 or
2686 more, it makes another scan, ignoring the first two and last two lines
2687 of context are ignored. It continues similarly if the maximum fuzz
2690 The @option{-F @var{lines}} or @option{--fuzz=@var{lines}} option sets the
2691 maximum fuzz factor to @var{lines}. This option only applies to context
2692 and unified diffs; it ignores up to @var{lines} lines while looking for
2693 the place to install a hunk. Note that a larger fuzz factor increases
2694 the odds of making a faulty patch. The default fuzz factor is 2; there
2695 is no point to setting it to more than the number of lines of context
2696 in the diff, ordinarily 3.
2698 If @command{patch} cannot find a place to install a hunk of the patch, it
2699 writes the hunk out to a reject file (@pxref{Reject Names}, for information
2700 on how reject files are named). It writes out rejected hunks in context
2701 format no matter what form the input patch is in. If the input is a
2702 normal or @command{ed} diff, many of the contexts are simply null. The
2703 line numbers on the hunks in the reject file may be different from those
2704 in the patch file: they show the approximate location where @command{patch}
2705 thinks the failed hunks belong in the new file rather than in the old
2708 If the @option{--verbose} option is given, then
2709 as it completes each hunk @command{patch} tells you whether the hunk
2710 succeeded or failed, and if it failed, on which line (in the new file)
2711 @command{patch} thinks the hunk should go. If this is different from the
2712 line number specified in the diff, it tells you the offset. A single
2713 large offset @emph{may} indicate that @command{patch} installed a hunk in
2714 the wrong place. @command{patch} also tells you if it used a fuzz factor
2715 to make the match, in which case you should also be slightly suspicious.
2717 @command{patch} cannot tell if the line numbers are off in an @command{ed}
2718 script, and can only detect wrong line numbers in a normal diff when it
2719 finds a change or delete command. It may have the same problem with a
2720 context diff using a fuzz factor equal to or greater than the number of
2721 lines of context shown in the diff (typically 3). In these cases, you
2722 should probably look at a context diff between your original and patched
2723 input files to see if the changes make sense. Compiling without errors
2724 is a pretty good indication that the patch worked, but not a guarantee.
2726 A patch against an empty file applies to a nonexistent file, and vice
2727 versa. @xref{Creating and Removing}.
2729 @command{patch} usually produces the correct results, even when it must
2730 make many guesses. However, the results are guaranteed only when
2731 the patch is applied to an exact copy of the file that the patch was
2735 @subsection Predicting what @command{patch} will do
2736 @cindex testing @command{patch}
2737 @cindex dry runs for @command{patch}
2739 It may not be obvious in advance what @command{patch} will do with a
2740 complicated or poorly formatted patch. If you are concerned that the
2741 input might cause @command{patch} to modify the wrong files, you can
2742 use the @option{--dry-run} option, which causes @command{patch} to
2743 print the results of applying patches without actually changing any
2744 files. You can then inspect the diagnostics generated by the dry run
2745 to see whether @command{patch} will modify the files that you expect.
2746 If the patch does not do what you want, you can modify the patch (or
2747 the other options to @command{patch}) and try another dry run. Once
2748 you are satisfied with the proposed patch you can apply it by invoking
2749 @command{patch} as before, but this time without the
2750 @option{--dry-run} option.
2752 @node Creating and Removing
2753 @section Creating and Removing Files
2754 @cindex creating files
2755 @cindex empty files, removing
2756 @cindex removing empty files
2758 Sometimes when comparing two directories, a file may exist in one
2759 directory but not the other. If you give @command{diff} the
2760 @option{-N} or @option{--new-file} option, or if you supply an old or
2761 new file that is named @file{/dev/null} or is empty and is dated the
2762 Epoch (1970-01-01 00:00:00 UTC), @command{diff} outputs a patch that
2763 adds or deletes the contents of this file. When given such a patch,
2764 @command{patch} normally creates a new file or removes the old file.
2765 However, when conforming to @acronym{POSIX} (@pxref{patch and POSIX}),
2766 @command{patch} does not remove the old file, but leaves it empty.
2767 The @option{-E} or @option{--remove-empty-files} option causes
2768 @command{patch} to remove output files that are empty after applying a
2769 patch, even if the patch does not appear to be one that removed the
2772 If the patch appears to create a file that already exists,
2773 @command{patch} asks for confirmation before applying the patch.
2775 @node Patching Time Stamps
2776 @section Updating Time Stamps on Patched Files
2777 @cindex time stamps on patched files
2779 When @command{patch} updates a file, it normally sets the file's
2780 last-modified time stamp to the current time of day. If you are using
2781 @command{patch} to track a software distribution, this can cause
2782 @command{make} to incorrectly conclude that a patched file is out of
2783 date. For example, if @file{syntax.c} depends on @file{syntax.y}, and
2784 @command{patch} updates @file{syntax.c} and then @file{syntax.y}, then
2785 @file{syntax.c} will normally appear to be out of date with respect to
2786 @file{syntax.y} even though its contents are actually up to date.
2788 The @option{-Z} or @option{--set-utc} option causes @command{patch} to
2789 set a patched file's modification and access times to the time stamps
2790 given in context diff headers. If the context diff headers do not
2791 specify a time zone, they are assumed to use Coordinated Universal
2792 Time (@acronym{UTC}, often known as @acronym{GMT}).
2794 The @option{-T} or @option{--set-time} option acts like @option{-Z} or
2795 @option{--set-utc}, except that it assumes that the context diff
2796 headers' time stamps use local time instead of @acronym{UTC}. This option
2797 is not recommended, because patches using local time cannot easily be
2798 used by people in other time zones, and because local time stamps are
2799 ambiguous when local clocks move backwards during daylight-saving time
2800 adjustments. If the context diff headers specify a time zone, this
2801 option is equivalent to @option{-Z} or @option{--set-utc}.
2803 @command{patch} normally refrains from setting a file's time stamps if
2804 the file's original last-modified time stamp does not match the time
2805 given in the diff header, of if the file's contents do not exactly
2806 match the patch. However, if the @option{-f} or @option{--force}
2807 option is given, the file's time stamps are set regardless.
2809 Due to the limitations of the current @command{diff} format,
2810 @command{patch} cannot update the times of files whose contents have
2811 not changed. Also, if you set file time stamps to values other than
2812 the current time of day, you should also remove (e.g., with @samp{make
2813 clean}) all files that depend on the patched files, so that later
2814 invocations of @command{make} do not get confused by the patched
2817 @node Multiple Patches
2818 @section Multiple Patches in a File
2819 @cindex multiple patches
2820 @cindex intuiting file names from patches
2822 If the patch file contains more than one patch, and if you do not
2823 specify an input file on the command line, @command{patch} tries to
2824 apply each patch as if they came from separate patch files. This
2825 means that it determines the name of the file to patch for each patch,
2826 and that it examines the leading text before each patch for file names
2827 and prerequisite revision level (@pxref{Making Patches}, for more on
2830 @command{patch} uses the following rules to intuit a file name from
2831 the leading text before a patch. First, @command{patch} takes an
2832 ordered list of candidate file names as follows:
2836 If the header is that of a context diff, @command{patch} takes the old
2837 and new file names in the header. A name is ignored if it does not
2838 have enough slashes to satisfy the @option{-p@var{num}} or
2839 @option{--strip=@var{num}} option. The name @file{/dev/null} is also
2843 If there is an @samp{Index:} line in the leading garbage and if either
2844 the old and new names are both absent or if @command{patch} is
2845 conforming to @acronym{POSIX}, @command{patch} takes the name in the
2849 For the purpose of the following rules, the candidate file names are
2850 considered to be in the order (old, new, index), regardless of the
2851 order that they appear in the header.
2855 Then @command{patch} selects a file name from the candidate list as
2860 If some of the named files exist, @command{patch} selects the first
2861 name if conforming to @acronym{POSIX}, and the best name otherwise.
2864 If @command{patch} is not ignoring @acronym{RCS}, ClearCase, and @acronym{SCCS}
2865 (@pxref{Revision Control}), and no named files exist but an @acronym{RCS},
2866 ClearCase, or @acronym{SCCS} master is found, @command{patch} selects the
2867 first named file with an @acronym{RCS}, ClearCase, or @acronym{SCCS} master.
2870 If no named files exist, no @acronym{RCS}, ClearCase, or @acronym{SCCS} master
2871 was found, some names are given, @command{patch} is not conforming to
2872 @acronym{POSIX}, and the patch appears to create a file, @command{patch}
2873 selects the best name requiring the creation of the fewest
2877 If no file name results from the above heuristics, you are asked for
2878 the name of the file to patch, and @command{patch} selects that name.
2881 To determine the @dfn{best} of a nonempty list of file names,
2882 @command{patch} first takes all the names with the fewest path name
2883 components; of those, it then takes all the names with the shortest
2884 basename; of those, it then takes all the shortest names; finally, it
2885 takes the first remaining name.
2887 @xref{patch and POSIX}, to see whether @command{patch} is conforming
2890 @node patch Directories
2891 @section Applying Patches in Other Directories
2892 @cindex directories and patch
2893 @cindex patching directories
2895 The @option{-d @var{directory}} or @option{--directory=@var{directory}}
2896 option to @command{patch} makes directory @var{directory} the current
2897 directory for interpreting both file names in the patch file, and file
2898 names given as arguments to other options (such as @option{-B} and
2899 @option{-o}). For example, while in a mail reading program, you can patch
2900 a file in the @file{/usr/src/emacs} directory directly from a message
2901 containing the patch like this:
2904 | patch -d /usr/src/emacs
2907 Sometimes the file names given in a patch contain leading directories,
2908 but you keep your files in a directory different from the one given in
2909 the patch. In those cases, you can use the
2910 @option{-p@var{number}} or @option{--strip=@var{number}}
2911 option to set the file name strip count to @var{number}. The strip
2912 count tells @command{patch} how many slashes, along with the directory
2913 names between them, to strip from the front of file names. A sequence
2914 of one or more adjacent slashes is counted as a single slash. By
2915 default, @command{patch} strips off all leading directories, leaving
2916 just the base file names.
2918 For example, suppose the file name in the patch file is
2919 @file{/gnu/src/emacs/etc/NEWS}. Using @option{-p0} gives the
2920 entire file name unmodified, @option{-p1} gives
2921 @file{gnu/src/emacs/etc/NEWS} (no leading slash), @option{-p4} gives
2922 @file{etc/NEWS}, and not specifying @option{-p} at all gives @file{NEWS}.
2924 @command{patch} looks for each file (after any slashes have been stripped)
2925 in the current directory, or if you used the @option{-d @var{directory}}
2926 option, in that directory.
2929 @section Backup Files
2930 @cindex backup file strategy
2932 Normally, @command{patch} creates a backup file if the patch does not
2933 exactly match the original input file, because in that case the
2934 original data might not be recovered if you undo the patch with
2935 @samp{patch -R} (@pxref{Reversed Patches}). However, when conforming
2936 to @acronym{POSIX}, @command{patch} does not create backup files by
2937 default. @xref{patch and POSIX}.
2939 The @option{-b} or @option{--backup} option causes @command{patch} to
2940 make a backup file regardless of whether the patch matches the
2941 original input. The @option{--backup-if-mismatch} option causes
2942 @command{patch} to create backup files for mismatches files; this is
2943 the default when not conforming to @acronym{POSIX}. The
2944 @option{--no-backup-if-mismatch} option causes @command{patch} to not
2945 create backup files, even for mismatched patches; this is the default
2946 when conforming to @acronym{POSIX}.
2948 When backing up a file that does not exist, an empty, unreadable
2949 backup file is created as a placeholder to represent the nonexistent
2953 @section Backup File Names
2954 @cindex backup file names
2956 Normally, @command{patch} renames an original input file into a backup
2957 file by appending to its name the extension @samp{.orig}, or @samp{~}
2958 if using @samp{.orig} would make the backup file name too
2959 long.@footnote{A coding error in @acronym{GNU} @command{patch} version
2960 2.5.4 causes it to always use @samp{~}, but this should be fixed in
2961 the next release.} The @option{-z @var{backup-suffix}} or
2962 @option{--suffix=@var{backup-suffix}} option causes @command{patch} to
2963 use @var{backup-suffix} as the backup extension instead.
2965 @vindex SIMPLE_BACKUP_SUFFIX
2966 Alternately, you can specify the extension for backup files with the
2967 @env{SIMPLE_BACKUP_SUFFIX} environment variable, which the options
2970 @command{patch} can also create numbered backup files the way
2971 @acronym{GNU} Emacs does. With this method, instead of having a
2972 single backup of each file, @command{patch} makes a new backup file
2973 name each time it patches a file. For example, the backups of a file
2974 named @file{sink} would be called, successively, @file{sink.~1~},
2975 @file{sink.~2~}, @file{sink.~3~}, etc.
2977 @vindex PATCH_VERSION_CONTROL
2978 @vindex VERSION_CONTROL
2979 The @option{-V @var{backup-style}} or
2980 @option{--version-control=@var{backup-style}} option takes as an
2981 argument a method for creating backup file names. You can alternately
2982 control the type of backups that @command{patch} makes with the
2983 @env{PATCH_VERSION_CONTROL} environment variable, which the
2984 @option{-V} option overrides. If @env{PATCH_VERSION_CONTROL} is not
2985 set, the @env{VERSION_CONTROL} environment variable is used instead.
2986 Please note that these options and variables control backup file
2987 names; they do not affect the choice of revision control system
2988 (@pxref{Revision Control}).
2990 The values of these environment variables and the argument to the
2991 @option{-V} option are like the @acronym{GNU} Emacs @code{version-control}
2992 variable (@pxref{Backup Names, , , emacs, The @acronym{GNU} Emacs Manual},
2993 for more information on backup versions in Emacs). They also
2994 recognize synonyms that are more descriptive. The valid values are
2995 listed below; unique abbreviations are acceptable.
3000 Always make numbered backups.
3004 Make numbered backups of files that already have them, simple backups of
3005 the others. This is the default.
3009 Always make simple backups.
3012 You can also tell @command{patch} to prepend a prefix, such as a
3013 directory name, to produce backup file names. The @option{-B
3014 @var{prefix}} or @option{--prefix=@var{prefix}} option makes backup
3015 files by prepending @var{prefix} to them. The @option{-Y
3016 @var{prefix}} or @option{--basename-prefix=@var{prefix}} prepends
3017 @var{prefix} to the last file name component of backup file names
3018 instead; for example, @option{-Y ~} causes the backup name for
3019 @file{dir/file.c} to be @file{dir/~file.c}. If you use either of
3020 these prefix options, the suffix-based options are ignored.
3022 If you specify the output file with the @option{-o} option, that file is
3023 the one that is backed up, not the input file.
3025 Options that affect the names of backup files do not affect whether
3026 backups are made. For example, if you specify the
3027 @option{--no-backup-if-mismatch} option, none of the options described
3028 in this section have any affect, because no backups are made.
3031 @section Reject File Names
3032 @cindex reject file names
3034 The names for reject files (files containing patches that
3035 @command{patch} could not find a place to apply) are normally the name
3036 of the output file with @samp{.rej} appended (or @samp{#} if using
3037 @samp{.rej} would make the backup file name too long).
3039 Alternatively, you can tell @command{patch} to place all of the rejected
3040 patches in a single file. The @option{-r @var{reject-file}} or
3041 @option{--reject-file=@var{reject-file}} option uses @var{reject-file} as
3042 the reject file name.
3044 @node patch Messages
3045 @section Messages and Questions from @command{patch}
3046 @cindex @command{patch} messages and questions
3047 @cindex diagnostics from @command{patch}
3048 @cindex messages from @command{patch}
3050 @command{patch} can produce a variety of messages, especially if it
3051 has trouble decoding its input. In a few situations where it's not
3052 sure how to proceed, @command{patch} normally prompts you for more
3053 information from the keyboard. There are options to produce more or
3054 fewer messages, to have it not ask for keyboard input, and to
3055 affect the way that file names are quoted in messages.
3058 * More or Fewer Messages:: Controlling the verbosity of @command{patch}.
3059 * patch and Keyboard Input:: Inhibiting keyboard input.
3060 * patch Quoting Style:: Quoting file names in diagnostics.
3063 @command{patch} exits with status 0 if all hunks are applied successfully,
3064 1 if some hunks cannot be applied, and 2 if there is more serious trouble.
3065 When applying a set of patches in a loop, you should check the
3066 exit status, so you don't apply a later patch to a partially patched
3069 @node More or Fewer Messages
3070 @subsection Controlling the Verbosity of @command{patch}
3071 @cindex verbose messages from @command{patch}
3072 @cindex inhibit messages from @command{patch}
3074 You can cause @command{patch} to produce more messages by using the
3075 @option{--verbose} option. For example, when you give this option,
3076 the message @samp{Hmm...} indicates that @command{patch} is reading text in
3077 the patch file, attempting to determine whether there is a patch in that
3078 text, and if so, what kind of patch it is.
3080 You can inhibit all terminal output from @command{patch}, unless an error
3081 occurs, by using the @option{-s}, @option{--quiet}, or @option{--silent}
3084 @node patch and Keyboard Input
3085 @subsection Inhibiting Keyboard Input
3086 @cindex keyboard input to @command{patch}
3088 There are two ways you can prevent @command{patch} from asking you any
3089 questions. The @option{-f} or @option{--force} option assumes that you know
3090 what you are doing. It causes @command{patch} to do the following:
3094 Skip patches that do not contain file names in their headers.
3097 Patch files even though they have the wrong version for the
3098 @samp{Prereq:} line in the patch;
3101 Assume that patches are not reversed even if they look like they are.
3105 The @option{-t} or @option{--batch} option is similar to @option{-f}, in that
3106 it suppresses questions, but it makes somewhat different assumptions:
3110 Skip patches that do not contain file names in their headers
3111 (the same as @option{-f}).
3114 Skip patches for which the file has the wrong version for the
3115 @samp{Prereq:} line in the patch;
3118 Assume that patches are reversed if they look like they are.
3121 @node patch Quoting Style
3122 @subsection @command{patch} Quoting Style
3123 @cindex quoting style
3125 When @command{patch} outputs a file name in a diagnostic message, it
3126 can format the name in any of several ways. This can be useful to
3127 output file names unambiguously, even if they contain punctuation or
3128 special characters like newlines. The
3129 @option{--quoting-style=@var{word}} option controls how names are
3130 output. The @var{word} should be one of the following:
3136 Quote names for the shell if they contain shell metacharacters or would
3137 cause ambiguous output.
3139 Quote names for the shell, even if they would normally not require quoting.
3141 Quote names as for a C language string.
3143 Quote as with @samp{c} except omit the surrounding double-quote
3145 @c The following are not yet implemented in patch 2.5.4.
3147 @c Quote as with @samp{c} except use quotation marks appropriate for the
3150 @c @c Use @t instead of @samp to avoid duplicate quoting in some output styles.
3151 @c Like @samp{clocale}, but quote @t{`like this'} instead of @t{"like
3152 @c this"} in the default C locale. This looks nicer on many displays.
3155 @vindex QUOTING_STYLE
3156 You can specify the default value of the @option{--quoting-style}
3157 option with the environment variable @env{QUOTING_STYLE}. If that
3158 environment variable is not set, the default value is @samp{shell},
3159 but this default may change in a future version of @command{patch}.
3161 @node patch and POSIX
3162 @section @command{patch} and the @acronym{POSIX} Standard
3163 @cindex @acronym{POSIX}
3165 @vindex POSIXLY_CORRECT
3166 If you specify the @option{--posix} option, or set the
3167 @env{POSIXLY_CORRECT} environment variable, @command{patch} conforms
3168 more strictly to the @acronym{POSIX} standard, as follows:
3172 Take the first existing file from the list (old, new, index)
3173 when intuiting file names from diff headers. @xref{Multiple Patches}.
3176 Do not remove files that are removed by a diff.
3177 @xref{Creating and Removing}.
3180 Do not ask whether to get files from @acronym{RCS}, ClearCase, or
3181 @acronym{SCCS}. @xref{Revision Control}.
3184 Require that all options precede the files in the command line.
3187 Do not backup files, even when there is a mismatch. @xref{Backups}.
3191 @node patch and Tradition
3192 @section @acronym{GNU} @command{patch} and Traditional @command{patch}
3193 @cindex traditional @command{patch}
3195 The current version of @acronym{GNU} @command{patch} normally follows the
3196 @acronym{POSIX} standard. @xref{patch and POSIX}, for the few exceptions
3197 to this general rule.
3199 Unfortunately, @acronym{POSIX} redefined the behavior of @command{patch} in
3200 several important ways. You should be aware of the following
3201 differences if you must interoperate with traditional @command{patch},
3202 or with @acronym{GNU} @command{patch} version 2.1 and earlier.
3206 In traditional @command{patch}, the @option{-p} option's operand was
3207 optional, and a bare @option{-p} was equivalent to @option{-p0}. The
3208 @option{-p} option now requires an operand, and @option{-p@ 0} is now
3209 equivalent to @option{-p0}. For maximum compatibility, use options
3210 like @option{-p0} and @option{-p1}.
3212 Also, traditional @command{patch} simply counted slashes when
3213 stripping path prefixes; @command{patch} now counts pathname
3214 components. That is, a sequence of one or more adjacent slashes now
3215 counts as a single slash. For maximum portability, avoid sending
3216 patches containing @file{//} in file names.
3219 In traditional @command{patch}, backups were enabled by default. This
3220 behavior is now enabled with the @option{-b} or @option{--backup}
3223 Conversely, in @acronym{POSIX} @command{patch}, backups are never made,
3224 even when there is a mismatch. In @acronym{GNU} @command{patch}, this
3225 behavior is enabled with the @option{--no-backup-if-mismatch} option,
3226 or by conforming to @acronym{POSIX}.
3228 The @option{-b@ @var{suffix}} option of traditional @command{patch} is
3229 equivalent to the @samp{-b -z@ @var{suffix}} options of @acronym{GNU}
3233 Traditional @command{patch} used a complicated (and incompletely
3234 documented) method to intuit the name of the file to be patched from
3235 the patch header. This method did not conform to @acronym{POSIX}, and had
3236 a few gotchas. Now @command{patch} uses a different, equally
3237 complicated (but better documented) method that is optionally
3238 @acronym{POSIX}-conforming; we hope it has fewer gotchas. The two methods
3239 are compatible if the file names in the context diff header and the
3240 @samp{Index:} line are all identical after prefix-stripping. Your
3241 patch is normally compatible if each header's file names all contain
3242 the same number of slashes.
3245 When traditional @command{patch} asked the user a question, it sent
3246 the question to standard error and looked for an answer from the first
3247 file in the following list that was a terminal: standard error,
3248 standard output, @file{/dev/tty}, and standard input. Now
3249 @command{patch} sends questions to standard output and gets answers
3250 from @file{/dev/tty}. Defaults for some answers have been changed so
3251 that @command{patch} never goes into an infinite loop when using
3255 Traditional @command{patch} exited with a status value that counted
3256 the number of bad hunks, or with status 1 if there was real trouble.
3257 Now @command{patch} exits with status 1 if some hunks failed, or with
3258 2 if there was real trouble.
3261 Limit yourself to the following options when sending instructions
3262 meant to be executed by anyone running @acronym{GNU} @command{patch},
3263 traditional @command{patch}, or a @command{patch} that conforms to
3264 @acronym{POSIX}. Spaces are significant in the following list, and
3265 operands are required.
3269 @option{-d @var{dir}}
3270 @option{-D @var{define}}
3275 @option{-o @var{outfile}}
3276 @option{-p@var{num}}
3278 @option{-r @var{rejectfile}}
3283 @node Making Patches
3284 @chapter Tips for Making and Using Patches
3286 Use some common sense when making and using patches. For example,
3287 when sending bug fixes to a program's maintainer, send several small
3288 patches, one per independent subject, instead of one large,
3289 harder-to-digest patch that covers all the subjects.
3291 Here are some other things you should keep in mind if you are going to
3292 distribute patches for updating a software package.
3295 * Tips for Patch Producers:: Advice for making patches.
3296 * Tips for Patch Consumers:: Advice for using patches.
3297 * Avoiding Common Mistakes:: Avoiding common mistakes when using @command{patch}.
3298 * Generating Smaller Patches:: How to generate smaller patches.
3301 @node Tips for Patch Producers
3302 @section Tips for Patch Producers
3303 @cindex patch producer tips
3305 To create a patch that changes an older version of a package into a
3306 newer version, first make a copy of the older and newer versions in
3307 adjacent subdirectories. It is common to do that by unpacking
3308 @command{tar} archives of the two versions.
3310 To generate the patch, use the command @samp{diff -Naur @var{old}
3311 @var{new}} where @var{old} and @var{new} identify the old and new
3312 directories. The names @var{old} and @var{new} should not contain any
3313 slashes. The @option{-N} option lets the patch create and remove
3314 files; @option{-a} lets the patch update non-text files; @option{-u}
3315 generates useful time stamps and enough context; and @option{-r} lets
3316 the patch update subdirectories. Here is an example command, using
3317 Bourne shell syntax:
3320 diff -Naur gcc-3.0.3 gcc-3.0.4
3323 Tell your recipients how to apply the patches. This should include
3324 which working directory to use, and which @command{patch} options to
3325 use; the option @samp{-p1} is recommended. Test your procedure by
3326 pretending to be a recipient and applying your patches to a copy of
3329 @xref{Avoiding Common Mistakes}, for how to avoid common mistakes when
3332 @node Tips for Patch Consumers
3333 @section Tips for Patch Consumers
3334 @cindex patch consumer tips
3336 A patch producer should tell recipients how to apply the patches, so
3337 the first rule of thumb for a patch consumer is to follow the
3338 instructions supplied with the patch.
3340 @acronym{GNU} @command{diff} can analyze files with arbitrarily long lines
3341 and files that end in incomplete lines. However, older versions of
3342 @command{patch} cannot patch such files. If you are having trouble
3343 applying such patches, try upgrading to a recent version of @acronym{GNU}
3346 @node Avoiding Common Mistakes
3347 @section Avoiding Common Mistakes
3348 @cindex common mistakes with patches
3349 @cindex patch, common mistakes
3351 When producing a patch for multiple files, apply @command{diff} to
3352 directories whose names do not have slashes. This reduces confusion
3353 when the patch consumer specifies the @option{-p@var{number}} option,
3354 since this option can have surprising results when the old and new
3355 file names have different numbers of slashes. For example, do not
3356 send a patch with a header that looks like this:
3359 diff -Naur v2.0.29/prog/README prog/README
3360 --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
3361 +++ prog/README 2002-03-17 20:49:32.442260588 -0800
3365 because the two file names have different numbers of slashes, and
3366 different versions of @command{patch} interpret the file names
3367 differently. To avoid confusion, send output that looks like this
3371 diff -Naur v2.0.29/prog/README v2.0.30/prog/README
3372 --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
3373 +++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800
3376 Make sure you have specified the file names correctly, either in a
3377 context diff header or with an @samp{Index:} line. Take care to not send out
3378 reversed patches, since these make people wonder whether they have
3379 already applied the patch.
3381 Avoid sending patches that compare backup file names like
3382 @file{README.orig} or @file{README~}, since this might confuse
3383 @command{patch} into patching a backup file instead of the real file.
3384 Instead, send patches that compare the same base file names in
3385 different directories, e.g.@: @file{old/README} and @file{new/README}.
3387 To save people from partially applying a patch before other patches that
3388 should have gone before it, you can make the first patch in the patch
3389 file update a file with a name like @file{patchlevel.h} or
3390 @file{version.c}, which contains a patch level or version number. If
3391 the input file contains the wrong version number, @command{patch} will
3392 complain immediately.
3394 An even clearer way to prevent this problem is to put a @samp{Prereq:}
3395 line before the patch. If the leading text in the patch file contains a
3396 line that starts with @samp{Prereq:}, @command{patch} takes the next word
3397 from that line (normally a version number) and checks whether the next
3398 input file contains that word, preceded and followed by either
3399 white space or a newline. If not, @command{patch} prompts you for
3400 confirmation before proceeding. This makes it difficult to accidentally
3401 apply patches in the wrong order.
3403 @node Generating Smaller Patches
3404 @section Generating Smaller Patches
3405 @cindex patches, shrinking
3407 The simplest way to generate a patch is to use @samp{diff -Naur}
3408 (@pxref{Tips for Patch Producers}), but you might be able to reduce
3409 the size of the patch by renaming or removing some files before making
3410 the patch. If the older version of the package contains any files
3411 that the newer version does not, or if any files have been renamed
3412 between the two versions, make a list of @command{rm} and @command{mv}
3413 commands for the user to execute in the old version directory before
3414 applying the patch. Then run those commands yourself in the scratch
3417 If there are any files that you don't need to include in the patch
3418 because they can easily be rebuilt from other files (for example,
3419 @file{TAGS} and output from @command{yacc} and @command{makeinfo}),
3420 exclude them from the patch by giving @command{diff} the @option{-x
3421 @var{pattern}} option (@pxref{Comparing Directories}). If you want
3422 your patch to modify a derived file because your recipients lack tools
3423 to build it, make sure that the patch for the derived file follows any
3424 patches for files that it depends on, so that the recipients' time
3425 stamps will not confuse @command{make}.
3427 Now you can create the patch using @samp{diff -Naur}. Make sure to
3428 specify the scratch directory first and the newer directory second.
3430 Add to the top of the patch a note telling the user any @command{rm} and
3431 @command{mv} commands to run before applying the patch. Then you can
3432 remove the scratch directory.
3434 You can also shrink the patch size by using fewer lines of context,
3435 but bear in mind that @command{patch} typically needs at least two
3436 lines for proper operation when patches do not exactly match the input
3440 @chapter Invoking @command{cmp}
3441 @cindex invoking @command{cmp}
3442 @cindex @command{cmp} invocation
3444 The @command{cmp} command compares two files, and if they differ,
3445 tells the first byte and line number where they differ or reports
3446 that one file is a prefix of the other. Bytes and
3447 lines are numbered starting with 1. The arguments of @command{cmp}
3451 cmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file} @r{[}@var{from-skip} @r{[}@var{to-skip}@r{]}@r{]}@r{]}
3454 The file name @file{-} is always the standard input. @command{cmp}
3455 also uses the standard input if one file name is omitted. The
3456 @var{from-skip} and @var{to-skip} operands specify how many bytes to
3457 ignore at the start of each file; they are equivalent to the
3458 @option{--ignore-initial=@var{from-skip}:@var{to-skip}} option.
3460 By default, @command{cmp} outputs nothing if the two files have the
3461 same contents. If one file is a prefix of the other, @command{cmp}
3462 prints to standard error a message of the following form:
3465 cmp: EOF on @var{shorter-file}
3468 Otherwise, @command{cmp} prints to standard output a message of the
3472 @var{from-file} @var{to-file} differ: char @var{byte-number}, line @var{line-number}
3475 The message formats can differ outside the @acronym{POSIX} locale.
3476 Also, @acronym{POSIX} allows the @acronym{EOF} message to be followed
3477 by a blank and some additional information.
3479 An exit status of 0 means no differences were found, 1 means some
3480 differences were found, and 2 means trouble.
3483 * cmp Options:: Summary of options to @command{cmp}.
3487 @section Options to @command{cmp}
3488 @cindex @command{cmp} options
3489 @cindex options for @command{cmp}
3491 Below is a summary of all of the options that @acronym{GNU}
3492 @command{cmp} accepts. Most options have two equivalent names, one of
3493 which is a single letter preceded by @samp{-}, and the other of which
3494 is a long name preceded by @samp{--}. Multiple single letter options
3495 (unless they take an argument) can be combined into a single command
3496 line word: @option{-bl} is equivalent to @option{-b -l}.
3500 @itemx --print-bytes
3501 Print the differing bytes. Display control bytes as a
3502 @samp{^} followed by a letter of the alphabet and precede bytes
3503 that have the high bit set with @samp{M-} (which stands for ``meta'').
3506 Output a summary of usage and then exit.
3509 @itemx --ignore-initial=@var{skip}
3510 Ignore any differences in the first @var{skip} bytes of the input
3511 files. Treat files with fewer than @var{skip} bytes as if they are
3512 empty. If @var{skip} is of the form
3513 @option{@var{from-skip}:@var{to-skip}}, skip the first @var{from-skip}
3514 bytes of the first input file and the first @var{to-skip} bytes of the
3519 Output the (decimal) byte numbers and (octal) values of all differing bytes,
3520 instead of the default standard output.
3522 @item -n @var{count}
3523 @itemx --bytes=@var{count}
3524 Compare at most @var{count} input bytes.
3529 Do not print anything; only return an exit status indicating whether
3534 Output version information and then exit.
3537 In the above table, operands that are byte counts are normally
3538 decimal, but may be preceded by @samp{0} for octal and @samp{0x} for
3541 A byte count can be followed by a suffix to specify a multiple of that
3542 count; in this case an omitted integer is understood to be 1. A bare
3543 size letter, or one followed by @samp{iB}, specifies a multiple using
3544 powers of 1024. A size letter followed by @samp{B} specifies powers
3545 of 1000 instead. For example, @option{-n 4M} and @option{-n 4MiB} are
3546 equivalent to @option{-n 4194304}, whereas @option{-n 4MB} is
3547 equivalent to @option{-n 4000000}. This notation is upward compatible
3548 with the @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI
3549 prefixes} for decimal multiples and with the
3550 @uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2
3551 prefixes for binary multiples}.
3553 The following suffixes are defined. Large sizes like @code{1Y} may be
3554 rejected by your computer due to limitations of its arithmetic.
3558 @cindex kilobyte, definition of
3559 kilobyte: @math{10^3 = 1000}.
3563 @cindex kibibyte, definition of
3564 kibibyte: @math{2^10 = 1024}. @samp{K} is special: the SI prefix is
3565 @samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and
3566 @acronym{POSIX} use @samp{k} to mean @samp{KiB}.
3568 @cindex megabyte, definition of
3569 megabyte: @math{10^6 = 1,000,000}.
3572 @cindex mebibyte, definition of
3573 mebibyte: @math{2^20 = 1,048,576}.
3575 @cindex gigabyte, definition of
3576 gigabyte: @math{10^9 = 1,000,000,000}.
3579 @cindex gibibyte, definition of
3580 gibibyte: @math{2^30 = 1,073,741,824}.
3582 @cindex terabyte, definition of
3583 terabyte: @math{10^12 = 1,000,000,000,000}.
3586 @cindex tebibyte, definition of
3587 tebibyte: @math{2^40 = 1,099,511,627,776}.
3589 @cindex petabyte, definition of
3590 petabyte: @math{10^15 = 1,000,000,000,000,000}.
3593 @cindex pebibyte, definition of
3594 pebibyte: @math{2^50 = 1,125,899,906,842,624}.
3596 @cindex exabyte, definition of
3597 exabyte: @math{10^18 = 1,000,000,000,000,000,000}.
3600 @cindex exbibyte, definition of
3601 exbibyte: @math{2^60 = 1,152,921,504,606,846,976}.
3603 @cindex zettabyte, definition of
3604 zettabyte: @math{10^21 = 1,000,000,000,000,000,000,000}
3607 @math{2^70 = 1,180,591,620,717,411,303,424}.
3608 (@samp{Zi} is a GNU extension to IEC 60027-2.)
3610 @cindex yottabyte, definition of
3611 yottabyte: @math{10^24 = 1,000,000,000,000,000,000,000,000}.
3614 @math{2^80 = 1,208,925,819,614,629,174,706,176}.
3615 (@samp{Yi} is a GNU extension to IEC 60027-2.)
3619 @chapter Invoking @command{diff}
3620 @cindex invoking @command{diff}
3621 @cindex @command{diff} invocation
3623 The format for running the @command{diff} command is:
3626 diff @var{options}@dots{} @var{files}@dots{}
3629 In the simplest case, two file names @var{from-file} and
3630 @var{to-file} are given, and @command{diff} compares the contents of
3631 @var{from-file} and @var{to-file}. A file name of @file{-} stands for
3632 text read from the standard input. As a special case, @samp{diff - -}
3633 compares a copy of standard input to itself.
3635 If one file is a directory and the other is not, @command{diff} compares
3636 the file in the directory whose name is that of the non-directory.
3637 The non-directory file must not be @file{-}.
3639 If two file names are given and both are directories,
3640 @command{diff} compares corresponding files in both directories, in
3641 alphabetical order; this comparison is not recursive unless the
3642 @option{-r} or @option{--recursive} option is given. @command{diff} never
3643 compares the actual contents of a directory as if it were a file. The
3644 file that is fully specified may not be standard input, because standard
3645 input is nameless and the notion of ``file with the same name'' does not
3648 If the @option{--from-file=@var{file}} option is given, the number of
3649 file names is arbitrary, and @var{file} is compared to each named file.
3650 Similarly, if the @option{--to-file=@var{file}} option is given, each
3651 named file is compared to @var{file}.
3653 @command{diff} options begin with @samp{-}, so normally file names
3654 may not begin with @samp{-}. However, @option{--} as an
3655 argument by itself treats the remaining arguments as file names even if
3656 they begin with @samp{-}.
3658 An exit status of 0 means no differences were found, 1 means some
3659 differences were found, and 2 means trouble. Normally, differing
3660 binary files count as trouble, but this can be altered by using the
3661 @option{-a} or @option{--text} option, or the @option{-q} or
3662 @option{--brief} option.
3665 * diff Options:: Summary of options to @command{diff}.
3669 @section Options to @command{diff}
3670 @cindex @command{diff} options
3671 @cindex options for @command{diff}
3673 Below is a summary of all of the options that @acronym{GNU}
3674 @command{diff} accepts. Most options have two equivalent names, one
3675 of which is a single letter preceded by @samp{-}, and the other of
3676 which is a long name preceded by @samp{--}. Multiple single letter
3677 options (unless they take an argument) can be combined into a single
3678 command line word: @option{-ac} is equivalent to @option{-a -c}. Long
3679 named options can be abbreviated to any unique prefix of their name.
3680 Brackets ([ and ]) indicate that an option takes an optional argument.
3685 Treat all files as text and compare them line-by-line, even if they
3686 do not seem to be text. @xref{Binary}.
3689 @itemx --ignore-space-change
3690 Ignore changes in amount of white space. @xref{White Space}.
3693 @itemx --ignore-blank-lines
3694 Ignore changes that just insert or delete blank lines. @xref{Blank
3698 Read and write data in binary mode. @xref{Binary}.
3701 Use the context output format, showing three lines of context.
3702 @xref{Context Format}.
3704 @item -C @var{lines}
3705 @itemx --context@r{[}=@var{lines}@r{]}
3706 Use the context output format, showing @var{lines} (an integer) lines of
3707 context, or three if @var{lines} is not given. @xref{Context Format}.
3708 For proper operation, @command{patch} typically needs at least two lines of
3711 On older systems, @command{diff} supports an obsolete option
3712 @option{-@var{lines}} that has effect when combined with @option{-c}
3713 or @option{-p}. @acronym{POSIX} 1003.1-2001 (@pxref{Standards
3714 conformance}) does not allow this; use @option{-C @var{lines}}
3717 @item --changed-group-format=@var{format}
3718 Use @var{format} to output a line group containing differing lines from
3719 both files in if-then-else format. @xref{Line Group Formats}.
3723 Change the algorithm perhaps find a smaller set of changes. This makes
3724 @command{diff} slower (sometimes much slower). @xref{diff Performance}.
3727 @itemx --ifdef=@var{name}
3728 Make merged @samp{#ifdef} format output, conditional on the preprocessor
3729 macro @var{name}. @xref{If-then-else}.
3733 Make output that is a valid @command{ed} script. @xref{ed Scripts}.
3736 @itemx --ignore-tab-expansion
3737 Ignore changes due to tab expansion.
3742 Make output that looks vaguely like an @command{ed} script but has changes
3743 in the order they appear in the file. @xref{Forward ed}.
3745 @item -F @var{regexp}
3746 @itemx --show-function-line=@var{regexp}
3747 In context and unified format, for each hunk of differences, show some
3748 of the last preceding line that matches @var{regexp}. @xref{Specified
3751 @item --from-file=@var{file}
3752 Compare @var{file} to each operand; @var{file} may be a directory.
3755 Output a summary of usage and then exit.
3757 @item --horizon-lines=@var{lines}
3758 Do not discard the last @var{lines} lines of the common prefix
3759 and the first @var{lines} lines of the common suffix.
3760 @xref{diff Performance}.
3763 @itemx --ignore-case
3764 Ignore changes in case; consider upper- and lower-case letters
3765 equivalent. @xref{Case Folding}.
3767 @item -I @var{regexp}
3768 @itemx --ignore-matching-lines=@var{regexp}
3769 Ignore changes that just insert or delete lines that match @var{regexp}.
3770 @xref{Specified Lines}.
3772 @item --ignore-file-name-case
3773 Ignore case when comparing file names during recursive comparison.
3774 @xref{Comparing Directories}.
3778 Pass the output through @command{pr} to paginate it. @xref{Pagination}.
3780 @item --label=@var{label}
3781 Use @var{label} instead of the file name in the context format
3782 (@pxref{Context Format}) and unified format (@pxref{Unified Format})
3783 headers. @xref{RCS}.
3786 Print only the left column of two common lines in side by side format.
3787 @xref{Side by Side Format}.
3789 @item --line-format=@var{format}
3790 Use @var{format} to output all input lines in if-then-else format.
3791 @xref{Line Formats}.
3795 Output @acronym{RCS}-format diffs; like @option{-f} except that each command
3796 specifies the number of lines affected. @xref{RCS}.
3800 In directory comparison, if a file is found in only one directory,
3801 treat it as present but empty in the other directory. @xref{Comparing
3804 @item --new-group-format=@var{format}
3805 Use @var{format} to output a group of lines taken from just the second
3806 file in if-then-else format. @xref{Line Group Formats}.
3808 @item --new-line-format=@var{format}
3809 Use @var{format} to output a line taken from just the second file in
3810 if-then-else format. @xref{Line Formats}.
3812 @item --old-group-format=@var{format}
3813 Use @var{format} to output a group of lines taken from just the first
3814 file in if-then-else format. @xref{Line Group Formats}.
3816 @item --old-line-format=@var{format}
3817 Use @var{format} to output a line taken from just the first file in
3818 if-then-else format. @xref{Line Formats}.
3821 @itemx --show-c-function
3822 Show which C function each change is in. @xref{C Function Headings}.
3826 Report only whether the files differ, not the details of the
3827 differences. @xref{Brief}.
3831 When comparing directories, recursively compare any subdirectories
3832 found. @xref{Comparing Directories}.
3835 @itemx --report-identical-files
3836 Report when two files are the same. @xref{Comparing Directories}.
3839 @itemx --starting-file=@var{file}
3840 When comparing directories, start with the file @var{file}. This is
3841 used for resuming an aborted comparison. @xref{Comparing Directories}.
3843 @item --speed-large-files
3844 Use heuristics to speed handling of large files that have numerous
3845 scattered small changes. @xref{diff Performance}.
3847 @item --strip-trailing-cr
3848 Strip any trailing carriage return at the end of an input line.
3851 @item --suppress-common-lines
3852 Do not print common lines in side by side format.
3853 @xref{Side by Side Format}.
3856 @itemx --expand-tabs
3857 Expand tabs to spaces in the output, to preserve the alignment of tabs
3858 in the input files. @xref{Tabs}.
3861 @itemx --initial-tab
3862 Output a tab rather than a space before the text of a line in normal or
3863 context format. This causes the alignment of tabs in the line to look
3864 normal. @xref{Tabs}.
3866 @item --tabsize=@var{columns}
3867 Assume that tab stops are set every @var{columns} (default 8) print
3868 columns. @xref{Tabs}.
3870 @item --to-file=@var{file}
3871 Compare each operand to @var{file}; @var{file} may be a directory.
3874 Use the unified output format, showing three lines of context.
3875 @xref{Unified Format}.
3877 @item --unchanged-group-format=@var{format}
3878 Use @var{format} to output a group of common lines taken from both files
3879 in if-then-else format. @xref{Line Group Formats}.
3881 @item --unchanged-line-format=@var{format}
3882 Use @var{format} to output a line common to both files in if-then-else
3883 format. @xref{Line Formats}.
3885 @item --unidirectional-new-file
3886 When comparing directories, if a file appears only in the second
3887 directory of the two, treat it as present but empty in the other.
3888 @xref{Comparing Directories}.
3890 @item -U @var{lines}
3891 @itemx --unified@r{[}=@var{lines}@r{]}
3892 Use the unified output format, showing @var{lines} (an integer) lines of
3893 context, or three if @var{lines} is not given. @xref{Unified Format}.
3894 For proper operation, @command{patch} typically needs at least two lines of
3897 On older systems, @command{diff} supports an obsolete option
3898 @option{-@var{lines}} that has effect when combined with @option{-u}.
3899 @acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not allow
3900 this; use @option{-U @var{lines}} instead.
3904 Output version information and then exit.
3907 @itemx --ignore-all-space
3908 Ignore white space when comparing lines. @xref{White Space}.
3910 @item -W @var{columns}
3911 @itemx --width=@var{columns}
3912 Output at most @var{columns} (default 130) print columns per line in
3913 side by side format. @xref{Side by Side Format}.
3915 @item -x @var{pattern}
3916 @itemx --exclude=@var{pattern}
3917 When comparing directories, ignore files and subdirectories whose basenames
3918 match @var{pattern}. @xref{Comparing Directories}.
3921 @itemx --exclude-from=@var{file}
3922 When comparing directories, ignore files and subdirectories whose basenames
3923 match any pattern contained in @var{file}. @xref{Comparing Directories}.
3926 @itemx --side-by-side
3927 Use the side by side output format. @xref{Side by Side Format}.
3930 @node Invoking diff3
3931 @chapter Invoking @command{diff3}
3932 @cindex invoking @command{diff3}
3933 @cindex @command{diff3} invocation
3935 The @command{diff3} command compares three files and outputs descriptions
3936 of their differences. Its arguments are as follows:
3939 diff3 @var{options}@dots{} @var{mine} @var{older} @var{yours}
3942 The files to compare are @var{mine}, @var{older}, and @var{yours}.
3943 At most one of these three file names may be @file{-},
3944 which tells @command{diff3} to read the standard input for that file.
3946 An exit status of 0 means @command{diff3} was successful, 1 means some
3947 conflicts were found, and 2 means trouble.
3950 * diff3 Options:: Summary of options to @command{diff3}.
3954 @section Options to @command{diff3}
3955 @cindex @command{diff3} options
3956 @cindex options for @command{diff3}
3958 Below is a summary of all of the options that @acronym{GNU} @command{diff3}
3959 accepts. Multiple single letter options (unless they take an argument)
3960 can be combined into a single command line argument.
3965 Treat all files as text and compare them line-by-line, even if they
3966 do not appear to be text. @xref{Binary}.
3970 Incorporate all unmerged changes from @var{older} to @var{yours} into
3971 @var{mine}, surrounding conflicts with bracket lines.
3972 @xref{Marking Conflicts}.
3974 @item --diff-program=@var{program}
3975 Use the compatible comparison program @var{program} to compare files
3976 instead of @command{diff}.
3980 Generate an @command{ed} script that incorporates all the changes from
3981 @var{older} to @var{yours} into @var{mine}. @xref{Which Changes}.
3984 @itemx --show-overlap
3985 Like @option{-e}, except bracket lines from overlapping changes' first
3987 @xref{Marking Conflicts}.
3988 With @option{-E}, an overlapping change looks like this:
3992 @r{lines from @var{mine}}
3994 @r{lines from @var{yours}}
3999 Output a summary of usage and then exit.
4002 Generate @samp{w} and @samp{q} commands at the end of the @command{ed}
4003 script for System V compatibility. This option must be combined with
4004 one of the @option{-AeExX3} options, and may not be combined with @option{-m}.
4005 @xref{Saving the Changed File}.
4007 @item --label=@var{label}
4008 Use the label @var{label} for the brackets output by the @option{-A},
4009 @option{-E} and @option{-X} options. This option may be given up to three
4010 times, one for each input file. The default labels are the names of
4011 the input files. Thus @samp{diff3 --label X --label Y --label Z -m A
4013 @samp{diff3 -m A B C}, except that the output looks like it came from
4014 files named @samp{X}, @samp{Y} and @samp{Z} rather than from files
4015 named @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}.
4019 Apply the edit script to the first file and send the result to standard
4020 output. Unlike piping the output from @command{diff3} to @command{ed}, this
4021 works even for binary files and incomplete lines. @option{-A} is assumed
4022 if no edit script option is specified. @xref{Bypassing ed}.
4024 @item --strip-trailing-cr
4025 Strip any trailing carriage return at the end of an input line.
4029 @itemx --initial-tab
4030 Output a tab rather than two spaces before the text of a line in normal format.
4031 This causes the alignment of tabs in the line to look normal. @xref{Tabs}.
4035 Output version information and then exit.
4038 @itemx --overlap-only
4039 Like @option{-e}, except output only the overlapping changes.
4040 @xref{Which Changes}.
4043 Like @option{-E}, except output only the overlapping changes.
4044 In other words, like @option{-x}, except bracket changes as in @option{-E}.
4045 @xref{Marking Conflicts}.
4049 Like @option{-e}, except output only the nonoverlapping changes.
4050 @xref{Which Changes}.
4053 @node Invoking patch
4054 @chapter Invoking @command{patch}
4055 @cindex invoking @command{patch}
4056 @cindex @command{patch} invocation
4058 Normally @command{patch} is invoked like this:
4061 patch <@var{patchfile}
4064 The full format for invoking @command{patch} is:
4067 patch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]}
4070 You can also specify where to read the patch from with the @option{-i
4071 @var{patchfile}} or @option{--input=@var{patchfile}} option.
4072 If you do not specify @var{patchfile}, or if @var{patchfile} is
4073 @file{-}, @command{patch} reads the patch (that is, the @command{diff} output)
4074 from the standard input.
4076 If you do not specify an input file on the command line, @command{patch}
4077 tries to intuit from the @dfn{leading text} (any text in the patch
4078 that comes before the @command{diff} output) which file to edit.
4079 @xref{Multiple Patches}.
4081 By default, @command{patch} replaces the original input file with the
4082 patched version, possibly after renaming the original file into a
4083 backup file (@pxref{Backup Names}, for a description of how
4084 @command{patch} names backup files). You can also specify where to
4085 put the output with the @option{-o @var{file}} or
4086 @option{--output=@var{file}} option; however, do not use this option
4087 if @var{file} is one of the input files.
4090 * patch Options:: Summary table of options to @command{patch}.
4094 @section Options to @command{patch}
4095 @cindex @command{patch} options
4096 @cindex options for @command{patch}
4098 Here is a summary of all of the options that @acronym{GNU} @command{patch}
4099 accepts. @xref{patch and Tradition}, for which of these options are
4100 safe to use in older versions of @command{patch}.
4102 Multiple single-letter options that do not take an argument can be
4103 combined into a single command line argument with only one dash.
4108 Back up the original contents of each file, even if backups would
4109 normally not be made. @xref{Backups}.
4111 @item -B @var{prefix}
4112 @itemx --prefix=@var{prefix}
4113 Prepend @var{prefix} to backup file names. @xref{Backup Names}.
4115 @item --backup-if-mismatch
4116 Back up the original contents of each file if the patch does not
4117 exactly match the file. This is the default behavior when not
4118 conforming to @acronym{POSIX}. @xref{Backups}.
4121 Read and write all files in binary mode, except for standard output
4122 and @file{/dev/tty}. This option has no effect on
4123 @acronym{POSIX}-conforming systems like @acronym{GNU}/Linux. On systems where
4124 this option makes a difference, the patch should be generated by
4125 @samp{diff -a --binary}. @xref{Binary}.
4129 Interpret the patch file as a context diff. @xref{patch Input}.
4131 @item -d @var{directory}
4132 @itemx --directory=@var{directory}
4133 Make directory @var{directory} the current directory for interpreting
4134 both file names in the patch file, and file names given as arguments to
4135 other options. @xref{patch Directories}.
4138 @itemx --ifdef=@var{name}
4139 Make merged if-then-else output using @var{name}. @xref{If-then-else}.
4142 Print the results of applying the patches without actually changing
4143 any files. @xref{Dry Runs}.
4147 Interpret the patch file as an @command{ed} script. @xref{patch Input}.
4150 @itemx --remove-empty-files
4151 Remove output files that are empty after the patches have been applied.
4152 @xref{Creating and Removing}.
4156 Assume that the user knows exactly what he or she is doing, and do not
4157 ask any questions. @xref{patch Messages}.
4159 @item -F @var{lines}
4160 @itemx --fuzz=@var{lines}
4161 Set the maximum fuzz factor to @var{lines}. @xref{Inexact}.
4164 @itemx --get=@var{num}
4165 If @var{num} is positive, get input files from a revision control
4166 system as necessary; if zero, do not get the files; if negative, ask
4167 the user whether to get the files. @xref{Revision Control}.
4170 Output a summary of usage and then exit.
4172 @item -i @var{patchfile}
4173 @itemx --input=@var{patchfile}
4174 Read the patch from @var{patchfile} rather than from standard input.
4175 @xref{patch Options}.
4178 @itemx --ignore-white-space
4179 Let any sequence of blanks (spaces or tabs) in the patch file match
4180 any sequence of blanks in the input file. @xref{Changed White Space}.
4184 Interpret the patch file as a normal diff. @xref{patch Input}.
4188 Ignore patches that @command{patch} thinks are reversed or already applied.
4189 See also @option{-R}. @xref{Reversed Patches}.
4191 @item --no-backup-if-mismatch
4192 Do not back up the original contents of files. This is the default
4193 behavior when conforming to @acronym{POSIX}. @xref{Backups}.
4196 @itemx --output=@var{file}
4197 Use @var{file} as the output file name. @xref{patch Options}.
4199 @item -p@var{number}
4200 @itemx --strip=@var{number}
4201 Set the file name strip count to @var{number}. @xref{patch Directories}.
4204 Conform to @acronym{POSIX}, as if the @env{POSIXLY_CORRECT} environment
4205 variable had been set. @xref{patch and POSIX}.
4207 @item --quoting-style=@var{word}
4208 Use style @var{word} to quote names in diagnostics, as if the
4209 @env{QUOTING_STYLE} environment variable had been set to @var{word}.
4210 @xref{patch Quoting Style}.
4212 @item -r @var{reject-file}
4213 @itemx --reject-file=@var{reject-file}
4214 Use @var{reject-file} as the reject file name. @xref{Reject Names}.
4218 Assume that this patch was created with the old and new files swapped.
4219 @xref{Reversed Patches}.
4224 Work silently unless an error occurs. @xref{patch Messages}.
4228 Do not ask any questions. @xref{patch Messages}.
4232 Set the modification and access times of patched files from time
4233 stamps given in context diff headers, assuming that the context diff
4234 headers use local time. @xref{Patching Time Stamps}.
4238 Interpret the patch file as a unified diff. @xref{patch Input}.
4242 Output version information and then exit.
4244 @item -V @var{backup-style}
4245 @itemx --version=control=@var{backup-style}
4246 Select the naming convention for backup file names. @xref{Backup Names}.
4249 Print more diagnostics than usual. @xref{patch Messages}.
4251 @item -x @var{number}
4252 @itemx --debug=@var{number}
4253 Set internal debugging flags. Of interest only to @command{patch}
4256 @item -Y @var{prefix}
4257 @itemx --basename-prefix=@var{prefix}
4258 Prepend @var{prefix} to base names of backup files. @xref{Backup Names}.
4260 @item -z @var{suffix}
4261 @itemx --suffix=@var{suffix}
4262 Use @var{suffix} as the backup extension instead of @samp{.orig} or
4263 @samp{~}. @xref{Backup Names}.
4267 Set the modification and access times of patched files from time
4268 stamps given in context diff headers, assuming that the context diff
4269 headers use @acronym{UTC}. @xref{Patching Time Stamps}.
4273 @node Invoking sdiff
4274 @chapter Invoking @command{sdiff}
4275 @cindex invoking @command{sdiff}
4276 @cindex @command{sdiff} invocation
4278 The @command{sdiff} command merges two files and interactively outputs the
4279 results. Its arguments are as follows:
4282 sdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file}
4285 This merges @var{from-file} with @var{to-file}, with output to @var{outfile}.
4286 If @var{from-file} is a directory and @var{to-file} is not, @command{sdiff}
4287 compares the file in @var{from-file} whose file name is that of @var{to-file},
4288 and vice versa. @var{from-file} and @var{to-file} may not both be
4291 @command{sdiff} options begin with @samp{-}, so normally @var{from-file}
4292 and @var{to-file} may not begin with @samp{-}. However, @option{--} as an
4293 argument by itself treats the remaining arguments as file names even if
4294 they begin with @samp{-}. You may not use @file{-} as an input file.
4296 @command{sdiff} without @option{-o} (or @option{--output}) produces a
4297 side-by-side difference. This usage is obsolete; use the @option{-y}
4298 or @option{--side-by-side} option of @command{diff} instead.
4300 An exit status of 0 means no differences were found, 1 means some
4301 differences were found, and 2 means trouble.
4304 * sdiff Options:: Summary of options to @command{diff}.
4308 @section Options to @command{sdiff}
4309 @cindex @command{sdiff} options
4310 @cindex options for @command{sdiff}
4312 Below is a summary of all of the options that @acronym{GNU}
4313 @command{sdiff} accepts. Each option has two equivalent names, one of
4314 which is a single letter preceded by @samp{-}, and the other of which
4315 is a long name preceded by @samp{--}. Multiple single letter options
4316 (unless they take an argument) can be combined into a single command
4317 line argument. Long named options can be abbreviated to any unique
4318 prefix of their name.
4323 Treat all files as text and compare them line-by-line, even if they
4324 do not appear to be text. @xref{Binary}.
4327 @itemx --ignore-space-change
4328 Ignore changes in amount of white space. @xref{White Space}.
4331 @itemx --ignore-blank-lines
4332 Ignore changes that just insert or delete blank lines. @xref{Blank
4337 Change the algorithm to perhaps find a smaller set of changes. This
4338 makes @command{sdiff} slower (sometimes much slower). @xref{diff
4341 @item --diff-program=@var{program}
4342 Use the compatible comparison program @var{program} to compare files
4343 instead of @command{diff}.
4346 @itemx --ignore-tab-expansion
4347 Ignore changes due to tab expansion.
4351 Output a summary of usage and then exit.
4354 @itemx --ignore-case
4355 Ignore changes in case; consider upper- and lower-case to be the same.
4356 @xref{Case Folding}.
4358 @item -I @var{regexp}
4359 @itemx --ignore-matching-lines=@var{regexp}
4360 Ignore changes that just insert or delete lines that match @var{regexp}.
4361 @xref{Specified Lines}.
4364 @itemx --left-column
4365 Print only the left column of two common lines.
4366 @xref{Side by Side Format}.
4369 @itemx --output=@var{file}
4370 Put merged output into @var{file}. This option is required for merging.
4373 @itemx --suppress-common-lines
4374 Do not print common lines. @xref{Side by Side Format}.
4376 @item --speed-large-files
4377 Use heuristics to speed handling of large files that have numerous
4378 scattered small changes. @xref{diff Performance}.
4380 @item --strip-trailing-cr
4381 Strip any trailing carriage return at the end of an input line.
4385 @itemx --expand-tabs
4386 Expand tabs to spaces in the output, to preserve the alignment of tabs
4387 in the input files. @xref{Tabs}.
4389 @item --tabsize=@var{columns}
4390 Assume that tab stops are set every @var{columns} (default 8) print
4391 columns. @xref{Tabs}.
4395 Output version information and then exit.
4397 @item -w @var{columns}
4398 @itemx --width=@var{columns}
4399 Output at most @var{columns} (default 130) print columns per line.
4400 @xref{Side by Side Format}. Note that for historical reasons, this
4401 option is @option{-W} in @command{diff}, @option{-w} in @command{sdiff}.
4404 @itemx --ignore-all-space
4405 Ignore white space when comparing lines. @xref{White Space}.
4406 Note that for historical reasons, this option is @option{-w} in @command{diff},
4407 @option{-W} in @command{sdiff}.
4410 @node Standards conformance
4411 @chapter Standards conformance
4412 @cindex @acronym{POSIX}
4414 @vindex POSIXLY_CORRECT
4415 In a few cases, the @acronym{GNU} utilities' default behavior is
4416 incompatible with the @acronym{POSIX} standard. To suppress these
4417 incompatibilities, define the @env{POSIXLY_CORRECT} environment
4418 variable. Unless you are checking for @acronym{POSIX} conformance, you
4419 probably do not need to define @env{POSIXLY_CORRECT}.
4421 Normally options and operands can appear in any order, and programs act
4422 as if all the options appear before any operands. For example,
4423 @samp{diff lao tzu -C 2} acts like @samp{diff -C 2 lao tzu}, since
4424 @samp{2} is an option-argument of @option{-C}. However, if the
4425 @env{POSIXLY_CORRECT} environment variable is set, options must appear
4426 before operands, unless otherwise specified for a particular command.
4428 Newer versions of @acronym{POSIX} are occasionally incompatible with older
4429 versions. For example, older versions of @acronym{POSIX} allowed the
4430 command @samp{diff -c -10} to have the same meaning as @samp{diff -C
4431 10}, but @acronym{POSIX} 1003.1-2001 @samp{diff} no longer allows
4432 digit-string options like @option{-10}.
4434 @vindex _POSIX2_VERSION
4435 The @acronym{GNU} utilities normally conform to the version of @acronym{POSIX}
4436 that is standard for your system. To cause them to conform to a
4437 different version of @acronym{POSIX}, define the @env{_POSIX2_VERSION}
4438 environment variable to a value of the form @var{yyyymm} specifying
4439 the year and month the standard was adopted. Two values are currently
4440 supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
4441 @acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX}
4442 1003.1-2001. For example, if you are running older software that
4443 assumes an older version of @acronym{POSIX} and uses @samp{diff -c -10},
4444 you can work around the compatibility problems by setting
4445 @samp{_POSIX2_VERSION=199209} in your environment.
4448 @chapter Future Projects
4450 Here are some ideas for improving @acronym{GNU} @command{diff} and
4451 @command{patch}. The @acronym{GNU} project has identified some
4452 improvements as potential programming projects for volunteers. You
4453 can also help by reporting any bugs that you find.
4455 If you are a programmer and would like to contribute something to the
4456 @acronym{GNU} project, please consider volunteering for one of these
4457 projects. If you are seriously contemplating work, please write to
4458 @email{gvc@@gnu.org} to coordinate with other volunteers.
4461 * Shortcomings:: Suggested projects for improvements.
4462 * Bugs:: Reporting bugs.
4466 @section Suggested Projects for Improving @acronym{GNU} @command{diff} and @command{patch}
4467 @cindex projects for directories
4469 One should be able to use @acronym{GNU} @command{diff} to generate a
4470 patch from any pair of directory trees, and given the patch and a copy
4471 of one such tree, use @command{patch} to generate a faithful copy of
4472 the other. Unfortunately, some changes to directory trees cannot be
4473 expressed using current patch formats; also, @command{patch} does not
4474 handle some of the existing formats. These shortcomings motivate the
4475 following suggested projects.
4478 * Internationalization:: Handling multibyte and varying-width characters.
4479 * Changing Structure:: Handling changes to the directory structure.
4480 * Special Files:: Handling symbolic links, device special files, etc.
4481 * Unusual File Names:: Handling file names that contain unusual characters.
4482 * Time Stamp Order:: Outputting diffs in time stamp order.
4483 * Ignoring Changes:: Ignoring certain changes while showing others.
4484 * Speedups:: Improving performance.
4487 @node Internationalization
4488 @subsection Handling Multibyte and Varying-Width Characters
4489 @cindex multibyte characters
4490 @cindex varying-width characters
4492 @command{diff}, @command{diff3} and @command{sdiff} treat each line of
4493 input as a string of unibyte characters. This can mishandle multibyte
4494 characters in some cases. For example, when asked to ignore spaces,
4495 @command{diff} does not properly ignore a multibyte space character.
4497 Also, @command{diff} currently assumes that each byte is one column
4498 wide, and this assumption is incorrect in some locales, e.g., locales
4499 that use UTF-8 encoding. This causes problems with the @option{-y} or
4500 @option{--side-by-side} option of @command{diff}.
4502 These problems need to be fixed without unduly affecting the
4503 performance of the utilities in unibyte environments.
4505 The IBM GNU/Linux Technology Center Internationalization Team has
4507 @uref{http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz,patches
4508 to support internationalized @command{diff}}.
4509 Unfortunately, these patches are incomplete and are to an older
4510 version of @command{diff}, so more work needs to be done in this area.
4512 @node Changing Structure
4513 @subsection Handling Changes to the Directory Structure
4514 @cindex directory structure changes
4516 @command{diff} and @command{patch} do not handle some changes to directory
4517 structure. For example, suppose one directory tree contains a directory
4518 named @samp{D} with some subsidiary files, and another contains a file
4519 with the same name @samp{D}. @samp{diff -r} does not output enough
4520 information for @command{patch} to transform the directory subtree into
4523 There should be a way to specify that a file has been removed without
4524 having to include its entire contents in the patch file. There should
4525 also be a way to tell @command{patch} that a file was renamed, even if
4526 there is no way for @command{diff} to generate such information.
4527 There should be a way to tell @command{patch} that a file's time stamp
4528 has changed, even if its contents have not changed.
4530 These problems can be fixed by extending the @command{diff} output format
4531 to represent changes in directory structure, and extending @command{patch}
4532 to understand these extensions.
4535 @subsection Files that are Neither Directories Nor Regular Files
4536 @cindex special files
4538 Some files are neither directories nor regular files: they are unusual
4539 files like symbolic links, device special files, named pipes, and
4540 sockets. Currently, @command{diff} treats symbolic links as if they
4541 were the pointed-to files, except that a recursive @command{diff}
4542 reports an error if it detects infinite loops of symbolic links (e.g.,
4543 symbolic links to @file{..}). @command{diff} treats other special
4544 files like regular files if they are specified at the top level, but
4545 simply reports their presence when comparing directories. This means
4546 that @command{patch} cannot represent changes to such files. For
4547 example, if you change which file a symbolic link points to,
4548 @command{diff} outputs the difference between the two files, instead
4549 of the change to the symbolic link.
4551 @c This might not be a good idea; is it wise for root to install devices
4553 @command{diff} should optionally report changes to special files specially,
4554 and @command{patch} should be extended to understand these extensions.
4556 @node Unusual File Names
4557 @subsection File Names that Contain Unusual Characters
4558 @cindex file names with unusual characters
4560 When a file name contains an unusual character like a newline or
4561 white space, @samp{diff -r} generates a patch that @command{patch} cannot
4562 parse. The problem is with format of @command{diff} output, not just with
4563 @command{patch}, because with odd enough file names one can cause
4564 @command{diff} to generate a patch that is syntactically correct but
4565 patches the wrong files. The format of @command{diff} output should be
4566 extended to handle all possible file names.
4568 @node Time Stamp Order
4569 @subsection Outputting Diffs in Time Stamp Order
4571 Applying @command{patch} to a multiple-file diff can result in files
4572 whose time stamps are out of order. @acronym{GNU} @command{patch} has
4573 options to restore the time stamps of the updated files
4574 (@pxref{Patching Time Stamps}), but sometimes it is useful to generate
4575 a patch that works even if the recipient does not have @acronym{GNU} patch,
4576 or does not use these options. One way to do this would be to
4577 implement a @command{diff} option to output diffs in time stamp order.
4579 @node Ignoring Changes
4580 @subsection Ignoring Certain Changes
4582 It would be nice to have a feature for specifying two strings, one in
4583 @var{from-file} and one in @var{to-file}, which should be considered to
4584 match. Thus, if the two strings are @samp{foo} and @samp{bar}, then if
4585 two lines differ only in that @samp{foo} in file 1 corresponds to
4586 @samp{bar} in file 2, the lines are treated as identical.
4588 It is not clear how general this feature can or should be, or
4589 what syntax should be used for it.
4591 A partial substitute is to filter one or both files before comparing,
4595 sed 's/foo/bar/g' file1 | diff - file2
4598 However, this outputs the filtered text, not the original.
4601 @subsection Improving Performance
4603 When comparing two large directory structures, one of which was
4604 originally copied from the other with time stamps preserved (e.g.,
4605 with @samp{cp -pR}), it would greatly improve performance if an option
4606 told @command{diff} to assume that two files with the same size and
4607 time stamps have the same content. @xref{diff Performance}.
4610 @section Reporting Bugs
4612 @cindex reporting bugs
4614 If you think you have found a bug in @acronym{GNU} @command{cmp},
4615 @command{diff}, @command{diff3}, or @command{sdiff}, please report it
4616 by electronic mail to the
4617 @uref{http://mail.gnu.org/mailman/listinfo/bug-gnu-utils,GNU utilities
4618 bug report mailing list} @email{bug-gnu-utils@@gnu.org}. Please send
4619 bug reports for @acronym{GNU} @command{patch} to
4620 @email{bug-patch@@gnu.org}. Send as precise a description of the
4621 problem as you can, including the output of the @option{--version}
4622 option and sample input files that produce the bug, if applicable. If
4623 you have a nontrivial fix for the bug, please send it as well. If you
4624 have a patch, please send it too. It may simplify the maintainer's
4625 job if the patch is relative to a recent test release, which you can
4626 find in the directory @uref{ftp://alpha.gnu.org/gnu/diffutils/}.
4628 @node Copying This Manual
4629 @appendix Copying This Manual
4632 * GNU Free Documentation License:: License for copying this manual.
4638 @appendix Translations of This Manual
4640 Nishio Futoshi of the GNUjdoc project has prepared a Japanese
4641 translation of this manual. Its most recent version can be found at
4642 @uref{http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/}.