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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 19, 2023, 16:38 UTC
Message-ID: <xmqqh6nqgltw.fsf@gitster.g>
In-Reply-To: <87v8c7mp1j.fsf@osv.gnss.ru>

Sergey Organov <sorganov@gmail.com> writes:

Show 9 quoted lines

> 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.