From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Sun, 06 Sep 2026 07:22:27 GMT
Subject: Re: [PATCH 3/3] format-patch: learn --[no-]range-diff-notes
Message-ID: <e3b7ef75-08e6-4529-ac75-56f800d2f4a4@app.fastmail.com>
In-Reply-To: <b3c66de3-0ced-446f-9bd6-73412a8c92b5@app.fastmail.com>

On Wed, Sep 2, 2026, at 15:19, Kristoffer Haugsbakk wrote:
> On Fri, Aug 28, 2026, at 19:13, Junio C Hamano wrote:
>> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>>
>>>> I do not know.  My preference actually is not to introuce a new
>>>> option whose interaction with the existing --notes option cannot be
>>>> defined in simple terms.
>>>
>>> Let's drop this topic then.
>>
>> 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
    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.