From: Jakub Narebski Date: Thu, 26 Oct 2006 03:44:49 +0000 (+0200) Subject: diff-format.txt: Combined diff format documentation supplement X-Git-Tag: v1.4.3.4~21 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=0074aba1c0d3b073c635fdc1d5754dc6a6b6b7b9;p=git.git 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 Signed-off-by: Junio C Hamano --- diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 617d8f526..174d63a1e 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -156,31 +156,91 @@ to produce 'combined diff', which looks like this: ------------ diff --combined describe.c -@@@ +98,7 @@@ - return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; +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; + + 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 ++ +Contrary to two-line header for traditional 'unified' diff +format, and similar to filenames in ordinary "diff header", +/dev/null is not used for creation or deletion. + +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 +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 last file. A `+` character +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. +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