Documentation/diff-format.txt

   1 The output format from "git-diff-index", "git-diff-tree" and
   2 "git-diff-files" are very similar.
   3
   4 These commands all compare two sets of things; what is
   5 compared differs:
   6
   7 git-diff-index <tree-ish>::
   8         compares the <tree-ish> and the files on the filesystem.
   9
  10 git-diff-index --cached <tree-ish>::
  11         compares the <tree-ish> and the index.
  12
  13 git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::
  14         compares the trees named by the two arguments.
  15
  16 git-diff-files [<pattern>...]::
  17         compares the index and the files on the filesystem.
  18
  19
  20 An output line is formatted this way:
  21
  22 ------------------------------------------------
  23 in-place edit  :100644 100644 bcd1234... 0123456... M file0
  24 copy-edit      :100644 100644 abcd123... 1234567... C68 file1 file2
  25 rename-edit    :100644 100644 abcd123... 1234567... R86 file1 file3
  26 create         :000000 100644 0000000... 1234567... A file4
  27 delete         :100644 000000 1234567... 0000000... D file5
  28 unmerged       :000000 000000 0000000... 0000000... U file6
  29 ------------------------------------------------
  30
  31 That is, from the left to the right:
  32
  33 . a colon.
  34 . mode for "src"; 000000 if creation or unmerged.
  35 . a space.
  36 . mode for "dst"; 000000 if deletion or unmerged.
  37 . a space.
  38 . sha1 for "src"; 0\{40\} if creation or unmerged.
  39 . a space.
  40 . sha1 for "dst"; 0\{40\} if creation, unmerged or "look at work tree".
  41 . a space.
  42 . status, followed by optional "score" number.
  43 . a tab or a NUL when '-z' option is used.
  44 . path for "src"
  45 . a tab or a NUL when '-z' option is used; only exists for C or R.
  46 . path for "dst"; only exists for C or R.
  47 . an LF or a NUL when '-z' option is used, to terminate the record.
  48
  49 <sha1> is shown as all 0's if a file is new on the filesystem
  50 and it is out of sync with the index.
  51
  52 Example:
  53
  54 ------------------------------------------------
  55 :100644 100644 5be4a4...... 000000...... M file.c
  56 ------------------------------------------------
  57
  58 When `-z` option is not used, TAB, LF, and backslash characters
  59 in pathnames are represented as `\t`, `\n`, and `\\`,
  60 respectively.
  61
  62
  63 Generating patches with -p
  64 --------------------------
  65
  66 When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
  67 with a '-p' option, they do not produce the output described above;
  68 instead they produce a patch file.  You can customize the creation
  69 of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS
  70 environment variables.
  71
  72 What the -p option produces is slightly different from the traditional
  73 diff format.
  74
  75 1.   It is preceded with a "git diff" header, that looks like
  76      this:
  77
  78        diff --git a/file1 b/file2
  79 +
  80 The `a/` and `b/` filenames are the same unless rename/copy is
  81 involved.  Especially, even for a creation or a deletion,
  82 `/dev/null` is _not_ used in place of `a/` or `b/` filenames.
  83 +
  84 When rename/copy is involved, `file1` and `file2` show the
  85 name of the source file of the rename/copy and the name of
  86 the file that rename/copy produces, respectively.
  87
  88 2.   It is followed by one or more extended header lines:
  89
  90        old mode <mode>
  91        new mode <mode>
  92        deleted file mode <mode>
  93        new file mode <mode>
  94        copy from <path>
  95        copy to <path>
  96        rename from <path>
  97        rename to <path>
  98        similarity index <number>
  99        dissimilarity index <number>
 100        index <hash>..<hash> <mode>
 101
 102 3.  TAB, LF, double quote and backslash characters in pathnames
 103     are represented as `\t`, `\n`, `\"` and `\\`, respectively.
 104     If there is need for such substitution then the whole
 105     pathname is put in double quotes.
 106
 107
 108 combined diff format
 109 --------------------
 110
 111 git-diff-tree and git-diff-files can take '-c' or '--cc' option
 112 to produce 'combined diff', which looks like this:
 113
 114 ------------
 115 diff --combined describe.c
 116 index fabadb8,cc95eb0..4866510
 117 --- a/describe.c
 118 +++ b/describe.c
 119 @@@ -98,20 -98,12 +98,20 @@@
 120         return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
 121   }
 122
 123 - static void describe(char *arg)
 124  -static void describe(struct commit *cmit, int last_one)
 125 ++static void describe(char *arg, int last_one)
 126   {
 127  +      unsigned char sha1[20];
 128  +      struct commit *cmit;
 129         struct commit_list *list;
 130         static int initialized = 0;
 131         struct commit_name *n;
 132
 133  +      if (get_sha1(arg, sha1) < 0)
 134  +              usage(describe_usage);
 135  +      cmit = lookup_commit_reference(sha1);
 136  +      if (!cmit)
 137  +              usage(describe_usage);
 138  +
 139         if (!initialized) {
 140                 initialized = 1;
 141                 for_each_ref(get_name);
 142 ------------
 143
 144 1.   It is preceded with a "git diff" header, that looks like
 145      this (when '-c' option is used):
 146
 147        diff --combined file
 148 +
 149 or like this (when '--cc' option is used):
 150
 151        diff --c file
 152
 153 2.   It is followed by one or more extended header lines
 154      (this example shows a merge with two parents):
 155
 156        index <hash>,<hash>..<hash>
 157        mode <mode>,<mode>..<mode>
 158        new file mode <mode>
 159        deleted file mode <mode>,<mode>
 160 +
 161 The `mode <mode>,<mode>..<mode>` line appears only if at least one of
 162 the <mode> is diferent from the rest. Extended headers with
 163 information about detected contents movement (renames and
 164 copying detection) are designed to work with diff of two
 165 <tree-ish> and are not used by combined diff format.
 166
 167 3.   It is followed by two-line from-file/to-file header
 168
 169        --- a/file
 170        +++ b/file
 171 +
 172 Similar to two-line header for traditional 'unified' diff
 173 format, `/dev/null` is used to signal created or deleted
 174 files.
 175
 176 4.   Chunk header format is modified to prevent people from
 177      accidentally feeding it to `patch -p1`. Combined diff format
 178      was created for review of merge commit changes, and was not
 179      meant for apply. The change is similar to the change in the
 180      extended 'index' header:
 181
 182        @@@ <from-file-range> <from-file-range> <to-file-range> @@@
 183 +
 184 There are (number of parents + 1) `@` characters in the chunk
 185 header for combined diff format.
 186
 187 Unlike the traditional 'unified' diff format, which shows two
 188 files A and B with a single column that has `-` (minus --
 189 appears in A but removed in B), `+` (plus -- missing in A but
 190 added to B), or `" "` (space -- unchanged) prefix, this format
 191 compares two or more files file1, file2,... with one file X, and
 192 shows how X differs from each of fileN.  One column for each of
 193 fileN is prepended to the output line to note how X's line is
 194 different from it.
 195
 196 A `-` character in the column N means that the line appears in
 197 fileN but it does not appear in the result.  A `+` character
 198 in the column N means that the line appears in the last file,
 199 and fileN does not have that line (in other words, the line was
 200 added, from the point of view of that parent).
 201
 202 In the above example output, the function signature was changed
 203 from both files (hence two `-` removals from both file1 and
 204 file2, plus `++` to mean one line that was added does not appear
 205 in either file1 nor file2).  Also two other lines are the same
 206 from file1 but do not appear in file2 (hence prefixed with ` +`).
 207
 208 When shown by `git diff-tree -c`, it compares the parents of a
 209 merge commit with the merge result (i.e. file1..fileN are the
 210 parents).  When shown by `git diff-files -c`, it compares the
 211 two unresolved merge parents with the working tree file
 212 (i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka
 213 "their version").
 214