The diff command accepts two arguments like: diff
original new. Commonly, the arguments each identify normal files, but if the two arguments identify directories, then the command compares corresponding files in the directories. With the -r option, it recursively descends matching subdirectories to compare files with corresponding relative paths.
Default output format The example below shows the original and new file content as well as the resulting diff output in the default format. The output is shown with coloring to improve readability. By default, diff outputs
plain text, but GNU diff does use color
highlighting when the option is used.
original: This part of the document has stayed the same from version to version. It shouldn't be shown if it doesn't change. Otherwise, that would not be helping to compress the size of the changes. This paragraph contains text that is outdated. It will be deleted in the near future. It is important to spell check this dokument. On the other hand, a misspelled word isn't the end of the world. Nothing in the rest of this paragraph needs to be changed. Things can be added after it.
new: This is an important notice! It should therefore be located at the beginning of this document! This part of the document has stayed the same from version to version. It shouldn't be shown if it doesn't change. Otherwise, that would not be helping to compress the size of the changes. It is important to spell check this document. On the other hand, a misspelled word isn't the end of the world. Nothing in the rest of this paragraph needs to be changed. Things can be added after it. This paragraph contains important new additions to this document. output: In this default format, stands for added, for deleted and for changed. The line number of the original file appears before the single-letter code and the line number of the new file appears after. The
less-than and
greater-than signs (at the beginning of lines that are added, deleted or changed) indicate which file the lines appear in. Addition lines are added to the original file to appear in the new file. Deletion lines are deleted from the original file to be missing in the new file. By default, lines common to both files are not shown. Lines that have moved are shown as added at their new location and as deleted from their old location. However, some diff tools highlight moved lines.
Edit script An
ed script can be generated by modern versions of diff with the -e option. The resulting edit script for this example is as follows: 24
a This paragraph contains important new additions to this document. . 17
c check this document. On . 11,15
d 0
a This is an important notice! It should therefore be located at the beginning of this document! . In order to transform the content of the original file into the content of new file using , one appends two lines to this diff file, one line containing a w (write) command, and one containing a q (quit) command (e.g. by ). Here we gave the diff file the name
mydiff and the transformation will then happen when we run .
Context format The
Berkeley distribution of Unix made a point of adding the
context format () and the ability to recurse on filesystem directory structures (), adding those features in 2.8 BSD, released in July 1981. The context format of diff introduced at Berkeley helped with distributing patches for source code that may have been changed minimally. In the context format, any changed lines are shown alongside unchanged lines before and after. The inclusion of any number of unchanged lines provides a
context to the patch. The
context consists of lines that have not changed between the two files and serve as a reference to locate the lines' place in a modified file and find the intended location for a change to be applied regardless of whether the line numbers still correspond. The context format introduces greater readability for humans and reliability when applying the patch, and an output which is accepted as input to the
patch program. This intelligent behavior is not possible with the traditional diff output. The number of unchanged lines shown above and below a change
hunk can be defined by the user, even zero, but three lines is typically the default. If the context of unchanged lines in a hunk overlap with an adjacent hunk, then diff will avoid duplicating the unchanged lines and merge the hunks into a single hunk. A "" represents a change between lines that correspond in the two files, whereas a "" represents the addition of a line, and a "" the removal of a line. A blank
space represents an unchanged line. At the beginning of the patch is the file information, including the full path and a
time stamp delimited by a tab character. At the beginning of each hunk are the line numbers that apply for the corresponding change in the files. A number range appearing between sets of three asterisks applies to the original file, while sets of three dashes apply to the new file. The hunk ranges specify the starting and ending line numbers in the respective file. The command produces the following output: • /path/to/original timestamp --- /path/to/new timestamp • • 1,3 **** --- 1,9 ---- + This is an important + notice! It should + therefore be located at + the beginning of this + document! + This part of the document has stayed the same from version to • • 8,20 **** compress the size of the changes. - This paragraph contains - text that is outdated. - It will be deleted in the - near future. It is important to spell the other hand, a misspelled word isn't the end of the world. --- 14,21 ---- compress the size of the changes. It is important to spell the other hand, a misspelled word isn't the end of the world. • • 22,24 **** --- 23,29 ---- this paragraph needs to be changed. Things can be added after it. + + This paragraph contains + important new additions + to this document.
Unified format The
unified format (or
unidiff) inherits the technical improvements made by the context format, but produces a smaller diff with old and new text presented immediately adjacent. Unified format is usually invoked using the "-u"
command-line option. This output is often used as input to the
patch program. Many projects specifically request that "diffs" be submitted in the unified format, making unified diff format the most common format for exchange between software developers. Unified context diffs were originally developed by Wayne Davison in August 1990 (in
unidiff which appeared in Volume 14 of comp.sources.misc).
Richard Stallman added unified diff support to the
GNU Project's diff one month later, and the feature debuted in
GNU diff 1.15, released in January 1991. GNU diff has since generalized the context format to allow arbitrary formatting of diffs. The format starts with the same two-line
header as the context format, except that the original file is preceded by "---" and the new file is preceded by "+++". Following this are one or more
change hunks that contain the line differences in the file. The unchanged, contextual lines are preceded by a space character, addition lines are preceded by a
plus sign, and deletion lines are preceded by a
minus sign. A hunk begins with
range information and is immediately followed with the line additions, line deletions, and any number of the contextual lines. The range information is surrounded by double
at signs, and combines onto a single line what appears on two lines in the context format (
above). The format of the range information line is as follows: @@ -l,s +l,s @@
optional section heading ruins the italics --> The hunk range information contains two hunk ranges. The range for the hunk of the original file is preceded by a minus symbol, and the range for the new file is preceded by a plus symbol. Each hunk range is of the format
l,s where
l is the starting line number and
s is the number of lines the change hunk applies to for each respective file. In many versions of GNU diff, each range can omit the comma and trailing value
s, in which case
s defaults to 1. Note that the only really interesting value is the
l line number of the first range; all the other values can be computed from the diff. The hunk range for the original should be the sum of all contextual and deletion (including changed) hunk lines. The hunk range for the new file should be a sum of all contextual and addition (including changed) hunk lines. If hunk size information does not correspond with the number of lines in the hunk, then the diff could be considered invalid and be rejected. Optionally, the hunk range can be followed by the heading of the section or function that the hunk is part of. This is mainly useful to make the diff easier to read. When creating a diff with GNU diff, the heading is identified by
regular expression matching. If a line is modified, it is represented as a deletion and addition. Since the hunks of the original and new file appear in the same hunk, such changes would appear adjacent to one another. An occurrence of this in the example below is: -check this dokument. On +check this document. On The command diff -u original new produces the following output: --- /path/to/original timestamp +++ /path/to/new timestamp @@ -1,3 +1,9 @@ +This is an important +notice! It should +therefore be located at +the beginning of this +document! + This part of the document has stayed the same from version to @@ -8,13 +14,8 @@ compress the size of the changes. -This paragraph contains -text that is outdated. -It will be deleted in the -near future. - It is important to spell -check this dokument. On +check this document. On the other hand, a misspelled word isn't the end of the world. @@ -22,3 +23,7 @@ this paragraph needs to be changed. Things can be added after it. + +This paragraph contains +important new additions +to this document. To successfully separate the file names from the timestamps, the delimiter between them is a tab character. This is invisible on screen and can be lost when diffs are copy/pasted from console/terminal screens.
Extensions There are some modifications and extensions to the diff formats that are used and understood by certain programs and in certain contexts. For example, some
revision control systems—such as
Subversion—specify a version number, "working copy", or any other comment instead of or in addition to a timestamp in the diff's header section. Some tools allow diffs for several different files to be merged into one, using a header for each modified file that may look something like this: Index: path/to/file.cpp The special case of files that do not end in a newline is not handled. Neither nor the POSIX standard define a way to handle this type of files. (Indeed, such files are not "text" files by strict POSIX definitions.) GNU diff and git produce "\ No newline at end of file" (or a translated version) as a diagnostic, but this behavior is not portable. GNU patch does not seem to handle this case, while git-apply does. The
patch program does not necessarily recognize implementation-specific diff output. GNU patch is, however, known to recognize git patches and act a little differently. == Implementations and related programs ==