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

From: Sergey Organov <sorganov@gmail.com>
Date: Sep 18, 2023, 16:20 UTC
Message-ID: <87v8c7mp1j.fsf@osv.gnss.ru>
In-Reply-To: <xmqqcyymly5m.fsf@gitster.g>

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

Show 15 quoted lines

> Sergey Organov <sorganov@gmail.com> writes:
>
>>> It is more like that `-p` does not imply `-m` (which used to mean
>>> "consider showing the comparison between parent(s) and the child,
>>> even for merge commits"), even though newer options like `-c`,
>>> `--cc` and others do imply `-m` (simply because they do not make
>>> much sense if they are not allowed to work on merges) that may make
>>> new people confused.
>>
>> No, neither --cc nor -c imply -m.
>
> 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.

Your "I made --cc imply -m" does not explain why later, when you made --cc imply -p (did you, or was it somebody else?), you didn't make -m imply -p at the same time, and then "while keeping -p not to imply -m" sounds out of place as we rather try to figure why "-m not implies -p".

The "--c imply -m" part of the help raises yet another question: if --cc implied -m, why it was not -m that was made to imply -p instead of --cc (and -c)? Then both --cc and -c would imply -p automatically as a side-effect of implication of -p by -m (do not confuse with agreed non-implication of -m by -p), and then all the relevant options were consistent. This consideration renders current situation more surprising instead of clarifying it, I'm afraid.

"-p does not imply -m" fact is fine with me and is not the cause of user confusion I'm trying to address. How does it help us to explain why "-m does not imply -p" though?

[...]

Show 7 quoted lines

>
> 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 keep saying "--cc does not imply -m" because it does not seem to, unless you either use some vague meaning of "imply", or mean some other "-m", not the one used in "git log". Please check:

$ cd src/git $ git --version git version 2.42.0.111.gd814540bb75b $ git describe v2.42.0-111-gd814540bb75b $ git log 74a2e88700efc -n1 -p --cc > diff.actual $ git log 74a2e88700efc -n1 -p --cc -m > diff.expected $ cmp diff.expected diff.actual diff.expected diff.actual differ: byte 706, line 18 $

This test tells us that "--c" is not the same as "--cc -m", that for me in turn reads "--cc does not imply -m", and that's what I continue to say.

Show 5 quoted lines

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

I'd love to be corrected, but I think I carefully checked my grounds before saying that --cc does not imply -m, please consider:

1. "--cc implies -m" is not documented. Please point to the
   documentation in case I missed it.

2. Git does not behave as if "--cc implied -m", see the test-case above.

If it's neither documented nor matches actual behavior, it's not there, at least from the POV of random user, to whom my original clarification of "why -m does not imply -p?" has been addressed.

On top of that, I even can't figure why we argue about it in the first place, as it seems to be irrelevant to the issue at hand: explain why -m does not imply -p?

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

I'm all against spreading misinformation, and try my best to avoid it myself. I still fail to see what misinformation, exactly, you find in this particular explanation by me:

" Note: This option [`-m`] not implying `-p` is legacy feature that is
  preserved for the sake of backward compatibility. "

That's exactly what I figured out from a lot of discussions over my multiple attempts to make `-m` behave more usefully. Is it that "legacy feature" somehow sounds offensive, or what?

As, despite your help, I fail to come up with better edition of the note, please, if you feel like it, suggest your own variant of explanation to the user why `-m` is left inconsistent with the rest of diff for merges options, provided current matching documentation reads roughly like this (from more recent options to oldest):

   --remrege-diff: produces "remerge" output. Implies -p.
   --cc: produces dense combined output. Implies -p.
   -c: produces combined output. Implies -p.
   -m: produces separate output, provided -p is given as well (?!).

and so why

  git log -m

surprisingly has no visible effect, and then the user needs to type:

   git log -m -p

That's all I wanted to explain to the user in a few words with the note you argue against.

Thanks, -- Sergey Organov