From: Sergey Organov <sorganov@gmail•com>
To: Junio C Hamano <gitster@pobox•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 1/2] diff-merges: improve --diff-merges documentation
Date: Mon, 18 Sep 2023 19:20:08 +0300 [thread overview]
Message-ID: <87v8c7mp1j.fsf@osv.gnss.ru> (raw)
In-Reply-To: <xmqqcyymly5m.fsf@gitster.g> (Junio C. Hamano's message of "Tue, 12 Sep 2023 17:22:45 -0700")
Junio C Hamano <gitster@pobox•com> writes:
> 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?
[...]
>
> 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.
>
> 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
next prev parent reply other threads:[~2023-09-18 16:26 UTC|newest]
Thread overview: 55+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-09-09 12:54 [PATCH 0/2] diff-merges: introduce '-d' option Sergey Organov
2023-09-09 12:54 ` [PATCH 1/2] diff-merges: improve --diff-merges documentation Sergey Organov
2023-09-11 21:12 ` Junio C Hamano
2023-09-12 7:37 ` Sergey Organov
2023-09-13 0:22 ` Junio C Hamano
2023-09-18 16:20 ` Sergey Organov [this message]
2023-09-19 16:38 ` Junio C Hamano
2023-09-19 19:52 ` Sergey Organov
2023-09-09 12:54 ` [PATCH 2/2] diff-merges: introduce '-d' option Sergey Organov
2023-09-11 21:01 ` Junio C Hamano
2023-09-12 7:59 ` Sergey Organov
2023-09-14 22:17 ` Junio C Hamano
2023-09-14 23:56 ` Sergey Organov
2023-09-15 17:24 ` Junio C Hamano
2023-09-16 18:37 ` Sergey Organov
2023-09-26 2:50 ` Junio C Hamano
2023-09-26 9:04 ` Sergey Organov
2023-09-26 17:08 ` Junio C Hamano
2023-09-26 20:05 ` Sergey Organov
2023-09-20 15:02 ` [PATCH v2 0/2] " Sergey Organov
2023-09-20 15:02 ` [PATCH v2 1/2] diff-merges: improve --diff-merges documentation Sergey Organov
2023-09-20 15:02 ` [PATCH v2 2/2] diff-merges: introduce '-d' option Sergey Organov
2023-10-04 21:45 ` [PATCH v3 0/3] diff-merges: introduce '--dd' option Sergey Organov
2023-10-04 21:45 ` [PATCH v3 1/3] diff-merges: improve --diff-merges documentation Sergey Organov
2023-10-04 22:02 ` Eric Sunshine
2023-10-04 22:13 ` Sergey Organov
2023-10-05 21:11 ` Junio C Hamano
2023-10-06 17:02 ` Sergey Organov
2023-10-05 21:24 ` Junio C Hamano
2023-10-06 14:41 ` Elijah Newren
2023-10-06 17:03 ` Sergey Organov
2023-10-06 17:07 ` Sergey Organov
2023-10-06 18:01 ` Junio C Hamano
2023-10-06 18:36 ` Sergey Organov
2023-10-06 23:19 ` Junio C Hamano
2023-10-07 1:31 ` Elijah Newren
2023-10-07 1:50 ` Junio C Hamano
2023-10-07 6:49 ` Junio C Hamano
2023-10-09 17:04 ` Elijah Newren
2023-10-10 0:24 ` Junio C Hamano
2023-10-10 2:44 ` [silly] worldview documents? Junio C Hamano
2023-10-10 14:58 ` Emily Shaffer
2023-10-06 17:18 ` [PATCH v3 1/3] diff-merges: improve --diff-merges documentation Sergey Organov
2023-10-06 18:42 ` Sergey Organov
2023-10-04 21:45 ` [PATCH v3 2/3] diff-merges: introduce '--dd' option Sergey Organov
2023-10-05 21:45 ` Junio C Hamano
2023-10-06 17:05 ` Sergey Organov
2023-10-04 21:45 ` [PATCH v3 3/3] completion: complete '--dd' Sergey Organov
2023-10-05 21:45 ` Junio C Hamano
2023-10-06 18:53 ` Sergey Organov
2023-10-09 16:05 ` [PATCH v4 0/3] diff-merges: introduce '--dd' option Sergey Organov
2023-10-09 16:05 ` [PATCH v4 1/3] diff-merges: improve --diff-merges documentation Sergey Organov
2023-10-09 16:05 ` [PATCH v4 2/3] diff-merges: introduce '--dd' option Sergey Organov
2023-10-09 16:05 ` [PATCH v4 3/3] completion: complete '--dd' Sergey Organov
2023-10-09 20:02 ` [PATCH v4 0/3] diff-merges: introduce '--dd' option Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87v8c7mp1j.fsf@osv.gnss.ru \
--to=sorganov@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox