From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Sun, 06 Sep 2026 13:37:55 GMT
Subject: Re: [PATCH 3/3] format-patch: learn --[no-]range-diff-notes
Message-ID: <CALnO6CA-6m58sJCf=5_GwK3GE8=EfhzgsheWBqMQjc0r+N7+Xg@mail.gmail.com>
In-Reply-To: <e3b7ef75-08e6-4529-ac75-56f800d2f4a4@app.fastmail.com>

On Sun, Sep 6, 2026 at 3:23 AM Kristoffer Haugsbakk
<kristofferhaugsbakk@fastmail.com> wrote:
>
> On Wed, Sep 2, 2026, at 15:19, Kristoffer Haugsbakk wrote:
> > On Fri, Aug 28, 2026, at 19:13, Junio C Hamano wrote:
[snip]
> >> That is fine by me.  I was hoping that you'd come up with a way to
> >> add this new option with simpler-to-explain interactions.  E.g.,
> >> when only --notes exists on the command line, it is used as the
> >> material compared by the range-diff and as the material inserted
> >> into the final output, but when both options exist, they work
> >> independently, i.e., --notes gets used only as the final output,
> >> while --range-diff-notes gets used only for comparison material,
> >> or something like that.
> >
> > This is how it works. The `--range-diff-notes` behavior that the doc
> > discusses is just the special case when the list of notes for the range
> > diff is empty.
> >
> > That this wasn’t clear is the fault of the doc here.
>
> Seeing as how the doc was unclear and did not spell out how you can
> build two separate list of notes, here’s a draft of a rewrite:
>
>     `--range-diff-notes[=<ref>]`::
>     `--no-range-diff-notes`::
>             Used with `--range-diff`, tweak what notes to display in the
>             range diff.
>     +
>     The default behavior is to display the same notes in the range diff as
>     on the patches; see `--notes`. But you can use these options to use a
>     different list of notes. For example, say you have given three notes
>     refs to `--notes`. At this point those same three notes will be
>     displayed in the range diff. But then you pass
>     `--range-diff-notes=<ref>`. Now the range diff will only display
>     _<ref>_. You can of course pass more refs to this option, just like
>     `--notes`. And you can also turn off all notes with
>     `--no-range-diff-notes`.
>     +
>     You may want to turn off this notes override behavior after it has been

[nit: should we call this "no notes" override behavior? Otherwise I
think we are referring to --range-diff-notes=<ref> overriding
--notes=…]

>     activated. Use this sequence to do that:
>     +
>     ----
>     --no-range-diff-notes --range-diff-notes
>     ----
>     +
>     Now the range diff is back to displaying the same notes as the
>     patches. Going back to the three `--notes` example: now the range diff
>     will show all three notes again.

A bit long, but easy to follow and understand the interactions, I
think. The examples are helpful.

-- 
D. Ben Knoble