Assorted typo fixes
[git/git.git] / 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 different 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