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

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

On Sun, Sep 6, 2026, at 15:37, D. Ben Knoble wrote:
> On Sun, Sep 6, 2026 at 3:23 AM Kristoffer Haugsbakk
>> >[snip]
>> > 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=…]

(I will shorten `range-diff` to `RD` for semi-brevity)

What I mean here by “notes override behavior” is turning off all
`--[no-]RD-notes` options. It means turning off `--RD-notes` as well as
`--no-RD-notes`. And without the override you are back to the default
behavior where `--notes` dictates the notes for the range diff.

So that the utility is a bit more clear than these unmotivated examples,
here’s an example alias (with forced linebreaks):

    my-fp = format-patch --notes=review --notes=testing
        --notes=attribution --notes=changelog
        --range-diff-notes=changelog

The patches will have four notes while the range diff will have one.

But you may want to disregard that last `--RD-notes` and in turn get all
of the notes in the range diff. But without repeating yourself. Then you
can do this:

    my-fp --no-range-diff-notes --range-diff-notes

The option (the negation) is not sufficient since it would turn off all
range diff notes. But this special meaning of `--RD-notes` allows you to
go back to just regular `--notes` behavior. That `--RD-notes` has a
special meaning when the list of range diff notes is empty does not lose
anything since `--range-diff-notes` would just be a noöp otherwise.[1]

But I should point out in this doc that bare `--RD-notes` does not use
the default notes.

Of course, there could be a dedicated option to turn these options off.

Or to just not support it. ;)

(my standard verbosity level might not be doing me any favors
on this point.)

***

That might seem like a lot of “power” for something as niche as
overriding-then-reverting patch contra range diff notes. But code
wise I don’t think the price is high... :)

† 1: I just tested the behavior of `--notes` (no arg) on
     `format-patch`. Yes, it does respect the default notes ref just
     like git-log(1) does. So an alternative would be to have
     `--RD-notes` do the same.

     But I do not think some convenient default notes ref is good for a
     command which is supposed to generate patches for email
     sendout. For `log` you can make convenient notes to yourself and
     conveniently display them. But `format-patch` should demand more
     intentionality. (I also wrote about this on a bugfix for
     `format-patch` behavior some years ago.)[2]
† 2: I suspect there is a bug-looking like behavior in that
     `format-patch` seems to use `notes.displayRef` for the default
     notes (not just /refs/notes/commits). It should just respect
     `format.notes`, I think. But I can look at that later.

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

Thanks. I noticed the lines kept creeping up, but it is more involved
than most options; an option for passing on to another command which
also overrides the behavior of another option.

Thanks for taking a look at this niche topic. Though I see that you are
one of the dozen of us[3] who use Git notes on his submissions. ;)

🔗 3: https://lore.kernel.org/git/CV_format-patch_learn_--range-diff-notes.c57@msgid.xyz/T/#m6a7cbbe0fc456e7e62125d903b706ae5a547315b