diff options
Diffstat (limited to 'gnu/dist/diffutils/diff.info-2')
| -rw-r--r-- | gnu/dist/diffutils/diff.info-2 | 1312 |
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. - |
