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

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

Sergey Organov <sorganov@gmail.com> writes:

> Junio C Hamano <gitster@pobox.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".
>
> Your help is appreciated, yet unfortunately I still can't figure how to
> improve the text based on your advice.

If I were doing this patch, I would start from something like this:

-m::
	By default, comparisons between parent commits and the child
	commit are not shown for merge commits, but with the `-m`
	option, `git log` can be told to show comparisons for merges
	in chosen formats (e.g. `--raw`, `-p`, `--stat`).  When
	output formats (e.g. `--cc`) that are specifically designed
	to show better comparisons for merges are given, this option
	is implied; in other words, you do not have to say e.g. `git
	log -m --cc`.  `git log --cc` suffices.


The rest is a tangent that is not related to the above.  I suspect
that this also applies to newer `--remerge-diff`, as it also targets
to show merges better than the original "pairwise patches" that were
largely useless, but the right way to view what `--cc` and other
formats do for non-merge commits is *not* to think that they "imply"
`-p`.  It is more like that the output from these formats on
non-merge commits happen to be identical to what `-p` would produce.
You could say that the "magic" these options know to show merge
commits better degenerates to what `-p` gives when applied to
non-merge commits.

Another way to look at it is that `--cc` and friends, even though
they are meant as improvements for showing merges over "-m -p" that
gives human-unreadable pair-wise diffs, do not imply "--merges"
(i.e. show only merge commits)---hence they have to show something
for non-merge commits.  Because output formats for all of them were
modeled loosely [*] after "-p" output, we happened to pick it as the
format they fall back to when they are not showing comparisons for
merge commits.


[Footnote]

 * Here, `-p` roughly means "what GNU patch and `git apply` take".
   Output from `-c` and `--cc` on merge commits do not qualify, but
   they are loosely modeled after it.