summaryrefslogtreecommitdiff
path: root/gnu/dist/diffutils/diff.info-2
diff options
context:
space:
mode:
Diffstat (limited to 'gnu/dist/diffutils/diff.info-2')
-rw-r--r--gnu/dist/diffutils/diff.info-21312
1 files changed, 0 insertions, 1312 deletions
diff --git a/gnu/dist/diffutils/diff.info-2 b/gnu/dist/diffutils/diff.info-2
deleted file mode 100644
index 43fae2835c7..00000000000
--- a/gnu/dist/diffutils/diff.info-2
+++ /dev/null
@@ -1,1312 +0,0 @@
-This is Info file diff.info, produced by Makeinfo-1.55 from the input
-file ./diff.texi.
-
- This file documents the the GNU `diff', `diff3', `sdiff', and `cmp'
-commands for showing the differences between text files and the `patch'
-command for using their output to update files.
-
- Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
-
-File: diff.info, Node: Line Group Formats, Next: Line Formats, Up: If-then-else
-
-Line Group Formats
-------------------
-
- Line group formats let you specify formats suitable for many
-applications that allow if-then-else input, including programming
-languages and text formatting languages. A line group format specifies
-the output format for a contiguous group of similar lines.
-
- For example, the following command compares the TeX files `old' and
-`new', and outputs a merged file in which old regions are surrounded by
-`\begin{em}'-`\end{em}' lines, and new regions are surrounded by
-`\begin{bf}'-`\end{bf}' lines.
-
- diff \
- --old-group-format='\begin{em}
- %<\end{em}
- ' \
- --new-group-format='\begin{bf}
- %>\end{bf}
- ' \
- old new
-
- The following command is equivalent to the above example, but it is a
-little more verbose, because it spells out the default line group
-formats.
-
- diff \
- --old-group-format='\begin{em}
- %<\end{em}
- ' \
- --new-group-format='\begin{bf}
- %>\end{bf}
- ' \
- --unchanged-group-format='%=' \
- --changed-group-format='\begin{em}
- %<\end{em}
- \begin{bf}
- %>\end{bf}
- ' \
- old new
-
- Here is a more advanced example, which outputs a diff listing with
-headers containing line numbers in a "plain English" style.
-
- diff \
- --unchanged-group-format='' \
- --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
- %<' \
- --new-group-format='-------- %dN line%(N=1?:s) added after %de:
- %>' \
- --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
- %<-------- to:
- %>' \
- old new
-
- To specify a line group format, use `diff' with one of the options
-listed below. You can specify up to four line group formats, one for
-each kind of line group. You should quote FORMAT, because it typically
-contains shell metacharacters.
-
-`--old-group-format=FORMAT'
- These line groups are hunks containing only lines from the first
- file. The default old group format is the same as the changed
- group format if it is specified; otherwise it is a format that
- outputs the line group as-is.
-
-`--new-group-format=FORMAT'
- These line groups are hunks containing only lines from the second
- file. The default new group format is same as the the changed
- group format if it is specified; otherwise it is a format that
- outputs the line group as-is.
-
-`--changed-group-format=FORMAT'
- These line groups are hunks containing lines from both files. The
- default changed group format is the concatenation of the old and
- new group formats.
-
-`--unchanged-group-format=FORMAT'
- These line groups contain lines common to both files. The default
- unchanged group format is a format that outputs the line group
- as-is.
-
- In a line group format, ordinary characters represent themselves;
-conversion specifications start with `%' and have one of the following
-forms.
-
-`%<'
- stands for the lines from the first file, including the trailing
- newline. Each line is formatted according to the old line format
- (*note Line Formats::.).
-
-`%>'
- stands for the lines from the second file, including the trailing
- newline. Each line is formatted according to the new line format.
-
-`%='
- stands for the lines common to both files, including the trailing
- newline. Each line is formatted according to the unchanged line
- format.
-
-`%%'
- stands for `%'.
-
-`%c'C''
- where C is a single character, stands for C. C may not be a
- backslash or an apostrophe. For example, `%c':'' stands for a
- colon, even inside the then-part of an if-then-else format, which
- a colon would normally terminate.
-
-`%c'\O''
- where O is a string of 1, 2, or 3 octal digits, stands for the
- character with octal code O. For example, `%c'\0'' stands for a
- null character.
-
-`FN'
- where F is a `printf' conversion specification and N is one of the
- following letters, stands for N's value formatted with F.
-
- `e'
- The line number of the line just before the group in the old
- file.
-
- `f'
- The line number of the first line in the group in the old
- file; equals E + 1.
-
- `l'
- The line number of the last line in the group in the old file.
-
- `m'
- The line number of the line just after the group in the old
- file; equals L + 1.
-
- `n'
- The number of lines in the group in the old file; equals L -
- F + 1.
-
- `E, F, L, M, N'
- Likewise, for lines in the new file.
-
- The `printf' conversion specification can be `%d', `%o', `%x', or
- `%X', specifying decimal, octal, lower case hexadecimal, or upper
- case hexadecimal output respectively. After the `%' the following
- options can appear in sequence: a `-' specifying
- left-justification; an integer specifying the minimum field width;
- and a period followed by an optional integer specifying the
- minimum number of digits. For example, `%5dN' prints the number
- of new lines in the group in a field of width 5 characters, using
- the `printf' format `"%5d"'.
-
-`(A=B?T:E)'
- If A equals B then T else E. A and B are each either a decimal
- constant or a single letter interpreted as above. This format
- spec is equivalent to T if A's value equals B's; otherwise it is
- equivalent to E.
-
- For example, `%(N=0?no:%dN) line%(N=1?:s)' is equivalent to `no
- lines' if N (the number of lines in the group in the the new file)
- is 0, to `1 line' if N is 1, and to `%dN lines' otherwise.
-
-
-File: diff.info, Node: Line Formats, Next: Detailed If-then-else, Prev: Line Group Formats, Up: If-then-else
-
-Line Formats
-------------
-
- Line formats control how each line taken from an input file is
-output as part of a line group in if-then-else format.
-
- For example, the following command outputs text with a one-column
-change indicator to the left of the text. The first column of output
-is `-' for deleted lines, `|' for added lines, and a space for
-unchanged lines. The formats contain newline characters where newlines
-are desired on output.
-
- diff \
- --old-line-format='-%l
- ' \
- --new-line-format='|%l
- ' \
- --unchanged-line-format=' %l
- ' \
- old new
-
- To specify a line format, use one of the following options. You
-should quote FORMAT, since it often contains shell metacharacters.
-
-`--old-line-format=FORMAT'
- formats lines just from the first file.
-
-`--new-line-format=FORMAT'
- formats lines just from the second file.
-
-`--unchanged-line-format=FORMAT'
- formats lines common to both files.
-
-`--line-format=FORMAT'
- formats all lines; in effect, it sets all three above options
- simultaneously.
-
- In a line format, ordinary characters represent themselves;
-conversion specifications start with `%' and have one of the following
-forms.
-
-`%l'
- stands for the the contents of the line, not counting its trailing
- newline (if any). This format ignores whether the line is
- incomplete; *Note Incomplete Lines::.
-
-`%L'
- stands for the the contents of the line, including its trailing
- newline (if any). If a line is incomplete, this format preserves
- its incompleteness.
-
-`%%'
- stands for `%'.
-
-`%c'C''
- where C is a single character, stands for C. C may not be a
- backslash or an apostrophe. For example, `%c':'' stands for a
- colon.
-
-`%c'\O''
- where O is a string of 1, 2, or 3 octal digits, stands for the
- character with octal code O. For example, `%c'\0'' stands for a
- null character.
-
-`Fn'
- where F is a `printf' conversion specification, stands for the
- line number formatted with F. For example, `%.5dn' prints the
- line number using the `printf' format `"%.5d"'. *Note Line Group
- Formats::, for more about printf conversion specifications.
-
- The default line format is `%l' followed by a newline character.
-
- If the input contains tab characters and it is important that they
-line up on output, you should ensure that `%l' or `%L' in a line format
-is just after a tab stop (e.g. by preceding `%l' or `%L' with a tab
-character), or you should use the `-t' or `--expand-tabs' option.
-
- Taken together, the line and line group formats let you specify many
-different formats. For example, the following command uses a format
-similar to `diff''s normal format. You can tailor this command to get
-fine control over `diff''s output.
-
- diff \
- --old-line-format='< %l
- ' \
- --new-line-format='> %l
- ' \
- --old-group-format='%df%(f=l?:,%dl)d%dE
- %<' \
- --new-group-format='%dea%dF%(F=L?:,%dL)
- %>' \
- --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
- %<---
- %>' \
- --unchanged-group-format='' \
- old new
-
-
-File: diff.info, Node: Detailed If-then-else, Next: Example If-then-else, Prev: Line Formats, Up: If-then-else
-
-Detailed Description of If-then-else Format
--------------------------------------------
-
- For lines common to both files, `diff' uses the unchanged line group
-format. For each hunk of differences in the merged output format, if
-the hunk contains only lines from the first file, `diff' uses the old
-line group format; if the hunk contains only lines from the second
-file, `diff' uses the new group format; otherwise, `diff' uses the
-changed group format.
-
- The old, new, and unchanged line formats specify the output format of
-lines from the first file, lines from the second file, and lines common
-to both files, respectively.
-
- The option `--ifdef=NAME' is equivalent to the following sequence of
-options using shell syntax:
-
- --old-group-format='#ifndef NAME
- %<#endif /* not NAME */
- ' \
- --new-group-format='#ifdef NAME
- %>#endif /* NAME */
- ' \
- --unchanged-group-format='%=' \
- --changed-group-format='#ifndef NAME
- %<#else /* NAME */
- %>#endif /* NAME */
- '
-
- You should carefully check the `diff' output for proper nesting.
-For example, when using the the `-D NAME' or `--ifdef=NAME' option, you
-should check that if the differing lines contain any of the C
-preprocessor directives `#ifdef', `#ifndef', `#else', `#elif', or
-`#endif', they are nested properly and match. If they don't, you must
-make corrections manually. It is a good idea to carefully check the
-resulting code anyway to make sure that it really does what you want it
-to; depending on how the input files were produced, the output might
-contain duplicate or otherwise incorrect code.
-
- The `patch' `-D NAME' option behaves just like the `diff' `-D NAME'
-option, except it operates on a file and a diff to produce a merged
-file; *Note patch Options::.
-
-
-File: diff.info, Node: Example If-then-else, Prev: Detailed If-then-else, Up: If-then-else
-
-An Example of If-then-else Format
----------------------------------
-
- Here is the output of `diff -DTWO lao tzu' (*note Sample diff
-Input::., for the complete contents of the two files):
-
- #ifndef TWO
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
- #endif /* not TWO */
- The Nameless is the origin of Heaven and Earth;
- #ifndef TWO
- The Named is the mother of all things.
- #else /* TWO */
- The named is the mother of all things.
-
- #endif /* TWO */
- Therefore let there always be non-being,
- so we may see their subtlety,
- And let there always be being,
- so we may see their outcome.
- The two are the same,
- But after they are produced,
- they have different names.
- #ifdef TWO
- They both may be called deep and profound.
- Deeper and more profound,
- The door of all subtleties!
- #endif /* TWO */
-
-
-File: diff.info, Node: Comparing Directories, Next: Adjusting Output, Prev: Output Formats, Up: Top
-
-Comparing Directories
-*********************
-
- You can use `diff' to compare some or all of the files in two
-directory trees. When both file name arguments to `diff' are
-directories, it compares each file that is contained in both
-directories, examining file names in alphabetical order. Normally
-`diff' is silent about pairs of files that contain no differences, but
-if you use the `-s' or `--report-identical-files' option, it reports
-pairs of identical files. Normally `diff' reports subdirectories
-common to both directories without comparing subdirectories' files, but
-if you use the `-r' or `--recursive' option, it compares every
-corresponding pair of files in the directory trees, as many levels deep
-as they go.
-
- For file names that are in only one of the directories, `diff'
-normally does not show the contents of the file that exists; it reports
-only that the file exists in that directory and not in the other. You
-can make `diff' act as though the file existed but was empty in the
-other directory, so that it outputs the entire contents of the file that
-actually exists. (It is output as either an insertion or a deletion,
-depending on whether it is in the first or the second directory given.)
-To do this, use the `-N' or `--new-file' option.
-
- If the older directory contains one or more large files that are not
-in the newer directory, you can make the patch smaller by using the
-`-P' or `--unidirectional-new-file' option instead of `-N'. This
-option is like `-N' except that it only inserts the contents of files
-that appear in the second directory but not the first (that is, files
-that were added). At the top of the patch, write instructions for the
-user applying the patch to remove the files that were deleted before
-applying the patch. *Note Making Patches::, for more discussion of
-making patches for distribution.
-
- To ignore some files while comparing directories, use the `-x
-PATTERN' or `--exclude=PATTERN' option. This option ignores any files
-or subdirectories whose base names match the shell pattern PATTERN.
-Unlike in the shell, a period at the start of the base of a file name
-matches a wildcard at the start of a pattern. You should enclose
-PATTERN in quotes so that the shell does not expand it. For example,
-the option `-x '*.[ao]'' ignores any file whose name ends with `.a' or
-`.o'.
-
- This option accumulates if you specify it more than once. For
-example, using the options `-x 'RCS' -x '*,v'' ignores any file or
-subdirectory whose base name is `RCS' or ends with `,v'.
-
- If you need to give this option many times, you can instead put the
-patterns in a file, one pattern per line, and use the `-X FILE' or
-`--exclude-from=FILE' option.
-
- If you have been comparing two directories and stopped partway
-through, later you might want to continue where you left off. You can
-do this by using the `-S FILE' or `--starting-file=FILE' option. This
-compares only the file FILE and all alphabetically later files in the
-topmost directory level.
-
-
-File: diff.info, Node: Adjusting Output, Next: diff Performance, Prev: Comparing Directories, Up: Top
-
-Making `diff' Output Prettier
-*****************************
-
- `diff' provides several ways to adjust the appearance of its output.
-These adjustments can be applied to any output format.
-
-* Menu:
-
-* Tabs:: Preserving the alignment of tabstops.
-* Pagination:: Page numbering and timestamping `diff' output.
-
-
-File: diff.info, Node: Tabs, Next: Pagination, Up: Adjusting Output
-
-Preserving Tabstop Alignment
-============================
-
- The lines of text in some of the `diff' output formats are preceded
-by one or two characters that indicate whether the text is inserted,
-deleted, or changed. The addition of those characters can cause tabs to
-move to the next tabstop, throwing off the alignment of columns in the
-line. GNU `diff' provides two ways to make tab-aligned columns line up
-correctly.
-
- The first way is to have `diff' convert all tabs into the correct
-number of spaces before outputting them; select this method with the
-`-t' or `--expand-tabs' option. `diff' assumes that tabstops are set
-every 8 columns. To use this form of output with `patch', you must
-give `patch' the `-l' or `--ignore-white-space' option (*note Changed
-White Space::., for more information).
-
- The other method for making tabs line up correctly is to add a tab
-character instead of a space after the indicator character at the
-beginning of the line. This ensures that all following tab characters
-are in the same position relative to tabstops that they were in the
-original files, so that the output is aligned correctly. Its
-disadvantage is that it can make long lines too long to fit on one line
-of the screen or the paper. It also does not work with the unified
-output format, which does not have a space character after the change
-type indicator character. Select this method with the `-T' or
-`--initial-tab' option.
-
-
-File: diff.info, Node: Pagination, Prev: Tabs, Up: Adjusting Output
-
-Paginating `diff' Output
-========================
-
- It can be convenient to have long output page-numbered and
-time-stamped. The `-l' and `--paginate' options do this by sending the
-`diff' output through the `pr' program. Here is what the page header
-might look like for `diff -lc lao tzu':
-
- Mar 11 13:37 1991 diff -lc lao tzu Page 1
-
-
-File: diff.info, Node: diff Performance, Next: Comparing Three Files, Prev: Adjusting Output, Up: Top
-
-`diff' Performance Tradeoffs
-****************************
-
- GNU `diff' runs quite efficiently; however, in some circumstances
-you can cause it to run faster or produce a more compact set of changes.
-There are two ways that you can affect the performance of GNU `diff' by
-changing the way it compares files.
-
- Performance has more than one dimension. These options improve one
-aspect of performance at the cost of another, or they improve
-performance in some cases while hurting it in others.
-
- The way that GNU `diff' determines which lines have changed always
-comes up with a near-minimal set of differences. Usually it is good
-enough for practical purposes. If the `diff' output is large, you
-might want `diff' to use a modified algorithm that sometimes produces a
-smaller set of differences. The `-d' or `--minimal' option does this;
-however, it can also cause `diff' to run more slowly than usual, so it
-is not the default behavior.
-
- When the files you are comparing are large and have small groups of
-changes scattered throughout them, you can use the `-H' or
-`--speed-large-files' option to make a different modification to the
-algorithm that `diff' uses. If the input files have a constant small
-density of changes, this option speeds up the comparisons without
-changing the output. If not, `diff' might produce a larger set of
-differences; however, the output will still be correct.
-
- Normally `diff' discards the prefix and suffix that is common to
-both files before it attempts to find a minimal set of differences.
-This makes `diff' run faster, but occasionally it may produce
-non-minimal output. The `--horizon-lines=LINES' option prevents `diff'
-from discarding the last LINES lines of the prefix and the first LINES
-lines of the suffix. This gives `diff' further opportunities to find a
-minimal output.
-
-
-File: diff.info, Node: Comparing Three Files, Next: diff3 Merging, Prev: diff Performance, Up: Top
-
-Comparing Three Files
-*********************
-
- Use the program `diff3' to compare three files and show any
-differences among them. (`diff3' can also merge files; see *Note diff3
-Merging::).
-
- The "normal" `diff3' output format shows each hunk of differences
-without surrounding context. Hunks are labeled depending on whether
-they are two-way or three-way, and lines are annotated by their
-location in the input files.
-
- *Note Invoking diff3::, for more information on how to run `diff3'.
-
-* Menu:
-
-* Sample diff3 Input:: Sample `diff3' input for examples.
-* Detailed diff3 Normal:: A detailed description of normal output format.
-* diff3 Hunks:: The format of normal output format.
-* Example diff3 Normal:: Sample output in the normal format.
-
-
-File: diff.info, Node: Sample diff3 Input, Next: Detailed diff3 Normal, Up: Comparing Three Files
-
-A Third Sample Input File
-=========================
-
- Here is a third sample file that will be used in examples to
-illustrate the output of `diff3' and how various options can change it.
-The first two files are the same that we used for `diff' (*note Sample
-diff Input::.). This is the third sample file, called `tao':
-
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
- The Nameless is the origin of Heaven and Earth;
- The named is the mother of all things.
-
- Therefore let there always be non-being,
- so we may see their subtlety,
- And let there always be being,
- so we may see their result.
- The two are the same,
- But after they are produced,
- they have different names.
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
-
-
-File: diff.info, Node: Detailed diff3 Normal, Next: diff3 Hunks, Prev: Sample diff3 Input, Up: Comparing Three Files
-
-Detailed Description of `diff3' Normal Format
-=============================================
-
- Each hunk begins with a line marked `===='. Three-way hunks have
-plain `====' lines, and two-way hunks have `1', `2', or `3' appended to
-specify which of the three input files differ in that hunk. The hunks
-contain copies of two or three sets of input lines each preceded by one
-or two commands identifying where the lines came from.
-
- Normally, two spaces precede each copy of an input line to
-distinguish it from the commands. But with the `-T' or `--initial-tab'
-option, `diff3' uses a tab instead of two spaces; this lines up tabs
-correctly. *Note Tabs::, for more information.
-
- Commands take the following forms:
-
-`FILE:La'
- This hunk appears after line L of file FILE, and contains no lines
- in that file. To edit this file to yield the other files, one
- must append hunk lines taken from the other files. For example,
- `1:11a' means that the hunk follows line 11 in the first file and
- contains no lines from that file.
-
-`FILE:Rc'
- This hunk contains the lines in the range R of file FILE. The
- range R is a comma-separated pair of line numbers, or just one
- number if the range is a singleton. To edit this file to yield the
- other files, one must change the specified lines to be the lines
- taken from the other files. For example, `2:11,13c' means that
- the hunk contains lines 11 through 13 from the second file.
-
- If the last line in a set of input lines is incomplete (*note
-Incomplete Lines::.), it is distinguished on output from a full line by
-a following line that starts with `\'.
-
-
-File: diff.info, Node: diff3 Hunks, Next: Example diff3 Normal, Prev: Detailed diff3 Normal, Up: Comparing Three Files
-
-`diff3' Hunks
-=============
-
- Groups of lines that differ in two or three of the input files are
-called "diff3 hunks", by analogy with `diff' hunks (*note Hunks::.).
-If all three input files differ in a `diff3' hunk, the hunk is called a
-"three-way hunk"; if just two input files differ, it is a "two-way
-hunk".
-
- As with `diff', several solutions are possible. When comparing the
-files `A', `B', and `C', `diff3' normally finds `diff3' hunks by
-merging the two-way hunks output by the two commands `diff A B' and
-`diff A C'. This does not necessarily minimize the size of the output,
-but exceptions should be rare.
-
- For example, suppose `F' contains the three lines `a', `b', `f', `G'
-contains the lines `g', `b', `g', and `H' contains the lines `a', `b',
-`h'. `diff3 F G H' might output the following:
-
- ====2
- 1:1c
- 3:1c
- a
- 2:1c
- g
- ====
- 1:3c
- f
- 2:3c
- g
- 3:3c
- h
-
-because it found a two-way hunk containing `a' in the first and third
-files and `g' in the second file, then the single line `b' common to
-all three files, then a three-way hunk containing the last line of each
-file.
-
-
-File: diff.info, Node: Example diff3 Normal, Prev: diff3 Hunks, Up: Comparing Three Files
-
-An Example of `diff3' Normal Format
-===================================
-
- Here is the output of the command `diff3 lao tzu tao' (*note Sample
-diff3 Input::., for the complete contents of the files). Notice that
-it shows only the lines that are different among the three files.
-
- ====2
- 1:1,2c
- 3:1,2c
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
- 2:0a
- ====1
- 1:4c
- The Named is the mother of all things.
- 2:2,3c
- 3:4,5c
- The named is the mother of all things.
-
- ====3
- 1:8c
- 2:7c
- so we may see their outcome.
- 3:9c
- so we may see their result.
- ====
- 1:11a
- 2:11,13c
- They both may be called deep and profound.
- Deeper and more profound,
- The door of all subtleties!
- 3:13,14c
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
-
-
-File: diff.info, Node: diff3 Merging, Next: Interactive Merging, Prev: Comparing Three Files, Up: Top
-
-Merging From a Common Ancestor
-******************************
-
- When two people have made changes to copies of the same file,
-`diff3' can produce a merged output that contains both sets of changes
-together with warnings about conflicts.
-
- One might imagine programs with names like `diff4' and `diff5' to
-compare more than three files simultaneously, but in practice the need
-rarely arises. You can use `diff3' to merge three or more sets of
-changes to a file by merging two change sets at a time.
-
- `diff3' can incorporate changes from two modified versions into a
-common preceding version. This lets you merge the sets of changes
-represented by the two newer files. Specify the common ancestor version
-as the second argument and the two newer versions as the first and third
-arguments, like this:
-
- diff3 MINE OLDER YOURS
-
-You can remember the order of the arguments by noting that they are in
-alphabetical order.
-
- You can think of this as subtracting OLDER from YOURS and adding the
-result to MINE, or as merging into MINE the changes that would turn
-OLDER into YOURS. This merging is well-defined as long as MINE and
-OLDER match in the neighborhood of each such change. This fails to be
-true when all three input files differ or when only OLDER differs; we
-call this a "conflict". When all three input files differ, we call the
-conflict an "overlap".
-
- `diff3' gives you several ways to handle overlaps and conflicts.
-You can omit overlaps or conflicts, or select only overlaps, or mark
-conflicts with special `<<<<<<<' and `>>>>>>>' lines.
-
- `diff3' can output the merge results as an `ed' script that that can
-be applied to the first file to yield the merged output. However, it
-is usually better to have `diff3' generate the merged output directly;
-this bypasses some problems with `ed'.
-
-* Menu:
-
-* Which Changes:: Selecting changes to incorporate.
-* Marking Conflicts:: Marking conflicts.
-* Bypassing ed:: Generating merged output directly.
-* Merging Incomplete Lines:: How `diff3' merges incomplete lines.
-* Saving the Changed File:: Emulating System V behavior.
-
-
-File: diff.info, Node: Which Changes, Next: Marking Conflicts, Up: diff3 Merging
-
-Selecting Which Changes to Incorporate
-======================================
-
- You can select all unmerged changes from OLDER to YOURS for merging
-into MINE with the `-e' or `--ed' option. You can select only the
-nonoverlapping unmerged changes with `-3' or `--easy-only', and you can
-select only the overlapping changes with `-x' or `--overlap-only'.
-
- The `-e', `-3' and `-x' options select only "unmerged changes", i.e.
-changes where MINE and YOURS differ; they ignore changes from OLDER to
-YOURS where MINE and YOURS are identical, because they assume that such
-changes have already been merged. If this assumption is not a safe
-one, you can use the `-A' or `--show-all' option (*note Marking
-Conflicts::.).
-
- Here is the output of the command `diff3' with each of these three
-options (*note Sample diff3 Input::., for the complete contents of the
-files). Notice that `-e' outputs the union of the disjoint sets of
-changes output by `-3' and `-x'.
-
- Output of `diff3 -e lao tzu tao':
- 11a
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
- .
- 8c
- so we may see their result.
- .
-
- Output of `diff3 -3 lao tzu tao':
- 8c
- so we may see their result.
- .
-
- Output of `diff3 -x lao tzu tao':
- 11a
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
- .
-
-
-File: diff.info, Node: Marking Conflicts, Next: Bypassing ed, Prev: Which Changes, Up: diff3 Merging
-
-Marking Conflicts
-=================
-
- `diff3' can mark conflicts in the merged output by bracketing them
-with special marker lines. A conflict that comes from two files A and
-B is marked as follows:
-
- <<<<<<< A
- lines from A
- =======
- lines from B
- >>>>>>> B
-
- A conflict that comes from three files A, B and C is marked as
-follows:
-
- <<<<<<< A
- lines from A
- ||||||| B
- lines from B
- =======
- lines from C
- >>>>>>> C
-
- The `-A' or `--show-all' option acts like the `-e' option, except
-that it brackets conflicts, and it outputs all changes from OLDER to
-YOURS, not just the unmerged changes. Thus, given the sample input
-files (*note Sample diff3 Input::.), `diff3 -A lao tzu tao' puts
-brackets around the conflict where only `tzu' differs:
-
- <<<<<<< tzu
- =======
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
- >>>>>>> tao
-
- And it outputs the three-way conflict as follows:
-
- <<<<<<< lao
- ||||||| tzu
- They both may be called deep and profound.
- Deeper and more profound,
- The door of all subtleties!
- =======
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
- >>>>>>> tao
-
- The `-E' or `--show-overlap' option outputs less information than
-the `-A' or `--show-all' option, because it outputs only unmerged
-changes, and it never outputs the contents of the second file. Thus
-the `-E' option acts like the `-e' option, except that it brackets the
-first and third files from three-way overlapping changes. Similarly,
-`-X' acts like `-x', except it brackets all its (necessarily
-overlapping) changes. For example, for the three-way overlapping
-change above, the `-E' and `-X' options output the following:
-
- <<<<<<< lao
- =======
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
- >>>>>>> tao
-
- If you are comparing files that have meaningless or uninformative
-names, you can use the `-L LABEL' or `--label=LABEL' option to show
-alternate names in the `<<<<<<<', `|||||||' and `>>>>>>>' brackets.
-This option can be given up to three times, once for each input file.
-Thus `diff3 -A -L X -L Y -L Z A B C' acts like `diff3 -A A B C', except
-that the output looks like it came from files named `X', `Y' and `Z'
-rather than from files named `A', `B' and `C'.
-
-
-File: diff.info, Node: Bypassing ed, Next: Merging Incomplete Lines, Prev: Marking Conflicts, Up: diff3 Merging
-
-Generating the Merged Output Directly
-=====================================
-
- With the `-m' or `--merge' option, `diff3' outputs the merged file
-directly. This is more efficient than using `ed' to generate it, and
-works even with non-text files that `ed' would reject. If you specify
-`-m' without an `ed' script option, `-A' (`--show-all') is assumed.
-
- For example, the command `diff3 -m lao tzu tao' (*note Sample diff3
-Input::. for a copy of the input files) would output the following:
-
- <<<<<<< tzu
- =======
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
- >>>>>>> tao
- The Nameless is the origin of Heaven and Earth;
- The Named is the mother of all things.
- Therefore let there always be non-being,
- so we may see their subtlety,
- And let there always be being,
- so we may see their result.
- The two are the same,
- But after they are produced,
- they have different names.
- <<<<<<< lao
- ||||||| tzu
- They both may be called deep and profound.
- Deeper and more profound,
- The door of all subtleties!
- =======
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
- >>>>>>> tao
-
-
-File: diff.info, Node: Merging Incomplete Lines, Next: Saving the Changed File, Prev: Bypassing ed, Up: diff3 Merging
-
-How `diff3' Merges Incomplete Lines
-===================================
-
- With `-m', incomplete lines (*note Incomplete Lines::.) are simply
-copied to the output as they are found; if the merged output ends in an
-conflict and one of the input files ends in an incomplete line,
-succeeding `|||||||', `=======' or `>>>>>>>' brackets appear somewhere
-other than the start of a line because they are appended to the
-incomplete line.
-
- Without `-m', if an `ed' script option is specified and an
-incomplete line is found, `diff3' generates a warning and acts as if a
-newline had been present.
-
-
-File: diff.info, Node: Saving the Changed File, Prev: Merging Incomplete Lines, Up: diff3 Merging
-
-Saving the Changed File
-=======================
-
- Traditional Unix `diff3' generates an `ed' script without the
-trailing `w' and and `q' commands that save the changes. System V
-`diff3' generates these extra commands. GNU `diff3' normally behaves
-like traditional Unix `diff3', but with the `-i' option it behaves like
-System V `diff3' and appends the `w' and `q' commands.
-
- The `-i' option requires one of the `ed' script options `-AeExX3',
-and is incompatible with the merged output option `-m'.
-
-
-File: diff.info, Node: Interactive Merging, Next: Merging with patch, Prev: diff3 Merging, Up: Top
-
-Interactive Merging with `sdiff'
-********************************
-
- With `sdiff', you can merge two files interactively based on a
-side-by-side `-y' format comparison (*note Side by Side::.). Use `-o
-FILE' or `--output=FILE' to specify where to put the merged text.
-*Note Invoking sdiff::, for more details on the options to `sdiff'.
-
- Another way to merge files interactively is to use the Emacs Lisp
-package `emerge'. *Note emerge: (emacs)emerge, for more information.
-
-* Menu:
-
-* sdiff Option Summary::Summary of `sdiff' options.
-* Merge Commands:: Merging two files interactively.
-
-
-File: diff.info, Node: sdiff Option Summary, Next: Merge Commands, Up: Interactive Merging
-
-Specifying `diff' Options to `sdiff'
-====================================
-
- The following `sdiff' options have the same meaning as for `diff'.
-*Note diff Options::, for the use of these options.
-
- -a -b -d -i -t -v
- -B -H -I REGEXP
-
- --ignore-blank-lines --ignore-case
- --ignore-matching-lines=REGEXP --ignore-space-change
- --left-column --minimal --speed-large-files
- --suppress-common-lines --expand-tabs
- --text --version --width=COLUMNS
-
- For historical reasons, `sdiff' has alternate names for some
-options. The `-l' option is equivalent to the `--left-column' option,
-and similarly `-s' is equivalent to `--suppress-common-lines'. The
-meaning of the `sdiff' `-w' and `-W' options is interchanged from that
-of `diff': with `sdiff', `-w COLUMNS' is equivalent to
-`--width=COLUMNS', and `-W' is equivalent to `--ignore-all-space'.
-`sdiff' without the `-o' option is equivalent to `diff' with the `-y'
-or `--side-by-side' option (*note Side by Side::.).
-
-
-File: diff.info, Node: Merge Commands, Prev: sdiff Option Summary, Up: Interactive Merging
-
-Merge Commands
-==============
-
- Groups of common lines, with a blank gutter, are copied from the
-first file to the output. After each group of differing lines, `sdiff'
-prompts with `%' and pauses, waiting for one of the following commands.
-Follow each command with RET.
-
-`e'
- Discard both versions. Invoke a text editor on an empty temporary
- file, then copy the resulting file to the output.
-
-`eb'
- Concatenate the two versions, edit the result in a temporary file,
- then copy the edited result to the output.
-
-`el'
- Edit a copy of the left version, then copy the result to the
- output.
-
-`er'
- Edit a copy of the right version, then copy the result to the
- output.
-
-`l'
- Copy the left version to the output.
-
-`q'
- Quit.
-
-`r'
- Copy the right version to the output.
-
-`s'
- Silently copy common lines.
-
-`v'
- Verbosely copy common lines. This is the default.
-
- The text editor invoked is specified by the `EDITOR' environment
-variable if it is set. The default is system-dependent.
-
-
-File: diff.info, Node: Merging with patch, Next: Making Patches, Prev: Interactive Merging, Up: Top
-
-Merging with `patch'
-********************
-
- `patch' takes comparison output produced by `diff' and applies the
-differences to a copy of the original file, producing a patched
-version. With `patch', you can distribute just the changes to a set of
-files instead of distributing the entire file set; your correspondents
-can apply `patch' to update their copy of the files with your changes.
-`patch' automatically determines the diff format, skips any leading or
-trailing headers, and uses the headers to determine which file to
-patch. This lets your correspondents feed an article or message
-containing a difference listing directly to `patch'.
-
- `patch' detects and warns about common problems like forward
-patches. It saves the original version of the files it patches, and
-saves any patches that it could not apply. It can also maintain a
-`patchlevel.h' file to ensures that your correspondents apply diffs in
-the proper order.
-
- `patch' accepts a series of diffs in its standard input, usually
-separated by headers that specify which file to patch. It applies
-`diff' hunks (*note Hunks::.) one by one. If a hunk does not exactly
-match the original file, `patch' uses heuristics to try to patch the
-file as well as it can. If no approximate match can be found, `patch'
-rejects the hunk and skips to the next hunk. `patch' normally replaces
-each file F with its new version, saving the original file in `F.orig',
-and putting reject hunks (if any) into `F.rej'.
-
- *Note Invoking patch::, for detailed information on the options to
-`patch'. *Note Backups::, for more information on how `patch' names
-backup files. *Note Rejects::, for more information on where `patch'
-puts reject hunks.
-
-* Menu:
-
-* patch Input:: Selecting the type of `patch' input.
-* Imperfect:: Dealing with imperfect patches.
-* Empty Files:: Removing empty files after patching.
-* Multiple Patches:: Handling multiple patches in a file specially.
-* patch Messages:: Messages and questions `patch' can produce.
-
-
-File: diff.info, Node: patch Input, Next: Imperfect, Up: Merging with patch
-
-Selecting the `patch' Input Format
-==================================
-
- `patch' normally determines which `diff' format the patch file uses
-by examining its contents. For patch files that contain particularly
-confusing leading text, you might need to use one of the following
-options to force `patch' to interpret the patch file as a certain
-format of diff. The output formats listed here are the only ones that
-`patch' can understand.
-
-`-c'
-`--context'
- context diff.
-
-`-e'
-`--ed'
- `ed' script.
-
-`-n'
-`--normal'
- normal diff.
-
-`-u'
-`--unified'
- unified diff.
-
-
-File: diff.info, Node: Imperfect, Next: Empty Files, Prev: patch Input, Up: Merging with patch
-
-Applying Imperfect Patches
-==========================
-
- `patch' tries to skip any leading text in the patch file, apply the
-diff, and then skip any trailing text. Thus you can feed a news article
-or mail message directly to `patch', and it should work. If the entire
-diff is indented by a constant amount of white space, `patch'
-automatically ignores the indentation.
-
- However, certain other types of imperfect input require user
-intervention.
-
-* Menu:
-
-* Changed White Space:: When tabs and spaces don't match exactly.
-* Reversed Patches:: Applying reversed patches correctly.
-* Inexact:: Helping `patch' find close matches.
-
-
-File: diff.info, Node: Changed White Space, Next: Reversed Patches, Up: Imperfect
-
-Applying Patches with Changed White Space
------------------------------------------
-
- Sometimes mailers, editors, or other programs change spaces into
-tabs, or vice versa. If this happens to a patch file or an input file,
-the files might look the same, but `patch' will not be able to match
-them properly. If this problem occurs, use the `-l' or
-`--ignore-white-space' option, which makes `patch' compare white space
-loosely so that any sequence of white space in the patch file matches
-any sequence of white space in the input files. Non-white-space
-characters must still match exactly. Each line of the context must
-still match a line in the input file.
-
-
-File: diff.info, Node: Reversed Patches, Next: Inexact, Prev: Changed White Space, Up: Imperfect
-
-Applying Reversed Patches
--------------------------
-
- Sometimes people run `diff' with the new file first instead of
-second. This creates a diff that is "reversed". To apply such
-patches, give `patch' the `-R' or `--reverse' option. `patch' then
-attempts to swap each hunk around before applying it. Rejects come out
-in the swapped format. The `-R' option does not work with `ed' scripts
-because there is too little information in them to reconstruct the
-reverse operation.
-
- Often `patch' can guess that the patch is reversed. If the first
-hunk of a patch fails, `patch' reverses the hunk to see if it can apply
-it that way. If it can, `patch' asks you if you want to have the `-R'
-option set; if it can't, `patch' continues to apply the patch normally.
-This method cannot detect a reversed patch if it is a normal diff and
-the first command is an append (which should have been a delete) since
-appends always succeed, because a null context matches anywhere. But
-most patches add or change lines rather than delete them, so most
-reversed normal diffs begin with a delete, which fails, and `patch'
-notices.
-
- If you apply a patch that you have already applied, `patch' thinks
-it is a reversed patch and offers to un-apply the patch. This could be
-construed as a feature. If you did this inadvertently and you don't
-want to un-apply the patch, just answer `n' to this offer and to the
-subsequent "apply anyway" question--or type `C-c' to kill the `patch'
-process.
-
-
-File: diff.info, Node: Inexact, Prev: Reversed Patches, Up: Imperfect
-
-Helping `patch' Find Inexact Matches
-------------------------------------
-
- For context diffs, and to a lesser extent normal diffs, `patch' can
-detect when the line numbers mentioned in the patch are incorrect, and
-it attempts to find the correct place to apply each hunk of the patch.
-As a first guess, it takes the line number mentioned in the hunk, plus
-or minus any offset used in applying the previous hunk. If that is not
-the correct place, `patch' scans both forward and backward for a set of
-lines matching the context given in the hunk.
-
- First `patch' looks for a place where all lines of the context
-match. If it cannot find such a place, and it is reading a context or
-unified diff, and the maximum fuzz factor is set to 1 or more, then
-`patch' makes another scan, ignoring the first and last line of
-context. If that fails, and the maximum fuzz factor is set to 2 or
-more, it makes another scan, ignoring the first two and last two lines
-of context are ignored. It continues similarly if the maximum fuzz
-factor is larger.
-
- The `-F LINES' or `--fuzz=LINES' option sets the maximum fuzz factor
-to LINES. This option only applies to context and unified diffs; it
-ignores up to LINES lines while looking for the place to install a
-hunk. Note that a larger fuzz factor increases the odds of making a
-faulty patch. The default fuzz factor is 2; it may not be set to more
-than the number of lines of context in the diff, ordinarily 3.
-
- If `patch' cannot find a place to install a hunk of the patch, it
-writes the hunk out to a reject file (*note Rejects::., for information
-on how reject files are named). It writes out rejected hunks in context
-format no matter what form the input patch is in. If the input is a
-normal or `ed' diff, many of the contexts are simply null. The line
-numbers on the hunks in the reject file may be different from those in
-the patch file: they show the approximate location where `patch' thinks
-the failed hunks belong in the new file rather than in the old one.
-
- As it completes each hunk, `patch' tells you whether the hunk
-succeeded or failed, and if it failed, on which line (in the new file)
-`patch' thinks the hunk should go. If this is different from the line
-number specified in the diff, it tells you the offset. A single large
-offset *may* indicate that `patch' installed a hunk in the wrong place.
-`patch' also tells you if it used a fuzz factor to make the match, in
-which case you should also be slightly suspicious.
-
- `patch' cannot tell if the line numbers are off in an `ed' script,
-and can only detect wrong line numbers in a normal diff when it finds a
-change or delete command. It may have the same problem with a context
-diff using a fuzz factor equal to or greater than the number of lines
-of context shown in the diff (typically 3). In these cases, you should
-probably look at a context diff between your original and patched input
-files to see if the changes make sense. Compiling without errors is a
-pretty good indication that the patch worked, but not a guarantee.
-
- `patch' usually produces the correct results, even when it must make
-many guesses. However, the results are guaranteed only when the patch
-is applied to an exact copy of the file that the patch was generated
-from.
-
-
-File: diff.info, Node: Empty Files, Next: Multiple Patches, Prev: Imperfect, Up: Merging with patch
-
-Removing Empty Files
-====================
-
- Sometimes when comparing two directories, the first directory
-contains a file that the second directory does not. If you give `diff'
-the `-N' or `--new-file' option, it outputs a diff that deletes the
-contents of this file. By default, `patch' leaves an empty file after
-applying such a diff. The `-E' or `--remove-empty-files' option to
-`patch' deletes output files that are empty after applying the diff.
-
-
-File: diff.info, Node: Multiple Patches, Next: patch Messages, Prev: Empty Files, Up: Merging with patch
-
-Multiple Patches in a File
-==========================
-
- If the patch file contains more than one patch, `patch' tries to
-apply each of them as if they came from separate patch files. This
-means that it determines the name of the file to patch for each patch,
-and that it examines the leading text before each patch for file names
-and prerequisite revision level (*note Making Patches::., for more on
-that topic).
-
- For the second and subsequent patches in the patch file, you can give
-options and another original file name by separating their argument
-lists with a `+'. However, the argument list for a second or
-subsequent patch may not specify a new patch file, since that does not
-make sense.
-
- For example, to tell `patch' to strip the first three slashes from
-the name of the first patch in the patch file and none from subsequent
-patches, and to use `code.c' as the first input file, you can use:
-
- patch -p3 code.c + -p0 < patchfile
-
- The `-S' or `--skip' option ignores the current patch from the patch
-file, but continue looking for the next patch in the file. Thus, to
-ignore the first and third patches in the patch file, you can use:
-
- patch -S + + -S + < patch file
-
-
-File: diff.info, Node: patch Messages, Prev: Multiple Patches, Up: Merging with patch
-
-Messages and Questions from `patch'
-===================================
-
- `patch' can produce a variety of messages, especially if it has
-trouble decoding its input. In a few situations where it's not sure how
-to proceed, `patch' normally prompts you for more information from the
-keyboard. There are options to suppress printing non-fatal messages
-and stopping for keyboard input.
-
- The message `Hmm...' indicates that `patch' is reading text in the
-patch file, attempting to determine whether there is a patch in that
-text, and if so, what kind of patch it is.
-
- You can inhibit all terminal output from `patch', unless an error
-occurs, by using the `-s', `--quiet', or `--silent' option.
-
- There are two ways you can prevent `patch' from asking you any
-questions. The `-f' or `--force' option assumes that you know what you
-are doing. It assumes the following:
-
- * skip patches that do not contain file names in their headers;
-
- * patch files even though they have the wrong version for the
- `Prereq:' line in the patch;
-
- * assume that patches are not reversed even if they look like they
- are.
-
- The `-t' or `--batch' option is similar to `-f', in that it
-suppresses questions, but it makes somewhat different assumptions:
-
- * skip patches that do not contain file names in their headers (the
- same as `-f');
-
- * skip patches for which the file has the wrong version for the
- `Prereq:' line in the patch;
-
- * assume that patches are reversed if they look like they are.
-
- `patch' exits with a non-zero status if it creates any reject files.
-When applying a set of patches in a loop, you should check the exit
-status, so you don't apply a later patch to a partially patched file.
-