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

Sergey Organov <sorganov@gmail.com> writes:

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.