Re: [PATCH 3/3] format-patch: learn --[no-]range-diff-notes

On Sun, Sep 6, 2026 at 3:23 AM Kristoffer Haugsbakk
[off-list ref] wrote:

On Wed, Sep 2, 2026, at 15:19, Kristoffer Haugsbakk wrote:

quoted

On Fri, Aug 28, 2026, at 19:13, Junio C Hamano wrote:

[snip]

quoted

quoted

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