Assorted typo fixes
[git/git.git] / Documentation / diff-format.txt
CommitLineData
215a7ad1 1The output format from "git-diff-index", "git-diff-tree" and
8db9307c 2"git-diff-files" are very similar.
03ea2802 3
f73ae1fc
CM
4These commands all compare two sets of things; what is
5compared differs:
03ea2802 6
215a7ad1 7git-diff-index <tree-ish>::
03ea2802
DG
8 compares the <tree-ish> and the files on the filesystem.
9
215a7ad1 10git-diff-index --cached <tree-ish>::
5f3aa197 11 compares the <tree-ish> and the index.
03ea2802
DG
12
13git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::
14 compares the trees named by the two arguments.
15
16git-diff-files [<pattern>...]::
5f3aa197 17 compares the index and the files on the filesystem.
03ea2802 18
03ea2802 19
81e50eab 20An output line is formatted this way:
03ea2802 21
8db9307c 22------------------------------------------------
b6d8f309
JH
23in-place edit :100644 100644 bcd1234... 0123456... M file0
24copy-edit :100644 100644 abcd123... 1234567... C68 file1 file2
25rename-edit :100644 100644 abcd123... 1234567... R86 file1 file3
8db9307c 26create :000000 100644 0000000... 1234567... A file4
b6d8f309
JH
27delete :100644 000000 1234567... 0000000... D file5
28unmerged :000000 000000 0000000... 0000000... U file6
8db9307c 29------------------------------------------------
b6d8f309
JH
30
31That is, from the left to the right:
32
8db9307c
JH
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.
03ea2802 48
f73ae1fc 49<sha1> is shown as all 0's if a file is new on the filesystem
5f3aa197 50and it is out of sync with the index.
03ea2802 51
8db9307c
JH
52Example:
53
54------------------------------------------------
55:100644 100644 5be4a4...... 000000...... M file.c
56------------------------------------------------
03ea2802 57
d88156e9
JH
58When `-z` option is not used, TAB, LF, and backslash characters
59in pathnames are represented as `\t`, `\n`, and `\\`,
60respectively.
61
62
03ea2802
DG
63Generating patches with -p
64--------------------------
65
215a7ad1 66When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
1a93a766 67with a '-p' option, they do not produce the output described above;
fde97d8a
SE
68instead they produce a patch file. You can customize the creation
69of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS
70environment variables.
03ea2802 71
fde97d8a
SE
72What the -p option produces is slightly different from the traditional
73diff format.
1a93a766 74
89438677 751. It is preceded with a "git diff" header, that looks like
1a93a766
JH
76 this:
77
fde97d8a 78 diff --git a/file1 b/file2
8db9307c
JH
79+
80The `a/` and `b/` filenames are the same unless rename/copy is
81involved. Especially, even for a creation or a deletion,
82`/dev/null` is _not_ used in place of `a/` or `b/` filenames.
83+
f73ae1fc 84When rename/copy is involved, `file1` and `file2` show the
8db9307c
JH
85name of the source file of the rename/copy and the name of
86the file that rename/copy produces, respectively.
1a93a766 87
f73ae1fc 882. It is followed by one or more extended header lines:
1a93a766
JH
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>
d88156e9
JH
100 index <hash>..<hash> <mode>
101
fb8e23fa
JN
1023. 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.
34801cab
JH
106
107
108combined diff format
109--------------------
110
111git-diff-tree and git-diff-files can take '-c' or '--cc' option
112to produce 'combined diff', which looks like this:
113
114------------
115diff --combined describe.c
0074aba1
JN
116index 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;
34801cab 121 }
0074aba1 122
34801cab
JH
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 {
0074aba1
JN
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);
34801cab
JH
142------------
143
0074aba1
JN
1441. It is preceded with a "git diff" header, that looks like
145 this (when '-c' option is used):
146
147 diff --combined file
148+
149or like this (when '--cc' option is used):
150
151 diff --c file
152
1532. 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+
161The `mode <mode>,<mode>..<mode>` line appears only if at least one of
3dff5379 162the <mode> is different from the rest. Extended headers with
0074aba1
JN
163information about detected contents movement (renames and
164copying detection) are designed to work with diff of two
165<tree-ish> and are not used by combined diff format.
166
1673. It is followed by two-line from-file/to-file header
168
169 --- a/file
170 +++ b/file
171+
d5f6a01a
JH
172Similar to two-line header for traditional 'unified' diff
173format, `/dev/null` is used to signal created or deleted
174files.
0074aba1
JN
175
1764. 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+
184There are (number of parents + 1) `@` characters in the chunk
185header for combined diff format.
186
34801cab
JH
187Unlike the traditional 'unified' diff format, which shows two
188files A and B with a single column that has `-` (minus --
189appears in A but removed in B), `+` (plus -- missing in A but
0074aba1 190added to B), or `" "` (space -- unchanged) prefix, this format
34801cab
JH
191compares two or more files file1, file2,... with one file X, and
192shows how X differs from each of fileN. One column for each of
193fileN is prepended to the output line to note how X's line is
194different from it.
195
196A `-` character in the column N means that the line appears in
0074aba1 197fileN but it does not appear in the result. A `+` character
34801cab 198in the column N means that the line appears in the last file,
0074aba1
JN
199and fileN does not have that line (in other words, the line was
200added, from the point of view of that parent).
34801cab
JH
201
202In the above example output, the function signature was changed
203from both files (hence two `-` removals from both file1 and
204file2, plus `++` to mean one line that was added does not appear
205in either file1 nor file2). Also two other lines are the same
206from file1 but do not appear in file2 (hence prefixed with ` +`).
207
208When shown by `git diff-tree -c`, it compares the parents of a
209merge commit with the merge result (i.e. file1..fileN are the
210parents). When shown by `git diff-files -c`, it compares the
211two 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