Re: Combined diff format documentation

[Junio C Hamano <junkio@cox.net>]

Jakub Narebski <jnareb@gmail.com> writes:

> Well, the _documentation_ doesn't tell. I haven't fully grokked the code
> for generating and coloring combined diff output besides the fact that
> I think it uses last indicator ('+' or '-') to chose color for the rest
> of line. You said that even if the possibility exist, it is extreme
> unlikely.

Well if I said that I must have been on booze ;-).

A '-' in the nth column means that the line is from the nth
parent and does _not_ appear in the merge result.  A '+' in the
nth column means that the line _appears_ in the merge result,
and the nth parent does not have that line (i.e. added by the
merge itself, or inherited from other parents).

Hence, by definition, you cannot have '-' and '+' on the same
line (otherwise the line has to exist and not exist in the merge
result at the same time).

A ' ' is a bit tricky to interpret.  A ' ' on a line _without_
any '-' means the line is the same as in that parent and the
merge result (i.e. the result inherited the line from that
parent).  A ' ' on a line that has '-' talks nothing about the
merge result (because by definition '-' lines do not exist in
the merge result) nor the parent that has ' '; in other words,
it is a "don't care" bit.  In the example you quoted from the
commit log of af3feefa:

         - static void describe(char *arg)
          -static void describe(struct commit *cmit, int last_one)
         ++static void describe(char *arg, int last_one)
           {

The first parent had it as one-arg function, and the second one
two-arg but the first parameter was of type "struct commit *";
the merge result has it as two-arg with the first parameter of
type "char *".  The second parent does not know about the
one-arg form of the function so it has ' ' in its column for the
first line.

All versions start the function with an opening brace '{' so the
line has two ' ' prefixed, which is an example of ' ' on a line
without any '-'.