From: Kristoffer Haugsbakk Date: Sun, 06 Sep 2026 16:44:39 GMT Subject: Re: [PATCH 3/3] format-patch: learn --[no-]range-diff-notes Message-ID: <392dc2b3-59cf-4fd4-8c73-38a57c8d0423@app.fastmail.com> In-Reply-To: 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[=]`:: >> `--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=`. Now the range diff will only display >> __. 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= 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