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

Junio C Hamano [off-list ref] writes:

Sergey Organov [off-list ref] writes:

quoted

Junio C Hamano [off-list ref] writes:

quoted

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.

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