Re: [PATCH 1/2] diff-merges: improve --diff-merges documentation

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

Sergey Organov <sorganov@gmail.com> writes:

>> It is more like that `-p` does not imply `-m` (which used to mean
>> "consider showing the comparison between parent(s) and the child,
>> even for merge commits"), even though newer options like `-c`,
>> `--cc` and others do imply `-m` (simply because they do not make
>> much sense if they are not allowed to work on merges) that may make
>> new people confused.
>
> No, neither --cc nor -c imply -m.

I was only trying to help you polish the text you added to explain
what you called the "legacy feature" to reflect the reason behind
that legacy.  As you obviously were not there back then when I made
"--cc" imply "-m" while keeping "-p" not to imply "-m".

Our "git log [--diff-output-options]" logic was (and still is) not
to show the comparison between parents and the child by default for
merge commits even with -p/--raw/--stat (these were what existed and
were common back then) and "git log --raw/--stat/-p" showed the
raw/diffstat/patch after the log message for one-parent commits but
only the log message for merges.

The reason behind that design choice is that Linus (and I and
others) did not find that the patches for merges are as useful as
patches for regular commits.  We made "git log -p" to omit
patches for merges that tend to become large.

	Side note: the first-parent patch is sort of readable, but
	if you are not doing the "--first-parent" traversal (which
	is a much later invention, so it wasn't even an option), you
	are showing individual commits and their patches while
	traversing the side branch, then the first-parent patch of a
	merge amounts to the squash of individual changes on the
	side branch that got merged.  It was deemed redundant
	presentation that is just wasteful and harder to grok than
	reading individual commits.  Worse, the patch against second
	and later parent(s) have no real value (it shows how behind
	the fork point of the side branch was relative to the tip of
	the trunk, which is rarely useful).

But we also wanted to have a mode of "git log -p" that spews
everything to the output that could be used to reconstruct the
history, hence we added "-m" to tell "git log":

	By default, you are designed not to show comparison between
	parents and the child for merge commit.  But when "-m" is
	given, do show the comparison for merge commit in the format
	that other options given to you, like --raw, --patch,
	specifies.

We however didn't have a good idea how to represent such a
comparison between parents and the child, so we chose the most
redundant, verbose, and obvious, which is N pairwise patches with
each of N parents to the child (for a N-parent patch).

Later "--cc" and "-c" came as an alternative way to represent
comparison between parents and the child.

Given that I, together with Linus, invented "--cc" and "-c", taking
inspiration from how Paul Mackerras showed a merge in his 'gitk'
tool, and made the design decision not to require "-m" to get the
output in the format they specify when the "git log" traversal shows
merge commits, I do not know what to say when you repeat that "--cc"
does not imply "-m".  It simply is not true.

I think this is the second time you claimed the above after I
explained the same to you, if I am not mistaken.  If you do not want
to be corrected, that is fine, and I'll stop wasting my time trying
to correct you.

But I still have to make sure that you (or anybody else) do not
spread misinformation to other users by writing incorrect statements
in documentation patches.