Author: bapt Date: Mon Mar 2 11:48:00 2015 New Revision: 279519 URL: https://svnweb.freebsd.org/changeset/base/279519
Log: Convert texinfo to mdoc(7) using texi2mdoc Added: head/contrib/diff/doc/diff.7 (contents, props changed) head/contrib/gperf/doc/gperf.7 (contents, props changed) Added: head/contrib/diff/doc/diff.7 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/contrib/diff/doc/diff.7 Mon Mar 2 11:48:00 2015 (r279519) @@ -0,0 +1,6287 @@ +.Dd 2015-03-02 +.Dt DIFF 7 +.Os +.Sh NAME +.Nm diff +.Nd Comparing and Merging Files +.Sh Comparing and Merging Files +.Sh 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. +.Pp +You can use the +.Xr diff +command to show differences between two files, or each corresponding file +in two directories. +.Xr 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 +.Em diff +or +.Em patch . +For files that are identical, +.Xr diff +normally produces no output; for binary (non-text) files, +.Xr diff +normally reports only that they are different. +.Pp +You can use the +.Xr cmp +command to show the byte and line numbers where two files differ. +.Xr cmp +can also show all the bytes that differ between the two files, side by side. +A way to compare two files character by character is the Emacs command +.Li M-x compare-windows . +See Section.Dq Other Window , +for more information on that command. +.Pp +You can use the +.Xr diff3 +command to show differences among three files. When two people have made independent +changes to a common original, +.Xr 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. +.Pp +You can use the +.Xr sdiff +command to merge two files interactively. +.Pp +You can use the set of differences produced by +.Xr 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 +.Xr diff +output, you can use the +.Xr patch +program to update, or +.Em patch , +a copy of the file. If you think of +.Xr diff +as subtracting one file from another to produce their difference, you can +think of +.Xr patch +as adding the difference to one file to reproduce the other. +.Pp +This manual first concentrates on making diffs, and later shows how to use +diffs to update files. +.Pp +GNU +.Xr diff +was written by Paul Eggert, Mike Haertel, David Hayes, Richard Stallman, and +Len Tower. Wayne Davison designed and implemented the unified output format. +The basic algorithm is described by Eugene W. Myers in \(lqAn O(ND) Difference +Algorithm and its Variations\(rq, +.Em Algorithmica +Vol. 1 No. 2, 1986, pp. 251--266; and in \(lqA File Comparison Program\(rq, Webb Miller +and Eugene W. Myers, +.Em Software---Practice and Experience +Vol. 15 No. 11, 1985, pp. 1025--1040. The algorithm was independently discovered +as described by E. Ukkonen in \(lqAlgorithms for Approximate String Matching\(rq, +.Em Information and Control +Vol. 64, 1985, pp. 100--118. Unless the +.Op --minimal +option is used, +.Xr diff +uses a heuristic by Paul Eggert that limits the cost to O(N^1.5 log N) at +the price of producing suboptimal output for large inputs with many differences. +Related algorithms are surveyed by Alfred V. Aho in section 6.3 of \(lqAlgorithms +for Finding Patterns in Strings\(rq, +.Em Handbook of Theoretical Computer Science +(Jan Van Leeuwen, ed.), Vol. A, +.Em Algorithms and Complexity , +Elsevier/MIT Press, 1990, pp. 255--300. +.Pp +GNU +.Xr diff3 +was written by Randy Smith. GNU +.Xr sdiff +was written by Thomas Lord. GNU +.Xr cmp +was written by Torbj\(:orn Granlund and David MacKenzie. +.Pp +GNU +.Xr patch +was written mainly by Larry Wall and Paul Eggert; several GNU enhancements +were contributed by Wayne Davison and David MacKenzie. Parts of this manual +are adapted from a manual page written by Larry Wall, with his permission. +.Pp +.Sh 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. +.Xr 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. +.Pp +GNU +.Xr 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. +.Xr 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. +.Pp +Another way to think of the differences between two files is as a sequence +of pairs of bytes that can be either identical or different. +.Xr cmp +reports the differences between two files byte by byte, instead of line by +line. As a result, it is often more useful than +.Xr diff +for comparing binary files. For text files, +.Xr cmp +is useful mainly when you want to know only whether two files are identical, +or whether one file is a prefix of the other. +.Pp +To illustrate the effect that considering changes byte by byte 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, +.Xr diff +will report that a blank line has been added to the file, while +.Xr cmp +will report that almost every byte of the two files differs. +.Pp +.Xr 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. +.Pp +.Ss Hunks +When comparing two files, +.Xr diff +finds sequences of lines common to both files, interspersed with groups of +differing lines called +.Em 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. +.Xr diff +tries to minimize the total hunk size by finding large sequences of common +lines interspersed with small hunks of differing lines. +.Pp +For example, suppose the file +.Pa F +contains the three lines +.Li a , +.Li b , +.Li c , +and the file +.Pa G +contains the same three lines in reverse order +.Li c , +.Li b , +.Li a . +If +.Xr diff +finds the line +.Li c +as common, then the command +.Li diff F G +produces this output: +.Pp +.Bd -literal -offset indent +1,2d0 +< a +< b +3a2,3 +> b +> a +.Ed +.Pp +But if +.Xr diff +notices the common line +.Li b +instead, it produces this output: +.Pp +.Bd -literal -offset indent +1c1 +< a +--- +> c +3c3 +< c +--- +> a +.Ed +.Pp +It is also possible to find +.Li a +as the common line. +.Xr 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 +.Op -d +or +.Op --minimal +option (see Section +.Dq diff Performance ) . +.Pp +.Ss Suppressing Differences in Blank and Tab Spacing +The +.Op -E +or +.Op --ignore-tab-expansion +option ignores the distinction between tabs and spaces on input. A tab is +considered to be equivalent to the number of spaces to the next tab stop (see Section +.Dq Tabs ) . +.Pp +The +.Op -b +or +.Op --ignore-space-change +option is stronger. It ignores white space at line end, and considers all +other sequences of one or more white space characters within a line to be +equivalent. With this option, +.Xr diff +considers the following two lines to be equivalent, where +.Li $ +denotes the line end: +.Pp +.Bd -literal -offset indent +Here lyeth muche rychnesse in lytell space. -- John Heywood$ +Here lyeth muche rychnesse in lytell space. -- John Heywood $ +.Ed +.Pp +The +.Op -w +or +.Op --ignore-all-space +option is stronger still. It ignores differences even if one line has white +space where the other line has none. +.Em 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 this option, +.Xr diff +considers the following two lines to be equivalent, where +.Li $ +denotes the line end and +.Li ^M +denotes a carriage return: +.Pp +.Bd -literal -offset indent +Here lyeth muche rychnesse in lytell space.-- John Heywood$ + He relyeth much erychnes seinly tells pace. --John Heywood ^M$ +.Ed +.Pp +.Ss Suppressing Differences Whose Lines Are All Blank +The +.Op -B +or +.Op --ignore-blank-lines +option ignores changes that consist entirely of blank lines. With this option, +for example, a file containing +.Bd -literal -offset indent +1. A point is that which has no part. + +2. A line is breadthless length. +-- Euclid, The Elements, I +.Ed +is considered identical to a file containing +.Bd -literal -offset indent +1. A point is that which has no part. +2. A line is breadthless length. + + +-- Euclid, The Elements, I +.Ed +.Pp +Normally this option affects only lines that are completely empty, but if +you also specify the +.Op -b +or +.Op --ignore-space-change +option, or the +.Op -w +or +.Op --ignore-all-space +option, lines are also affected if they look empty but contain white space. +In other words, +.Op -B +is equivalent to +.Li -I '^$' +by default, but it is equivalent to +.Op -I '^[[:space:]]*$' +if +.Op -b +or +.Op -w +is also specified. +.Pp +.Ss Suppressing Differences Whose Lines All Match a Regular Expression +To ignore insertions and deletions of lines that match a +.Xr grep +-style regular expression, use the +.Op -I Va regexp +or +.Op --ignore-matching-lines= Va regexp +option. You should escape regular expressions that contain shell metacharacters +to prevent the shell from expanding them. For example, +.Li diff -I '^[[:digit:]]' +ignores all changes to lines beginning with a digit. +.Pp +However, +.Op -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, +.Xr diff +prints the complete set of changes in its vicinity, including the ignorable +ones. +.Pp +You can specify more than one regular expression for lines to ignore by using +more than one +.Op -I +option. +.Xr diff +tries to match each line against each regular expression. +.Pp +.Ss Suppressing Case Differences +GNU +.Xr diff +can treat lower case letters as equivalent to their upper case counterparts, +so that, for example, it considers +.Li Funky Stuff , +.Li funky STUFF , +and +.Li fUNKy stuFf +to all be the same. To request this, use the +.Op -i +or +.Op --ignore-case +option. +.Pp +.Ss 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, +.Xr diff +simply reports whether files differ. The +.Op -q +or +.Op --brief +option selects this output format. +.Pp +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 +.Xr diff +can stop analyzing the files as soon as it knows that there are any differences. +.Pp +You can also get a brief indication of whether two files differ by using +.Xr cmp . +For files that are identical, +.Xr cmp +produces no output. When the files differ, by default, +.Xr cmp +outputs the byte and line number where the first difference occurs, or reports +that one file is a prefix of the other. You can use the +.Op -s , +.Op --quiet , +or +.Op --silent +option to suppress that information, so that +.Xr cmp +produces no output and reports whether the files differ using only its exit +status (see Section +.Dq Invoking cmp ) . +.Pp +Unlike +.Xr diff , +.Xr cmp +cannot compare directories; it can only compare two files. +.Pp +.Ss Binary Files and Forcing Text Comparisons +If +.Xr 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 (see Section +.Dq Brief ) , +and reports only that the binary files are different. This is because line +by line comparisons are usually not meaningful for binary files. +.Pp +.Xr 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 byte in that part of the file is non-null, +.Xr diff +considers the file to be text; otherwise it considers the file to be binary. +.Pp +Sometimes you might want to force +.Xr diff +to consider files to be text. For example, you might be comparing text files +that contain null characters; +.Xr 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 +.Xr diff +to consider all files to be text files, and compare them line by line, by +using the +.Op -a +or +.Op --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 +.Xr diff +output will consist of hunks showing differences between long lines of whatever +characters the files contain. +.Pp +You can also force +.Xr diff +to report only whether files differ (but not how). Use the +.Op -q +or +.Op --brief +option for this. +.Pp +Normally, differing binary files count as trouble because the resulting +.Xr diff +output does not capture all the differences. This trouble causes +.Xr diff +to exit with status 2. However, this trouble cannot occur with the +.Op -a +or +.Op --text +option, or with the +.Op -q +or +.Op --brief +option, as these options both cause +.Xr diff +to generate a form of output that represents differences as requested. +.Pp +In operating systems that distinguish between text and binary files, +.Xr diff +normally reads and writes all data as text. Use the +.Op --binary +option to force +.Xr 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, +.Xr diff +normally ignores these carriage returns on input and generates them at the +end of each output line, but with the +.Op --binary +option +.Xr 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. +.Pp +The +.Op --strip-trailing-cr +causes +.Xr diff +to treat input lines that end in carriage return followed by newline as if +they end in plain newline. This can be useful when comparing text that is +imperfectly imported from many personal computer operating systems. This option +affects how lines are read, which in turn affects how they are compared and +output. +.Pp +If you want to compare two files byte by byte, you can use the +.Xr cmp +program with the +.Op -l +or +.Op --verbose +option to show the values of each differing byte in the two files. With GNU +.Xr cmp , +you can also use the +.Op -b +or +.Op --print-bytes +option to show the ASCII representation of those bytes.See Section +.Dq Invoking cmp , +for more information. +.Pp +If +.Xr 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. +.Xr diff3 +uses the same test as +.Xr diff +to decide whether a file is binary. As with +.Xr diff , +if the input files contain a few non-text bytes but otherwise are like text +files, you can force +.Xr diff3 +to consider all files to be text files and compare them line by line by using +the +.Op -a +or +.Op --text +option. +.Pp +.Sh Xr diff Output Formats +.Xr diff +has several mutually exclusive options for output format. The following sections +describe each format, illustrating how +.Xr diff +reports the differences between two sample input files. +.Pp +.Ss Two Sample Input Files +Here are two sample files that we will use in numerous examples to illustrate +the output of +.Xr diff +and how various options can change it. +.Pp +This is the file +.Pa lao : +.Pp +.Bd -literal -offset indent +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. +.Ed +.Pp +This is the file +.Pa tzu : +.Pp +.Bd -literal -offset indent +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! +.Ed +.Pp +In this example, the first hunk contains just the first two lines of +.Pa lao , +the second hunk contains the fourth line of +.Pa lao +opposing the second and third lines of +.Pa tzu , +and the last hunk contains just the last three lines of +.Pa tzu . +.Pp +.Ss 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 +.Em context . +.Pp +GNU +.Xr diff +provides two output formats that show context around the differing lines: +.Em context format +and +.Em unified format . +It can optionally show in which function or section of the file the differing +lines are found. +.Pp +If you are distributing new versions of files to other people in the form +of +.Xr 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. +.Xr 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, +.Xr patch +can adjust the line numbers accordingly and still apply the diff correctly.See Section +.Dq Imperfect , +for more information on using +.Xr patch +to apply imperfect diffs. +.Pp +.Em Context Format +.Pp +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. +.Pp +To select this output format, use the +.Op -C Va lines , +.Op --context[= Va lines] , +or +.Op -c +option. The argument +.Va lines +that some of these options take is the number of lines of context to show. +If you do not specify +.Va lines , +it defaults to three. For proper operation, +.Xr patch +typically needs at least two lines of context. +.Pp +.No An Example of Context Format +.Pp +Here is the output of +.Li diff -c lao tzu +(see Section +.Dq 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. +.Pp +.Bd -literal -offset indent +*** lao 2002-02-21 23:30:39.942229878 -0800 +--- tzu 2002-02-21 23:30:50.442260588 -0800 +*************** +*** 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! +.Ed +.Pp +.No An Example of Context Format with Less Context +.Pp +Here is the output of +.Li diff -C 1 lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files). Notice that at most one context +line is reported here. +.Pp +.Bd -literal -offset indent +*** lao 2002-02-21 23:30:39.942229878 -0800 +--- tzu 2002-02-21 23:30:50.442260588 -0800 +*************** +*** 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! +.Ed +.Pp +.No Detailed Description of Context Format +.Pp +The context output format starts with a two-line header, which looks like +this: +.Pp +.Bd -literal -offset indent +*** from-file from-file-modification-time +--- to-file to-file-modification time +.Ed +.Pp +The time stamp normally looks like +.Li 2002-02-21 23:30:39.942229878 -0800 +to indicate the date, time with fractional seconds, and time zone in +.Lk ftp://ftp.isi.edu/in-notes/rfc2822.txt . +(The fractional seconds are omitted on hosts that do not support fractional +time stamps.) However, a traditional time stamp like +.Li Thu Feb 21 23:30:39 2002 +is used if the +.Ev LC_TIME +locale category is either +.Li C +or +.Li POSIX . +.Pp +You can change the header's content with the +.Op --label= Va label +option; see Alternate Names. +.Pp +Next come one or more hunks of differences; each hunk shows one area where +the files differ. Context format hunks look like this: +.Pp +.Bd -literal -offset indent +*************** +*** from-file-line-numbers **** + from-file-line + from-file-line... +--- to-file-line-numbers ---- + to-file-line + to-file-line... +.Ed +.Pp +If a hunk contains two or more lines, its line numbers look like +.Li Va start, Va end . +Otherwise only its end line number appears. An empty hunk is considered to +end at the line that precedes the hunk. +.Pp +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: +.Pp +.Bl -tag -width Ds +.It ! +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 +.Li ! +in the part of this hunk for the other file. +.Pp +.It + +An \(lqinserted\(rq line in the second file that corresponds to nothing in the first +file. +.Pp +.It - +A \(lqdeleted\(rq line in the first file that corresponds to nothing in the second +file. +.El +.Pp +If all of the changes in a hunk are insertions, the lines of +.Va from-file +are omitted. If all of the changes are deletions, the lines of +.Va to-file +are omitted. +.Pp +.Em Unified Format +.Pp +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 +.Op -U Va lines , +.Op --unified[= Va lines] , +or +.Op -u +option. The argument +.Va lines +is the number of lines of context to show. When it is not given, it defaults +to three. +.Pp +At present, only GNU +.Xr diff +can produce this format and only GNU +.Xr patch +can automatically apply diffs in this format. For proper operation, +.Xr patch +typically needs at least three lines of context. +.Pp +.No An Example of Unified Format +.Pp +Here is the output of the command +.Li diff -u lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files): +.Pp +.Bd -literal -offset indent +--- lao 2002-02-21 23:30:39.942229878 -0800 ++++ tzu 2002-02-21 23:30:50.442260588 -0800 +@@ -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! +.Ed +.Pp +.No Detailed Description of Unified Format +.Pp +The unified output format starts with a two-line header, which looks like +this: +.Pp +.Bd -literal -offset indent +--- from-file from-file-modification-time ++++ to-file to-file-modification-time +.Ed +.Pp +The time stamp looks like +.Li 2002-02-21 23:30:39.942229878 -0800 +to indicate the date, time with fractional seconds, and time zone. The fractional +seconds are omitted on hosts that do not support fractional time stamps. +.Pp +You can change the header's content with the +.Op --label= Va label +option; seeSee Section +.Dq Alternate Names . +.Pp +Next come one or more hunks of differences; each hunk shows one area where +the files differ. Unified format hunks look like this: +.Pp +.Bd -literal -offset indent +@@ from-file-line-numbers to-file-line-numbers @@ + line-from-either-file + line-from-either-file... +.Ed +.Pp +If a hunk contains just one line, only its start line number appears. Otherwise +its line numbers look like +.Li Va start, Va count . +An empty hunk is considered to start at the line that follows the hunk. +.Pp +If a hunk and its context contain two or more lines, its line numbers look +like +.Li Va start, Va count . +Otherwise only its end line number appears. An empty hunk is considered to +end at the line that precedes the hunk. +.Pp +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 print column: +.Pp +.Bl -tag -width Ds +.It + +A line was added here to the first file. +.Pp +.It - +A line was removed here from the first file. +.El +.Pp +.Em Showing Which Sections Differences Are in +.Pp +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 +.Xr diff +can show this by displaying the nearest section heading line that precedes +the differing lines. Which lines are \(lqsection headings\(rq is determined by a regular +expression. +.Pp +.No Showing Lines That Match Regular Expressions +.Pp +To show in which sections differences occur for files that are not source +code for C or similar languages, use the +.Op -F Va regexp +or +.Op --show-function-line= Va regexp +option. +.Xr diff +considers lines that match the +.Xr grep +-style regular expression +.Va regexp +to be the beginning of a section of the file. Here are suggested regular expressions +for some common languages: +.Pp +.Bl -tag -width Ds +.It ^[[:alpha:]$_] +C, C++, Prolog +.It ^( +Lisp +.It ^@node +Texinfo +.El +.Pp +This option does not automatically select an output format; in order to use +it, you must select the context format (see Section +.Dq Context Format ) +or unified format (see Section +.Dq Unified Format ) . +In other output formats it has no effect. +.Pp +The +.Op -F +or +.Op --show-function-line +option finds the nearest unchanged line that precedes each hunk of differences +and matches the given regular expression. Then it adds that line to the end +of the line of asterisks in the context format, or to the +.Li @@ +line in unified format. If no matching line exists, this option leaves the +output for that hunk unchanged. If that line is more than 40 characters long, +it outputs only the first 40 characters. You can specify more than one regular +expression for such lines; +.Xr diff +tries to match each line against each regular expression, starting with the +last one given. This means that you can use +.Op -p +and +.Op -F +together, if you wish. +.Pp +.No Showing C Function Headings +.Pp +To show in which functions differences occur for C and similar languages, +you can use the +.Op -p +or +.Op --show-c-function +option. This option automatically defaults to the context output format (see Section +.Dq Context Format ) , +with the default number of lines of context. You can override that number +with +.Op -C Va lines +elsewhere in the command line. You can override both the format and the number +with +.Op -U Va lines +elsewhere in the command line. +.Pp +The +.Op -p +or +.Op --show-c-function +option is equivalent to +.Op -F '^[[:alpha:]$_]' +if the unified format is specified, otherwise +.Op -c -F '^[[:alpha:]$_]' +(see Section +.Dq Specified Headings ) . +GNU +.Xr diff +provides this option for the sake of convenience. +.Pp +.Em Showing Alternate File Names +.Pp +If you are comparing two files that have meaningless or uninformative names, +you might want +.Xr diff +to show alternate names in the header of the context and unified output formats. +To do this, use the +.Op --label= Va 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 OUTPUT TRUNCATED AT 1000 LINES *** _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"
