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

From: Elijah Newren <newren@gmail.com>
Date: Oct 9, 2023, 17:04 UTC
Message-ID: <CABPp-BGL_QzRd3mRhSF7rHYNA4pFWfKPA+UuZDODFgEv-1BHhA@mail.gmail.com>
In-Reply-To: <xmqqmswv3p11.fsf@gitster.g>

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

Show 12 quoted lines

>
> Junio C Hamano <gitster@pobox.com> writes:
>
> > Elijah Newren <newren@gmail.com> writes:
> >
> >> In my opinion, --remerge-diff does this better; wouldn't we want a
> >> ...
> > Between -c and --cc, I do not think there is anything that makes us
> > favor -c over --cc.  While the algorithm to decide which hunks out
> > of -c's output to omit was being polished, comparison with -c served
> > a good way to give baseline, but once --cc has become solid, I do
> > not think I've used -c myself.

Perhaps, then, the user manual should either omit -c, or recommend users use --cc instead?

> > I personally find that a very trivial merge resolution is far easier
> > to read with --cc than --remerge-diff, the latter being way too
> > verbose.

Ah, indeed, for those that know the --cc output format well (it takes a bit to figure out for newcomers), your example demonstrates this nicely. Thanks.

Show 5 quoted lines

> > Also, --cc and -c should work inside a read-only repository where
> > you only have read access to.  If remerge needs to write some
> > objects to the repository, then you'd need some hack to give a
> > writable object store overlay via the alternate odb mechanism, or
> > something, right?

Well, it does use a temporary object store with the alternate odb mechanism already, but I don't think there's any code to allow the user to input the location for the temporary store, and thus we'd probably attempt to write it underneath the same read-only directory. So, yes, read-only repositories would likely be problematic for --remerge-diff.

However, are read-only repositories worth mentioning in the documentation here?

Show 16 quoted lines

> Well, the above did not come out as well as I intended, as I forgot
> to prefix it with something I thought was obvious from what I said
> in the recent discussion in the earlier iteration of this topic,
> where I said that it would be "--remerge-diff", if I were to pick an
> option that is so useful that it deserves short and sweet single
> letter.  Narutally, it came after we gained experience with "--cc",
> so it would be surprising if it did worse.  Just like it is natural
> to expect that "--cc" would give more useful output than "-m -p"
> that predates everybody else.
>
> In short, I would say "--remerge-diff" would give output that is the
> easiest to grok among the three modern variants to show the changes
> a merge introduces.
>
> The above two cases, where I said cc does better than remerge-diff,
> were meant as _exceptions_ for that general sentiment.

Thanks, this is useful. This does make me wonder, though: Should we perhaps guide users as to what we recommend (and recommend against) in this documentation?

If we have lots of options and they all shine on different usecases, it makes sense to just provide a long list of possibilities for users. But if we generally feel that one is entirely supplanted by another (e.g. -c by --cc) it seems beneficial to mention that, and if we generally feel that one will often be clearer or more useful than the others (e.g. --remerge-diff), it seems beneficial to recommend it. Thoughts?

Also, perhaps this would be best to include in a follow-up series (as it appears from Sergey's latest iteration that we are leaving other tweaks for a later series anyway), if we do decide we want to do it...