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

From: Sergey Organov <sorganov@gmail.com>
Date: Sep 19, 2023, 19:52 UTC
Message-ID: <87il86q6sq.fsf@osv.gnss.ru>
In-Reply-To: <xmqqh6nqgltw.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 23 quoted lines

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

Well, to me this piece looks much harder to understand than current Git documentation, and then seemingly contradicts current Git behavior and implementation, as "log --cc -m" is not the same as "log --cc" in the current Git (so we can't say that --cc implies -m), and "log -m --cc" is the same as "log --cc" due to absolutely different reason: -m and --cc are mutually exclusive options, so the last one simply takes precedence.

In the current Git, as documented, -m just produces separate diff with respect to every parent. Simple and straightforward. Users don't need to learn about --cc, -c, --raw, --stat... to figure what -m does and if it's what they need. Unfortunately they still need to learn about -p, but I'm already done trying to promote this simple change.

Show 20 quoted lines

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

I admit you are very creative producing these views,, but currently these options just imply -p. Simple to understand, useful, works.

Overall, as you don't like my simple clarification, and I don't like the direction(s) you propose, I figure I rather withdraw the part of patch causing contention in the re-roll.

Thanks, -- Sergey Organov