Subject: Re: [PATCH v1 24/27] doc/git-log: describe new --diff-merges options

From: Sergey Organov <[email-masked]>
Date: Fri, 04 Dec 2020 20:34:17 +0300

Elijah Newren <[email-masked]> writes:

> On Thu, Dec 3, 2020 at 11:34 AM Sergey Organov <[email-masked]> wrote:
>>
>> Elijah Newren <[email-masked]> writes:

[...]

>> >> ++
>> >> +--diff-merges=(off|none):::
>> >> +--no-diff-merges:::
>> >> +       (default) Disable output of diffs for merge commits. Useful to
>> >> +       override implied value.
>> >> ++
>> >> +--diff-merges=first-parent:::
>> >> +       This option makes merge commits show the full diff with
>> >> +       respect to the first parent only, exactly like  regular
>> >> +       commits.
>> >
>> > Not sure that "exactly like regular commits" is helpful here; I'd
>> > personally rather cut those four words out.  I'm worried it'll be
>> > taken not as an implementation explanation, but as a "this treats
>> > merge commits in the natural way that regular commits are" which users
>> > may mistakenly translate to "it shows what changes the user manually
>> > made as part of the commit" which is not at all the correct mapping.
>>
>> Dunno. Don't have strict preference here. Git has no idea how the
>> changes in a commit have been made in the first place. Changes are just
>> changes.
>
> If you don't have a preference, can we drop those four words?  ;-)

Yeah, sure, dropped.

>
>> To my excuse, I took this from git:5fbb4bc191 that has:
>>
>> +Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits
>> +will never show a diff, even if a diff format like `--patch` is
>> +selected, nor will they match search options like `-S`. The exception is
>> +when `--first-parent` is in use, in which merges are treated like normal
>> +single-parent commits (this can be overridden by providing a
>> +combined-diff option or with `--no-diff-merges`).
>
> Yeah, I can see where you're coming from, though the context change
> feels like just enough different that the four words you added bother
> me a bit more.  However, this existing wording does bother me now that
> you highlight it.  Even though it's not something introduced by your
> patch, I'd really like to drop "normal" here; I think it is prone to
> cause confusion to users and as far as I can tell provides no useful
> meaning for the sentence.  (There are multiple types of single-parent
> commits?  What is an "unnormal" one?  How do I tell which kind I want?
>  etc...).

I see your point, but I won't change it in these series. I think that
it'd be better if you change this yourself, independently.

Thanks,
-- 
Sergey Organov