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

From: Elijah Newren <newren@gmail.com>
Date: Oct 7, 2023, 01:31 UTC
Message-ID: <CABPp-BGxVnhnmoajWyqY_gMvQ42W5S6VX5EOXq3PW=GLVQwe0g@mail.gmail.com>
In-Reply-To: <xmqq7cnzaav0.fsf@gitster.g>

On Fri, Oct 6, 2023 at 11:01 AM Junio C Hamano <gitster@pobox.com> wrote:

Show 20 quoted lines

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

The problem is it's really hard for me to come up with an answer to that, in part because...

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

In my opinion, --remerge-diff does this better; wouldn't we want a rationale where these particular modes shine? Is that a non-empty set? (It may well be, but to me, --cc was never worse than -c while often being better, and likewise, --remerge-diff is never worse than --cc while often being better, at least on anything I had thought to use any of these for. Maybe there are other usecases for -c and --cc I'm just not thinking of?)