@matheusbsbs / matheus-bagliano / commits / 0074aba1c0
Fork 0

diff-format.txt: Combined diff format documentation supplement

Update example combined diff format to the current version $ git diff-tree -p -c fec9ebf16c948bcb4a8b88d0173ee63584bcde76 and provide complete first chunk in example. Document combined diff format headers: how "diff header" look like, which of "extended diff headers" are used with combined diff and how they look like, differences in two-line from-file/to-file header from non-combined diff format, chunk header format. It should be noted that combined diff format was designed for quick _content_ inspection and renames would work correctly to pick which blobs from each tree to compare but otherwise not reflected in the output (the pathnames are not shown). [jc: with minimum copyediting] Signed-off-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>

Jakub Narebski committed Oct 26, 2006 at 05:44 UTC 0074aba1c0d3b073c635fdc1d5754dc6a6b6b7b9
1 file changed +68 -8
Documentation/diff-format.txt
+68 -8
@@ -156,31 +156,91 @@ to produce 'combined diff', which looks like this:
156
157 ------------
158 diff --combined describe.c
159 -@@@ +98,7 @@@
160 - return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
159 +index fabadb8,cc95eb0..4866510
160 +--- a/describe.c
161 ++++ b/describe.c
162 +@@@ -98,20 -98,12 +98,20 @@@
163 + return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
164 }
162 -
165 +
166 - static void describe(char *arg)
167 -static void describe(struct commit *cmit, int last_one)
168 ++static void describe(char *arg, int last_one)
169 {
167 - + unsigned char sha1[20];
168 - + struct commit *cmit;
170 + + unsigned char sha1[20];
171 + + struct commit *cmit;
172 + struct commit_list *list;
173 + static int initialized = 0;
174 + struct commit_name *n;
175 +
176 + + if (get_sha1(arg, sha1) < 0)
177 + + usage(describe_usage);
178 + + cmit = lookup_commit_reference(sha1);
179 + + if (!cmit)
180 + + usage(describe_usage);
181 + +
182 + if (!initialized) {
183 + initialized = 1;
184 + for_each_ref(get_name);
185 ------------
186
187 +1. It is preceded with a "git diff" header, that looks like
188 + this (when '-c' option is used):
189 +
190 + diff --combined file
191 ++
192 +or like this (when '--cc' option is used):
193 +
194 + diff --c file
195 +
196 +2. It is followed by one or more extended header lines
197 + (this example shows a merge with two parents):
198 +
199 + index <hash>,<hash>..<hash>
200 + mode <mode>,<mode>..<mode>
201 + new file mode <mode>
202 + deleted file mode <mode>,<mode>
203 ++
204 +The `mode <mode>,<mode>..<mode>` line appears only if at least one of
205 +the <mode> is diferent from the rest. Extended headers with
206 +information about detected contents movement (renames and
207 +copying detection) are designed to work with diff of two
208 +<tree-ish> and are not used by combined diff format.
209 +
210 +3. It is followed by two-line from-file/to-file header
211 +
212 + --- a/file
213 + +++ b/file
214 ++
215 +Contrary to two-line header for traditional 'unified' diff
216 +format, and similar to filenames in ordinary "diff header",
217 +/dev/null is not used for creation or deletion.
218 +
219 +4. Chunk header format is modified to prevent people from
220 + accidentally feeding it to `patch -p1`. Combined diff format
221 + was created for review of merge commit changes, and was not
222 + meant for apply. The change is similar to the change in the
223 + extended 'index' header:
224 +
225 + @@@ <from-file-range> <from-file-range> <to-file-range> @@@
226 ++
227 +There are (number of parents + 1) `@` characters in the chunk
228 +header for combined diff format.
229 +
230 Unlike the traditional 'unified' diff format, which shows two
231 files A and B with a single column that has `-` (minus --
232 appears in A but removed in B), `+` (plus -- missing in A but
174 -added to B), or ` ` (space -- unchanged) prefix, this format
233 +added to B), or `" "` (space -- unchanged) prefix, this format
234 compares two or more files file1, file2,... with one file X, and
235 shows how X differs from each of fileN. One column for each of
236 fileN is prepended to the output line to note how X's line is
237 different from it.
238
239 A `-` character in the column N means that the line appears in
181 -fileN but it does not appear in the last file. A `+` character
240 +fileN but it does not appear in the result. A `+` character
241 in the column N means that the line appears in the last file,
183 -and fileN does not have that line.
242 +and fileN does not have that line (in other words, the line was
243 +added, from the point of view of that parent).
244
245 In the above example output, the function signature was changed
246 from both files (hence two `-` removals from both file1 and