Re: Meaning of double + and - in Gitk's diff pane

[Junio C Hamano <gitster@pobox.com>]

Dirk Süsserott <newsletter@dirk.my1.cc> writes:

> Am 21.03.2011 20:49 schrieb Junio C Hamano:
>>>
>>> Junio, thanks. When I've found the time, I'll probably condense Linus'
>>> explanations and submit a documentation patch. It's not explained
>>> in the actual git docs, right?
>>
>> How about checking "git diff"?  The same conclusion should be in there, as
>> I wrote the implementation, docs and the messages there.
>>
> Uhh, sorry, I missed that. That was actually what I was searching for.

Hmm... re-reading "git diff --help" and looking at the section on combined
diff, I notice that we talk about how to understand its output, but we
don't say under what rule the --cc option condenses what would be produced
with the -c option.  Perhaps we would need a patch after all at the end of
Documentation/diff-generate-patch.txt file.

Here is a quick attempt.

 Documentation/diff-generate-patch.txt |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)

diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index c57460c..20a603d 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -183,3 +183,21 @@ parents).  When shown by `git diff-files -c`, it compares the
 two unresolved merge parents with the working tree file
 (i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka
 "their version").
+
+The "combined" format (`-c` option) shows the diff to the result (i.e. the
+result of the merge, or the file in the working tree during a conflict
+resolution) from two or more originals (i.e. parents of the merge or
+branches being merged) combined, but it often shows many trivial changes
+that the result takes the change from a single original verbatim.  The
+"dense combined" format (`--cc` option) removes such hunks with only
+"trivial" changes. A hunk that has only two versions (or less) in the
+original (in a usual two-parent merge, this always is the case, simply
+because there are only two originals) and whose result matches exactly one
+of the originals, is considered "trivial" and is omitted from the output
+in the "dense combined" format.  In the previous illustration of a
+combined diff on `describe.c` file, there are two originals, one that had
+the describe function with a single `char *arg` parameter, and the other
+with two parameters, but the result matches neither of them, hence it is
+not "trivial" and the hunk appears in the output.
+
+