diff options
Diffstat (limited to 'gnu/dist/diffutils/diff.info-1')
| -rw-r--r-- | gnu/dist/diffutils/diff.info-1 | 1211 |
1 files changed, 0 insertions, 1211 deletions
diff --git a/gnu/dist/diffutils/diff.info-1 b/gnu/dist/diffutils/diff.info-1 deleted file mode 100644 index 477ac98399d..00000000000 --- a/gnu/dist/diffutils/diff.info-1 +++ /dev/null @@ -1,1211 +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: Top, Up: (dir) - - 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. - - This is Edition 1.2, for `diff' 2.4 and `patch' 2.1. - -* Menu: - -* Overview:: Preliminary information. - -* Comparison:: What file comparison means. -* Output Formats:: Formats for difference reports. -* Comparing Directories:: Comparing files and directories. -* Adjusting Output:: Making `diff' output prettier. -* diff Performance:: Making `diff' smarter or faster. -* Comparing Three Files:: Formats for three-way difference reports. - -* diff3 Merging:: Merging from a common ancestor. -* Interactive Merging:: Interactive merging with `sdiff'. -* Merging with patch:: Using `patch' to change old files into new ones. -* Making Patches:: Tips for making patch distributions. - -* Invoking cmp:: How to run `cmp' and a summary of its options. -* Invoking diff:: How to run `diff' and a summary of its options. -* Invoking diff3:: How to run `diff3' and a summary of its options. -* Invoking patch:: How to run `patch' and a summary of its options. -* Invoking sdiff:: How to run `sdiff' and a summary of its options. - -* Incomplete Lines:: Lines that lack trailing newlines. -* Projects:: If you think you've found a bug or other shortcoming. - -* Concept Index:: Index of concepts. - - -File: diff.info, Node: Overview, Next: Comparison, Up: Top - -Overview -******** - - Computer users often find occasion to ask how two files differ. -Perhaps one file is a newer version of the other file. Or maybe the -two files started out as identical copies but were changed by different -people. - - You can use the `diff' command to show differences between two -files, or each corresponding file in two directories. `diff' outputs -differences between files line by line in any of several formats, -selectable by command line options. This set of differences is often -called a "diff" or "patch". For files that are identical, `diff' -normally produces no output; for binary (non-text) files, `diff' -normally reports only that they are different. - - You can use the `cmp' command to show the offsets and line numbers -where two files differ. `cmp' can also show all the characters that -differ between the two files, side by side. Another way to compare two -files character by character is the Emacs command `M-x -compare-windows'. *Note Other Window: (emacs)Other Window, for more -information on that command. - - You can use the `diff3' command to show differences among three -files. When two people have made independent changes to a common -original, `diff3' can report the differences between the original and -the two changed versions, and can produce a merged file that contains -both persons' changes together with warnings about conflicts. - - You can use the `sdiff' command to merge two files interactively. - - You can use the set of differences produced by `diff' to distribute -updates to text files (such as program source code) to other people. -This method is especially useful when the differences are small compared -to the complete files. Given `diff' output, you can use the `patch' -program to update, or "patch", a copy of the file. If you think of -`diff' as subtracting one file from another to produce their -difference, you can think of `patch' as adding the difference to one -file to reproduce the other. - - This manual first concentrates on making diffs, and later shows how -to use diffs to update files. - - GNU `diff' was written by Mike Haertel, David Hayes, Richard -Stallman, Len Tower, and Paul Eggert. Wayne Davison designed and -implemented the unified output format. The basic algorithm is described -in "An O(ND) Difference Algorithm and its Variations", Eugene W. Myers, -`Algorithmica' Vol. 1 No. 2, 1986, pp. 251-266; and in "A File -Comparison Program", Webb Miller and Eugene W. Myers, -`Software--Practice and Experience' Vol. 15 No. 11, 1985, pp. 1025-1040. -The algorithm was independently discovered as described in "Algorithms -for Approximate String Matching", E. Ukkonen, `Information and Control' -Vol. 64, 1985, pp. 100-118. - - GNU `diff3' was written by Randy Smith. GNU `sdiff' was written by -Thomas Lord. GNU `cmp' was written by Torbjorn Granlund and David -MacKenzie. - - `patch' was written mainly by Larry Wall; the GNU enhancements were -written mainly by Wayne Davison and David MacKenzie. Parts of this -manual are adapted from a manual page written by Larry Wall, with his -permission. - - -File: diff.info, Node: Comparison, Next: Output Formats, Prev: Overview, Up: Top - -What Comparison Means -********************* - - There are several ways to think about the differences between two -files. One way to think of the differences is as a series of lines -that were deleted from, inserted in, or changed in one file to produce -the other file. `diff' compares two files line by line, finds groups of -lines that differ, and reports each group of differing lines. It can -report the differing lines in several formats, which have different -purposes. - - GNU `diff' can show whether files are different without detailing -the differences. It also provides ways to suppress certain kinds of -differences that are not important to you. Most commonly, such -differences are changes in the amount of white space between words or -lines. `diff' also provides ways to suppress differences in alphabetic -case or in lines that match a regular expression that you provide. -These options can accumulate; for example, you can ignore changes in -both white space and alphabetic case. - - Another way to think of the differences between two files is as a -sequence of pairs of characters that can be either identical or -different. `cmp' reports the differences between two files character -by character, instead of line by line. As a result, it is more useful -than `diff' for comparing binary files. For text files, `cmp' is -useful mainly when you want to know only whether two files are -identical. - - To illustrate the effect that considering changes character by -character can have compared with considering them line by line, think -of what happens if a single newline character is added to the beginning -of a file. If that file is then compared with an otherwise identical -file that lacks the newline at the beginning, `diff' will report that a -blank line has been added to the file, while `cmp' will report that -almost every character of the two files differs. - - `diff3' normally compares three input files line by line, finds -groups of lines that differ, and reports each group of differing lines. -Its output is designed to make it easy to inspect two different sets of -changes to the same file. - -* Menu: - -* Hunks:: Groups of differing lines. -* White Space:: Suppressing differences in white space. -* Blank Lines:: Suppressing differences in blank lines. -* Case Folding:: Suppressing differences in alphabetic case. -* Specified Folding:: Suppressing differences that match regular expressions. -* Brief:: Summarizing which files are different. -* Binary:: Comparing binary files or forcing text comparisons. - - -File: diff.info, Node: Hunks, Next: White Space, Up: Comparison - -Hunks -===== - - When comparing two files, `diff' finds sequences of lines common to -both files, interspersed with groups of differing lines called "hunks". -Comparing two identical files yields one sequence of common lines and -no hunks, because no lines differ. Comparing two entirely different -files yields no common lines and one large hunk that contains all lines -of both files. In general, there are many ways to match up lines -between two given files. `diff' tries to minimize the total hunk size -by finding large sequences of common lines interspersed with small -hunks of differing lines. - - For example, suppose the file `F' contains the three lines `a', `b', -`c', and the file `G' contains the same three lines in reverse order -`c', `b', `a'. If `diff' finds the line `c' as common, then the command -`diff F G' produces this output: - - 1,2d0 - < a - < b - 3a2,3 - > b - > a - -But if `diff' notices the common line `b' instead, it produces this -output: - - 1c1 - < a - --- - > c - 3c3 - < c - --- - > a - -It is also possible to find `a' as the common line. `diff' does not -always find an optimal matching between the files; it takes shortcuts -to run faster. But its output is usually close to the shortest -possible. You can adjust this tradeoff with the `--minimal' option -(*note diff Performance::.). - - -File: diff.info, Node: White Space, Next: Blank Lines, Prev: Hunks, Up: Comparison - -Suppressing Differences in Blank and Tab Spacing -================================================ - - The `-b' and `--ignore-space-change' options ignore white space at -line end, and considers all other sequences of one or more white space -characters to be equivalent. With these options, `diff' considers the -following two lines to be equivalent, where `$' denotes the line end: - - Here lyeth muche rychnesse in lytell space. -- John Heywood$ - Here lyeth muche rychnesse in lytell space. -- John Heywood $ - - The `-w' and `--ignore-all-space' options are stronger than `-b'. -They ignore difference even if one file has white space where the other -file has none. "White space" characters include tab, newline, vertical -tab, form feed, carriage return, and space; some locales may define -additional characters to be white space. With these options, `diff' -considers the following two lines to be equivalent, where `$' denotes -the line end and `^M' denotes a carriage return: - - Here lyeth muche rychnesse in lytell space.-- John Heywood$ - He relyeth much erychnes seinly tells pace. --John Heywood ^M$ - - -File: diff.info, Node: Blank Lines, Next: Case Folding, Prev: White Space, Up: Comparison - -Suppressing Differences in Blank Lines -====================================== - - The `-B' and `--ignore-blank-lines' options ignore insertions or -deletions of blank lines. These options normally affect only lines -that are completely empty; they do not affect lines that look empty but -contain space or tab characters. With these options, for example, a -file containing - 1. A point is that which has no part. - - 2. A line is breadthless length. - -- Euclid, The Elements, I - -is considered identical to a file containing - 1. A point is that which has no part. - 2. A line is breadthless length. - - - -- Euclid, The Elements, I - - -File: diff.info, Node: Case Folding, Next: Specified Folding, Prev: Blank Lines, Up: Comparison - -Suppressing Case Differences -============================ - - GNU `diff' can treat lowercase letters as equivalent to their -uppercase counterparts, so that, for example, it considers `Funky -Stuff', `funky STUFF', and `fUNKy stuFf' to all be the same. To -request this, use the `-i' or `--ignore-case' option. - - -File: diff.info, Node: Specified Folding, Next: Brief, Prev: Case Folding, Up: Comparison - -Suppressing Lines Matching a Regular Expression -=============================================== - - To ignore insertions and deletions of lines that match a regular -expression, use the `-I REGEXP' or `--ignore-matching-lines=REGEXP' -option. You should escape regular expressions that contain shell -metacharacters to prevent the shell from expanding them. For example, -`diff -I '^[0-9]'' ignores all changes to lines beginning with a digit. - - However, `-I' only ignores the insertion or deletion of lines that -contain the regular expression if every changed line in the hunk--every -insertion and every deletion--matches the regular expression. In other -words, for each nonignorable change, `diff' prints the complete set of -changes in its vicinity, including the ignorable ones. - - You can specify more than one regular expression for lines to ignore -by using more than one `-I' option. `diff' tries to match each line -against each regular expression, starting with the last one given. - - -File: diff.info, Node: Brief, Next: Binary, Prev: Specified Folding, Up: Comparison - -Summarizing Which Files Differ -============================== - - When you only want to find out whether files are different, and you -don't care what the differences are, you can use the summary output -format. In this format, instead of showing the differences between the -files, `diff' simply reports whether files differ. The `-q' and -`--brief' options select this output format. - - This format is especially useful when comparing the contents of two -directories. It is also much faster than doing the normal line by line -comparisons, because `diff' can stop analyzing the files as soon as it -knows that there are any differences. - - You can also get a brief indication of whether two files differ by -using `cmp'. For files that are identical, `cmp' produces no output. -When the files differ, by default, `cmp' outputs the byte offset and -line number where the first difference occurs. You can use the `-s' -option to suppress that information, so that `cmp' produces no output -and reports whether the files differ using only its exit status (*note -Invoking cmp::.). - - Unlike `diff', `cmp' cannot compare directories; it can only compare -two files. - - -File: diff.info, Node: Binary, Prev: Brief, Up: Comparison - -Binary Files and Forcing Text Comparisons -========================================= - - If `diff' thinks that either of the two files it is comparing is -binary (a non-text file), it normally treats that pair of files much as -if the summary output format had been selected (*note Brief::.), and -reports only that the binary files are different. This is because line -by line comparisons are usually not meaningful for binary files. - - `diff' determines whether a file is text or binary by checking the -first few bytes in the file; the exact number of bytes is system -dependent, but it is typically several thousand. If every character in -that part of the file is non-null, `diff' considers the file to be -text; otherwise it considers the file to be binary. - - Sometimes you might want to force `diff' to consider files to be -text. For example, you might be comparing text files that contain null -characters; `diff' would erroneously decide that those are non-text -files. Or you might be comparing documents that are in a format used -by a word processing system that uses null characters to indicate -special formatting. You can force `diff' to consider all files to be -text files, and compare them line by line, by using the `-a' or -`--text' option. If the files you compare using this option do not in -fact contain text, they will probably contain few newline characters, -and the `diff' output will consist of hunks showing differences between -long lines of whatever characters the files contain. - - You can also force `diff' to consider all files to be binary files, -and report only whether they differ (but not how). Use the `--brief' -option for this. - - In operating systems that distinguish between text and binary files, -`diff' normally reads and writes all data as text. Use the `--binary' -option to force `diff' to read and write binary data instead. This -option has no effect on a Posix-compliant system like GNU or -traditional Unix. However, many personal computer operating systems -represent the end of a line with a carriage return followed by a -newline. On such systems, `diff' normally ignores these carriage -returns on input and generates them at the end of each output line, but -with the `--binary' option `diff' treats each carriage return as just -another input character, and does not generate a carriage return at the -end of each output line. This can be useful when dealing with non-text -files that are meant to be interchanged with Posix-compliant systems. - - If you want to compare two files byte by byte, you can use the `cmp' -program with the `-l' option to show the values of each differing byte -in the two files. With GNU `cmp', you can also use the `-c' option to -show the ASCII representation of those bytes. *Note Invoking cmp::, -for more information. - - If `diff3' thinks that any of the files it is comparing is binary (a -non-text file), it normally reports an error, because such comparisons -are usually not useful. `diff3' uses the same test as `diff' to decide -whether a file is binary. As with `diff', if the input files contain a -few non-text characters but otherwise are like text files, you can -force `diff3' to consider all files to be text files and compare them -line by line by using the `-a' or `--text' options. - - -File: diff.info, Node: Output Formats, Next: Comparing Directories, Prev: Comparison, Up: Top - -`diff' Output Formats -********************* - - `diff' has several mutually exclusive options for output format. -The following sections describe each format, illustrating how `diff' -reports the differences between two sample input files. - -* Menu: - -* Sample diff Input:: Sample `diff' input files for examples. -* Normal:: Showing differences without surrounding text. -* Context:: Showing differences with the surrounding text. -* Side by Side:: Showing differences in two columns. -* Scripts:: Generating scripts for other programs. -* If-then-else:: Merging files with if-then-else. - - -File: diff.info, Node: Sample diff Input, Next: Normal, Up: Output Formats - -Two Sample Input Files -====================== - - Here are two sample files that we will use in numerous examples to -illustrate the output of `diff' and how various options can change it. - - This is the file `lao': - - The Way that can be told of is not the eternal Way; - The name that can be named is not the eternal name. - The Nameless is the origin of Heaven and Earth; - The Named is the mother of all things. - Therefore let there always be non-being, - so we may see their subtlety, - And let there always be being, - so we may see their outcome. - The two are the same, - But after they are produced, - they have different names. - - This is the file `tzu': - - The Nameless is the origin of Heaven and Earth; - The named is the mother of all things. - - Therefore let there always be non-being, - so we may see their subtlety, - And let there always be being, - so we may see their outcome. - The two are the same, - But after they are produced, - they have different names. - They both may be called deep and profound. - Deeper and more profound, - The door of all subtleties! - - In this example, the first hunk contains just the first two lines of -`lao', the second hunk contains the fourth line of `lao' opposing the -second and third lines of `tzu', and the last hunk contains just the -last three lines of `tzu'. - - -File: diff.info, Node: Normal, Next: Context, Prev: Sample diff Input, Up: Output Formats - -Showing Differences Without Context -=================================== - - The "normal" `diff' output format shows each hunk of differences -without any surrounding context. Sometimes such output is the clearest -way to see how lines have changed, without the clutter of nearby -unchanged lines (although you can get similar results with the context -or unified formats by using 0 lines of context). However, this format -is no longer widely used for sending out patches; for that purpose, the -context format (*note Context Format::.) and the unified format (*note -Unified Format::.) are superior. Normal format is the default for -compatibility with older versions of `diff' and the Posix standard. - -* Menu: - -* Detailed Normal:: A detailed description of normal output format. -* Example Normal:: Sample output in the normal format. - - -File: diff.info, Node: Detailed Normal, Next: Example Normal, Up: Normal - -Detailed Description of Normal Format -------------------------------------- - - The normal output format consists of one or more hunks of -differences; each hunk shows one area where the files differ. Normal -format hunks look like this: - - CHANGE-COMMAND - < FROM-FILE-LINE - < FROM-FILE-LINE... - --- - > TO-FILE-LINE - > TO-FILE-LINE... - - There are three types of change commands. Each consists of a line -number or comma-separated range of lines in the first file, a single -character indicating the kind of change to make, and a line number or -comma-separated range of lines in the second file. All line numbers are -the original line numbers in each file. The types of change commands -are: - -`LaR' - Add the lines in range R of the second file after line L of the - first file. For example, `8a12,15' means append lines 12-15 of - file 2 after line 8 of file 1; or, if changing file 2 into file 1, - delete lines 12-15 of file 2. - -`FcT' - Replace the lines in range F of the first file with lines in range - T of the second file. This is like a combined add and delete, but - more compact. For example, `5,7c8,10' means change lines 5-7 of - file 1 to read as lines 8-10 of file 2; or, if changing file 2 into - file 1, change lines 8-10 of file 2 to read as lines 5-7 of file 1. - -`RdL' - Delete the lines in range R from the first file; line L is where - they would have appeared in the second file had they not been - deleted. For example, `5,7d3' means delete lines 5-7 of file 1; - or, if changing file 2 into file 1, append lines 5-7 of file 1 - after line 3 of file 2. - - -File: diff.info, Node: Example Normal, Prev: Detailed Normal, Up: Normal - -An Example of Normal Format ---------------------------- - - Here is the output of the command `diff lao tzu' (*note Sample diff -Input::., for the complete contents of the two files). Notice that it -shows only the lines that are different between the two files. - - 1,2d0 - < The Way that can be told of is not the eternal Way; - < The name that can be named is not the eternal name. - 4c2,3 - < The Named is the mother of all things. - --- - > The named is the mother of all things. - > - 11a11,13 - > They both may be called deep and profound. - > Deeper and more profound, - > The door of all subtleties! - - -File: diff.info, Node: Context, Next: Side by Side, Prev: Normal, Up: Output Formats - -Showing Differences in Their Context -==================================== - - Usually, when you are looking at the differences between files, you -will also want to see the parts of the files near the lines that -differ, to help you understand exactly what has changed. These nearby -parts of the files are called the "context". - - GNU `diff' provides two output formats that show context around the -differing lines: "context format" and "unified format". It can -optionally show in which function or section of the file the differing -lines are found. - - If you are distributing new versions of files to other people in the -form of `diff' output, you should use one of the output formats that -show context so that they can apply the diffs even if they have made -small changes of their own to the files. `patch' can apply the diffs -in this case by searching in the files for the lines of context around -the differing lines; if those lines are actually a few lines away from -where the diff says they are, `patch' can adjust the line numbers -accordingly and still apply the diff correctly. *Note Imperfect::, for -more information on using `patch' to apply imperfect diffs. - -* Menu: - -* Context Format:: An output format that shows surrounding lines. -* Unified Format:: A more compact output format that shows context. -* Sections:: Showing which sections of the files differences are in. -* Alternate Names:: Showing alternate file names in context headers. - - -File: diff.info, Node: Context Format, Next: Unified Format, Up: Context - -Context Format --------------- - - The context output format shows several lines of context around the -lines that differ. It is the standard format for distributing updates -to source code. - - To select this output format, use the `-C LINES', -`--context[=LINES]', or `-c' option. The argument LINES that some of -these options take is the number of lines of context to show. If you -do not specify LINES, it defaults to three. For proper operation, -`patch' typically needs at least two lines of context. - -* Menu: - -* Detailed Context:: A detailed description of the context output format. -* Example Context:: Sample output in context format. -* Less Context:: Another sample with less context. - - -File: diff.info, Node: Detailed Context, Next: Example Context, Up: Context Format - -Detailed Description of Context Format -...................................... - - The context output format starts with a two-line header, which looks -like this: - - *** FROM-FILE FROM-FILE-MODIFICATION-TIME - --- TO-FILE TO-FILE-MODIFICATION TIME - -You can change the header's content with the `-L LABEL' or -`--label=LABEL' option; see *Note Alternate Names::. - - Next come one or more hunks of differences; each hunk shows one area -where the files differ. Context format hunks look like this: - - *************** - *** FROM-FILE-LINE-RANGE **** - FROM-FILE-LINE - FROM-FILE-LINE... - --- TO-FILE-LINE-RANGE ---- - TO-FILE-LINE - TO-FILE-LINE... - - The lines of context around the lines that differ start with two -space characters. The lines that differ between the two files start -with one of the following indicator characters, followed by a space -character: - -`!' - A line that is part of a group of one or more lines that changed - between the two files. There is a corresponding group of lines - marked with `!' in the part of this hunk for the other file. - -`+' - An "inserted" line in the second file that corresponds to nothing - in the first file. - -`-' - A "deleted" line in the first file that corresponds to nothing in - the second file. - - If all of the changes in a hunk are insertions, the lines of -FROM-FILE are omitted. If all of the changes are deletions, the lines -of TO-FILE are omitted. - - -File: diff.info, Node: Example Context, Next: Less Context, Prev: Detailed Context, Up: Context Format - -An Example of Context Format -............................ - - Here is the output of `diff -c lao tzu' (*note Sample diff Input::., -for the complete contents of the two files). Notice that up to three -lines that are not different are shown around each line that is -different; they are the context lines. Also notice that the first two -hunks have run together, because their contents overlap. - - *** lao Sat Jan 26 23:30:39 1991 - --- tzu Sat Jan 26 23:30:50 1991 - *************** - *** 1,7 **** - - 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, - --- 1,6 ---- - 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, - *************** - *** 9,11 **** - --- 8,13 ---- - The two are the same, - But after they are produced, - they have different names. - + They both may be called deep and profound. - + Deeper and more profound, - + The door of all subtleties! - - -File: diff.info, Node: Less Context, Prev: Example Context, Up: Context Format - -An Example of Context Format with Less Context -.............................................. - - Here is the output of `diff --context=1 lao tzu' (*note Sample diff -Input::., for the complete contents of the two files). Notice that at -most one context line is reported here. - - *** lao Sat Jan 26 23:30:39 1991 - --- tzu Sat Jan 26 23:30:50 1991 - *************** - *** 1,5 **** - - 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, - --- 1,4 ---- - The Nameless is the origin of Heaven and Earth; - ! The named is the mother of all things. - ! - Therefore let there always be non-being, - *************** - *** 11 **** - --- 10,13 ---- - they have different names. - + They both may be called deep and profound. - + Deeper and more profound, - + The door of all subtleties! - - -File: diff.info, Node: Unified Format, Next: Sections, Prev: Context Format, Up: Context - -Unified Format --------------- - - The unified output format is a variation on the context format that -is more compact because it omits redundant context lines. To select -this output format, use the `-U LINES', `--unified[=LINES]', or `-u' -option. The argument LINES is the number of lines of context to show. -When it is not given, it defaults to three. - - At present, only GNU `diff' can produce this format and only GNU -`patch' can automatically apply diffs in this format. For proper -operation, `patch' typically needs at least two lines of context. - -* Menu: - -* Detailed Unified:: A detailed description of unified format. -* Example Unified:: Sample output in unified format. - - -File: diff.info, Node: Detailed Unified, Next: Example Unified, Up: Unified Format - -Detailed Description of Unified Format -...................................... - - The unified output format starts with a two-line header, which looks -like this: - - --- FROM-FILE FROM-FILE-MODIFICATION-TIME - +++ TO-FILE TO-FILE-MODIFICATION-TIME - -You can change the header's content with the `-L LABEL' or -`--label=LABEL' option; see *Note Alternate Names::. - - Next come one or more hunks of differences; each hunk shows one area -where the files differ. Unified format hunks look like this: - - @@ FROM-FILE-RANGE TO-FILE-RANGE @@ - LINE-FROM-EITHER-FILE - LINE-FROM-EITHER-FILE... - - The lines common to both files begin with a space character. The -lines that actually differ between the two files have one of the -following indicator characters in the left column: - -`+' - A line was added here to the first file. - -`-' - A line was removed here from the first file. - - -File: diff.info, Node: Example Unified, Prev: Detailed Unified, Up: Unified Format - -An Example of Unified Format -............................ - - Here is the output of the command `diff -u lao tzu' (*note Sample -diff Input::., for the complete contents of the two files): - - --- lao Sat Jan 26 23:30:39 1991 - +++ tzu Sat Jan 26 23:30:50 1991 - @@ -1,7 +1,6 @@ - -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. - +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, - @@ -9,3 +8,6 @@ - The two are the same, - But after they are produced, - they have different names. - +They both may be called deep and profound. - +Deeper and more profound, - +The door of all subtleties! - - -File: diff.info, Node: Sections, Next: Alternate Names, Prev: Unified Format, Up: Context - -Showing Which Sections Differences Are in ------------------------------------------ - - Sometimes you might want to know which part of the files each change -falls in. If the files are source code, this could mean which function -was changed. If the files are documents, it could mean which chapter or -appendix was changed. GNU `diff' can show this by displaying the -nearest section heading line that precedes the differing lines. Which -lines are "section headings" is determined by a regular expression. - -* Menu: - -* Specified Headings:: Showing headings that match regular expressions. -* C Function Headings:: Showing headings of C functions. - - -File: diff.info, Node: Specified Headings, Next: C Function Headings, Up: Sections - -Showing Lines That Match Regular Expressions -............................................ - - To show in which sections differences occur for files that are not -source code for C or similar languages, use the `-F REGEXP' or -`--show-function-line=REGEXP' option. `diff' considers lines that -match the argument REGEXP to be the beginning of a section of the file. -Here are suggested regular expressions for some common languages: - -`^[A-Za-z_]' - C, C++, Prolog - -`^(' - Lisp - -`^@\(chapter\|appendix\|unnumbered\|chapheading\)' - Texinfo - - This option does not automatically select an output format; in order -to use it, you must select the context format (*note Context Format::.) -or unified format (*note Unified Format::.). In other output formats it -has no effect. - - The `-F' and `--show-function-line' options find the nearest -unchanged line that precedes each hunk of differences and matches the -given regular expression. Then they add that line to the end of the -line of asterisks in the context format, or to the `@@' line in unified -format. If no matching line exists, they leave the output for that -hunk unchanged. If that line is more than 40 characters long, they -output only the first 40 characters. You can specify more than one -regular expression for such lines; `diff' tries to match each line -against each regular expression, starting with the last one given. This -means that you can use `-p' and `-F' together, if you wish. - - -File: diff.info, Node: C Function Headings, Prev: Specified Headings, Up: Sections - -Showing C Function Headings -........................... - - To show in which functions differences occur for C and similar -languages, you can use the `-p' or `--show-c-function' option. This -option automatically defaults to the context output format (*note -Context Format::.), with the default number of lines of context. You -can override that number with `-C LINES' elsewhere in the command line. -You can override both the format and the number with `-U LINES' -elsewhere in the command line. - - The `-p' and `--show-c-function' options are equivalent to -`-F'^[_a-zA-Z$]'' if the unified format is specified, otherwise `-c --F'^[_a-zA-Z$]'' (*note Specified Headings::.). GNU `diff' provides -them for the sake of convenience. - - -File: diff.info, Node: Alternate Names, Prev: Sections, Up: Context - -Showing Alternate File Names ----------------------------- - - If you are comparing two files that have meaningless or uninformative -names, you might want `diff' to show alternate names in the header of -the context and unified output formats. To do this, use the `-L LABEL' -or `--label=LABEL' option. The first time you give this option, its -argument replaces the name and date of the first file in the header; -the second time, its argument replaces the name and date of the second -file. If you give this option more than twice, `diff' reports an -error. The `-L' option does not affect the file names in the `pr' -header when the `-l' or `--paginate' option is used (*note -Pagination::.). - - Here are the first two lines of the output from `diff -C2 -Loriginal --Lmodified lao tzu': - - *** original - --- modified - - -File: diff.info, Node: Side by Side, Next: Scripts, Prev: Context, Up: Output Formats - -Showing Differences Side by Side -================================ - - `diff' can produce a side by side difference listing of two files. -The files are listed in two columns with a gutter between them. The -gutter contains one of the following markers: - -white space - The corresponding lines are in common. That is, either the lines - are identical, or the difference is ignored because of one of the - `--ignore' options (*note White Space::.). - -`|' - The corresponding lines differ, and they are either both complete - or both incomplete. - -`<' - The files differ and only the first file contains the line. - -`>' - The files differ and only the second file contains the line. - -`(' - Only the first file contains the line, but the difference is - ignored. - -`)' - Only the second file contains the line, but the difference is - ignored. - -`\' - The corresponding lines differ, and only the first line is - incomplete. - -`/' - The corresponding lines differ, and only the second line is - incomplete. - - Normally, an output line is incomplete if and only if the lines that -it contains are incomplete; *Note Incomplete Lines::. However, when an -output line represents two differing lines, one might be incomplete -while the other is not. In this case, the output line is complete, but -its the gutter is marked `\' if the first line is incomplete, `/' if -the second line is. - - Side by side format is sometimes easiest to read, but it has -limitations. It generates much wider output than usual, and truncates -lines that are too long to fit. Also, it relies on lining up output -more heavily than usual, so its output looks particularly bad if you -use varying width fonts, nonstandard tab stops, or nonprinting -characters. - - You can use the `sdiff' command to interactively merge side by side -differences. *Note Interactive Merging::, for more information on -merging files. - -* Menu: - -* Side by Side Format:: Controlling side by side output format. -* Example Side by Side:: Sample side by side output. - - -File: diff.info, Node: Side by Side Format, Next: Example Side by Side, Up: Side by Side - -Controlling Side by Side Format -=============================== - - The `-y' or `--side-by-side' option selects side by side format. -Because side by side output lines contain two input lines, they are -wider than usual. They are normally 130 columns, which can fit onto a -traditional printer line. You can set the length of output lines with -the `-W COLUMNS' or `--width=COLUMNS' option. The output line is split -into two halves of equal length, separated by a small gutter to mark -differences; the right half is aligned to a tab stop so that tabs line -up. Input lines that are too long to fit in half of an output line are -truncated for output. - - The `--left-column' option prints only the left column of two common -lines. The `--suppress-common-lines' option suppresses common lines -entirely. - - -File: diff.info, Node: Example Side by Side, Prev: Side by Side Format, Up: Side by Side - -An Example of Side by Side Format ---------------------------------- - - Here is the output of the command `diff -y -W 72 lao tzu' (*note -Sample diff Input::., for the complete contents of the two files). - - The Way that can be told of is n < - The name that can be named is no < - The Nameless is the origin of He The Nameless is the origin of He - The Named is the mother of all t | The named is the mother of all t - > - Therefore let there always be no Therefore let there always be no - so we may see their subtlety, so we may see their subtlety, - And let there always be being, And let there always be being, - so we may see their outcome. so we may see their outcome. - The two are the same, The two are the same, - But after they are produced, But after they are produced, - they have different names. they have different names. - > They both may be called deep and - > Deeper and more profound, - > The door of all subtleties! - - -File: diff.info, Node: Scripts, Next: If-then-else, Prev: Side by Side, Up: Output Formats - -Making Edit Scripts -=================== - - Several output modes produce command scripts for editing FROM-FILE -to produce TO-FILE. - -* Menu: - -* ed Scripts:: Using `diff' to produce commands for `ed'. -* Forward ed:: Making forward `ed' scripts. -* RCS:: A special `diff' output format used by RCS. - - -File: diff.info, Node: ed Scripts, Next: Forward ed, Up: Scripts - -`ed' Scripts ------------- - - `diff' can produce commands that direct the `ed' text editor to -change the first file into the second file. Long ago, this was the -only output mode that was suitable for editing one file into another -automatically; today, with `patch', it is almost obsolete. Use the -`-e' or `--ed' option to select this output format. - - Like the normal format (*note Normal::.), this output format does not -show any context; unlike the normal format, it does not include the -information necessary to apply the diff in reverse (to produce the first -file if all you have is the second file and the diff). - - If the file `d' contains the output of `diff -e old new', then the -command `(cat d && echo w) | ed - old' edits `old' to make it a copy of -`new'. More generally, if `d1', `d2', ..., `dN' contain the outputs of -`diff -e old new1', `diff -e new1 new2', ..., `diff -e newN-1 newN', -respectively, then the command `(cat d1 d2 ... dN && echo w) | ed - -old' edits `old' to make it a copy of `newN'. - -* Menu: - -* Detailed ed:: A detailed description of `ed' format. -* Example ed:: A sample `ed' script. - - -File: diff.info, Node: Detailed ed, Next: Example ed, Up: ed Scripts - -Detailed Description of `ed' Format -................................... - - The `ed' output format consists of one or more hunks of differences. -The changes closest to the ends of the files come first so that -commands that change the number of lines do not affect how `ed' -interprets line numbers in succeeding commands. `ed' format hunks look -like this: - - CHANGE-COMMAND - TO-FILE-LINE - TO-FILE-LINE... - . - - Because `ed' uses a single period on a line to indicate the end of -input, GNU `diff' protects lines of changes that contain a single -period on a line by writing two periods instead, then writing a -subsequent `ed' command to change the two periods into one. The `ed' -format cannot represent an incomplete line, so if the second file ends -in a changed incomplete line, `diff' reports an error and then pretends -that a newline was appended. - - There are three types of change commands. Each consists of a line -number or comma-separated range of lines in the first file and a single -character indicating the kind of change to make. All line numbers are -the original line numbers in the file. The types of change commands -are: - -`La' - Add text from the second file after line L in the first file. For - example, `8a' means to add the following lines after line 8 of file - 1. - -`Rc' - Replace the lines in range R in the first file with the following - lines. Like a combined add and delete, but more compact. For - example, `5,7c' means change lines 5-7 of file 1 to read as the - text file 2. - -`Rd' - Delete the lines in range R from the first file. For example, - `5,7d' means delete lines 5-7 of file 1. - - -File: diff.info, Node: Example ed, Prev: Detailed ed, Up: ed Scripts - -Example `ed' Script -................... - - Here is the output of `diff -e lao tzu' (*note Sample diff Input::., -for the complete contents of the two files): - - 11a - They both may be called deep and profound. - Deeper and more profound, - The door of all subtleties! - . - 4c - The named is the mother of all things. - - . - 1,2d - - -File: diff.info, Node: Forward ed, Next: RCS, Prev: ed Scripts, Up: Scripts - -Forward `ed' Scripts --------------------- - - `diff' can produce output that is like an `ed' script, but with -hunks in forward (front to back) order. The format of the commands is -also changed slightly: command characters precede the lines they -modify, spaces separate line numbers in ranges, and no attempt is made -to disambiguate hunk lines consisting of a single period. Like `ed' -format, forward `ed' format cannot represent incomplete lines. - - Forward `ed' format is not very useful, because neither `ed' nor -`patch' can apply diffs in this format. It exists mainly for -compatibility with older versions of `diff'. Use the `-f' or -`--forward-ed' option to select it. - - -File: diff.info, Node: RCS, Prev: Forward ed, Up: Scripts - -RCS Scripts ------------ - - The RCS output format is designed specifically for use by the -Revision Control System, which is a set of free programs used for -organizing different versions and systems of files. Use the `-n' or -`--rcs' option to select this output format. It is like the forward -`ed' format (*note Forward ed::.), but it can represent arbitrary -changes to the contents of a file because it avoids the forward `ed' -format's problems with lines consisting of a single period and with -incomplete lines. Instead of ending text sections with a line -consisting of a single period, each command specifies the number of -lines it affects; a combination of the `a' and `d' commands are used -instead of `c'. Also, if the second file ends in a changed incomplete -line, then the output also ends in an incomplete line. - - Here is the output of `diff -n lao tzu' (*note Sample diff Input::., -for the complete contents of the two files): - - d1 2 - d4 1 - a4 2 - The named is the mother of all things. - - a11 3 - They both may be called deep and profound. - Deeper and more profound, - The door of all subtleties! - - -File: diff.info, Node: If-then-else, Prev: Scripts, Up: Output Formats - -Merging Files with If-then-else -=============================== - - You can use `diff' to merge two files of C source code. The output -of `diff' in this format contains all the lines of both files. Lines -common to both files are output just once; the differing parts are -separated by the C preprocessor directives `#ifdef NAME' or `#ifndef -NAME', `#else', and `#endif'. When compiling the output, you select -which version to use by either defining or leaving undefined the macro -NAME. - - To merge two files, use `diff' with the `-D NAME' or `--ifdef=NAME' -option. The argument NAME is the C preprocessor identifier to use in -the `#ifdef' and `#ifndef' directives. - - For example, if you change an instance of `wait (&s)' to `waitpid -(-1, &s, 0)' and then merge the old and new files with the -`--ifdef=HAVE_WAITPID' option, then the affected part of your code -might look like this: - - do { - #ifndef HAVE_WAITPID - if ((w = wait (&s)) < 0 && errno != EINTR) - #else /* HAVE_WAITPID */ - if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR) - #endif /* HAVE_WAITPID */ - return w; - } while (w != child); - - You can specify formats for languages other than C by using line -group formats and line formats, as described in the next sections. - -* Menu: - -* Line Group Formats:: Formats for general if-then-else line groups. -* Line Formats:: Formats for each line in a line group. -* Detailed If-then-else:: A detailed description of if-then-else format. -* Example If-then-else:: Sample if-then-else format output. - |
