X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fdiff-format.txt;h=883c1bb0a638d97278cdb66e288bc766a32626af;hb=e0d10e1c63bc52b37bbec99b07deee794058d9b4;hp=9298d79e51bf87ccff66357227c7df4db4c820c4;hpb=6b7242aa1acc3c7835f80522914ffc4b2e789a29;p=git.git diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 9298d79e5..883c1bb0a 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -1,127 +1,91 @@ -The output format from "git-diff-cache", "git-diff-tree" and -"git-diff-files" is very similar. +The output format from "git-diff-index", "git-diff-tree" and +"git-diff-files" are very similar. -These commands all compare two sets of things; what are -compared are different: +These commands all compare two sets of things; what is +compared differs: -git-diff-cache :: +git-diff-index :: compares the and the files on the filesystem. -git-diff-cache --cached :: - compares the and the cache. +git-diff-index --cached :: + compares the and the index. git-diff-tree [-r] [...]:: compares the trees named by the two arguments. git-diff-files [...]:: - compares the cache and the files on the filesystem. + compares the index and the files on the filesystem. An output line is formatted this way: +------------------------------------------------ in-place edit :100644 100644 bcd1234... 0123456... M file0 copy-edit :100644 100644 abcd123... 1234567... C68 file1 file2 rename-edit :100644 100644 abcd123... 1234567... R86 file1 file3 -create :000000 100644 0000000... 1234567... N file4 +create :000000 100644 0000000... 1234567... A file4 delete :100644 000000 1234567... 0000000... D file5 unmerged :000000 000000 0000000... 0000000... U file6 +------------------------------------------------ That is, from the left to the right: - (1) a colon. - (2) mode for "src"; 000000 if creation or unmerged. - (3) a space. - (4) mode for "dst"; 000000 if deletion or unmerged. - (5) a space. - (6) sha1 for "src"; 0{40} if creation or unmerged. - (7) a space. - (8) sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree". - (9) a space. - (10) status, followed by optional "score" number. - (11) a tab or a NUL when '-z' option is used. - (12) path for "src" - (13) a tab or a NUL when '-z' option is used; only exists for C or R. - (14) path for "dst"; only exists for C or R. - (15) an LF or a NUL when '-z' option is used, to terminate the record. - - is shown as all 0's if new is a file on the filesystem -and it is out of sync with the cache. Example: - - :100644 100644 5be4a4...... 000000...... M file.c +. a colon. +. mode for "src"; 000000 if creation or unmerged. +. a space. +. mode for "dst"; 000000 if deletion or unmerged. +. a space. +. sha1 for "src"; 0\{40\} if creation or unmerged. +. a space. +. sha1 for "dst"; 0\{40\} if creation, unmerged or "look at work tree". +. a space. +. status, followed by optional "score" number. +. a tab or a NUL when '-z' option is used. +. path for "src" +. a tab or a NUL when '-z' option is used; only exists for C or R. +. path for "dst"; only exists for C or R. +. an LF or a NUL when '-z' option is used, to terminate the record. -Generating patches with -p --------------------------- + is shown as all 0's if a file is new on the filesystem +and it is out of sync with the index. -When "git-diff-cache", "git-diff-tree", or "git-diff-files" are run -with a '-p' option, they do not produce the output described above; -instead they produce a patch file. +Example: -The patch generation can be customized at two levels. This -customization also applies to "git-diff-helper". +------------------------------------------------ +:100644 100644 5be4a4...... 000000...... M file.c +------------------------------------------------ -1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, - these commands internally invoke "diff" like this: +When `-z` option is not used, TAB, LF, and backslash characters +in pathnames are represented as `\t`, `\n`, and `\\`, +respectively. - diff -L a/ -L b/ -pu -+ -For added files, `/dev/null` is used for . For removed -files, `/dev/null` is used for -+ -The "diff" formatting options can be customized via the -environment variable 'GIT_DIFF_OPTS'. For example, if you -prefer context diff: - - GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD) - - -2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the - program named by it is called, instead of the diff invocation - described above. -+ -For a path that is added, removed, or modified, -'GIT_EXTERNAL_DIFF' is called with 7 parameters: - - path old-file old-hex old-mode new-file new-hex new-mode -+ -where: - - -file:: are files GIT_EXTERNAL_DIFF can use to read the - contents of , - -hex:: are the 40-hexdigit SHA1 hashes, - -mode:: are the octal representation of the file modes. - -+ -The file parameters can point at the user's working file -(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` -when a new file is added), or a temporary file (e.g. `old-file` in the -cache). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the -temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. - -For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 -parameter, . +Generating patches with -p +-------------------------- -Git specific extension to diff format -------------------------------------- +When "git-diff-index", "git-diff-tree", or "git-diff-files" are run +with a '-p' option, they do not produce the output described above; +instead they produce a patch file. You can customize the creation +of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS +environment variables. -What -p option produces is slightly different from the -traditional diff format. +What the -p option produces is slightly different from the traditional +diff format. - (1) It is preceeded with a "git diff" header, that looks like +1. It is preceded with a "git diff" header, that looks like this: - diff --git a/file1 b/file2 - - The a/ and b/ filenames are the same unless rename/copy is - involved. Especially, even for a creation or a deletion, - /dev/null is _not_ used in place of a/ or b/ filename. - - When rename/copy is involved, file1 and file2 shows the - name of the source file of the rename/copy and the name of - the file that rename/copy produces, respectively. + diff --git a/file1 b/file2 ++ +The `a/` and `b/` filenames are the same unless rename/copy is +involved. Especially, even for a creation or a deletion, +`/dev/null` is _not_ used in place of `a/` or `b/` filenames. ++ +When rename/copy is involved, `file1` and `file2` show the +name of the source file of the rename/copy and the name of +the file that rename/copy produces, respectively. - (2) It is followed by extended header lines that are one or - more of: +2. It is followed by one or more extended header lines: old mode new mode @@ -133,3 +97,118 @@ traditional diff format. rename to similarity index dissimilarity index + index .. + +3. TAB, LF, double quote and backslash characters in pathnames + are represented as `\t`, `\n`, `\"` and `\\`, respectively. + If there is need for such substitution then the whole + pathname is put in double quotes. + + +combined diff format +-------------------- + +git-diff-tree and git-diff-files can take '-c' or '--cc' option +to produce 'combined diff', which looks like this: + +------------ +diff --combined describe.c +index fabadb8,cc95eb0..4866510 +--- a/describe.c ++++ b/describe.c +@@@ -98,20 -98,12 +98,20 @@@ + return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; + } + +- static void describe(char *arg) + -static void describe(struct commit *cmit, int last_one) +++static void describe(char *arg, int last_one) + { + + unsigned char sha1[20]; + + struct commit *cmit; + struct commit_list *list; + static int initialized = 0; + struct commit_name *n; + + + if (get_sha1(arg, sha1) < 0) + + usage(describe_usage); + + cmit = lookup_commit_reference(sha1); + + if (!cmit) + + usage(describe_usage); + + + if (!initialized) { + initialized = 1; + for_each_ref(get_name); +------------ + +1. It is preceded with a "git diff" header, that looks like + this (when '-c' option is used): + + diff --combined file ++ +or like this (when '--cc' option is used): + + diff --c file + +2. It is followed by one or more extended header lines + (this example shows a merge with two parents): + + index ,.. + mode ,.. + new file mode + deleted file mode , ++ +The `mode ,..` line appears only if at least one of +the is diferent from the rest. Extended headers with +information about detected contents movement (renames and +copying detection) are designed to work with diff of two + and are not used by combined diff format. + +3. It is followed by two-line from-file/to-file header + + --- a/file + +++ b/file ++ +Similar to two-line header for traditional 'unified' diff +format, `/dev/null` is used to signal created or deleted +files. + +4. Chunk header format is modified to prevent people from + accidentally feeding it to `patch -p1`. Combined diff format + was created for review of merge commit changes, and was not + meant for apply. The change is similar to the change in the + extended 'index' header: + + @@@ @@@ ++ +There are (number of parents + 1) `@` characters in the chunk +header for combined diff format. + +Unlike the traditional 'unified' diff format, which shows two +files A and B with a single column that has `-` (minus -- +appears in A but removed in B), `+` (plus -- missing in A but +added to B), or `" "` (space -- unchanged) prefix, this format +compares two or more files file1, file2,... with one file X, and +shows how X differs from each of fileN. One column for each of +fileN is prepended to the output line to note how X's line is +different from it. + +A `-` character in the column N means that the line appears in +fileN but it does not appear in the result. A `+` character +in the column N means that the line appears in the last file, +and fileN does not have that line (in other words, the line was +added, from the point of view of that parent). + +In the above example output, the function signature was changed +from both files (hence two `-` removals from both file1 and +file2, plus `++` to mean one line that was added does not appear +in either file1 nor file2). Also two other lines are the same +from file1 but do not appear in file2 (hence prefixed with ` +`). + +When shown by `git diff-tree -c`, it compares the parents of a +merge commit with the merge result (i.e. file1..fileN are the +parents). When shown by `git diff-files -c`, it compares the +two unresolved merge parents with the working tree file +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka +"their version"). +