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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 6, 2023, 23:19 UTC
Message-ID: <xmqqv8bj5ofq.fsf@gitster.g>
In-Reply-To: <875y3jr42h.fsf@osv.gnss.ru>

Sergey Organov <sorganov@gmail.com> writes:

Show 31 quoted lines

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Elijah Newren <newren@gmail.com> writes:
>>
>>>> > +--cc::
>>>> > +     Produce dense combined diff output for merge commits.
>>>> > +     Shortcut for '--diff-merges=dense-combined -p'.
>>>>
>>>> Good.
>>>>
>>>> > +--remerge-diff::
>>>> > +     Produce diff against re-merge.
>>>> > +     Shortcut for '--diff-merges=remerge -p'.
>>>> ...
>>> Perhaps:
>>>
>>> Produce remerge-diff output for merge commits, in order to show how
>>> conflicts were resolved.
>>
>> I do not mind it, but then I'd prefer to see ", in order to show
>> how" also in the description of "--cc" and "-c" for consistency.
>>
>> A succinct way to say what they do may be hard to come by, but I
>> think of them showing places that did not have obvious natural
>> resolution.
>
> So, is it OK with both of you if I leave it as:
>
> "Produce remerge-diff output for merge commits."
>
> for now, and let you tweak the descriptions later on, if needed?

I do not know what Elijah would say, but in one of iterations of my draft response to him indeed suggested that "in order to" here is not necessary if it is described for the "--diff-merges=remerge" option, because those who know enough to skip referring to the other entry are expected to know why it exists. So I think I am OK with that.

Thanks.