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

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name: kh/format-patch-range-diff-notes

Topic summary: Teach 'format-patch' options to tweak notes output in the
range diff independent of what notes are output in the patches.

See patch 3/3 for details.

This is motivated by wanting to turn off range diff notes, but the goal
here is to implement it in full generality.

(How many of us `git format-patch --notes` users are there out there? More
than a dozen?)

I have implemented this behavior for myself and used it for many
months. But that was hacky and only suitable for one person’s use.
So this is a completely new implementation. In other words: this is
new code, *not* tested for months.

§ CI

https://github.com/LemmingAvalanche/git/actions/runs/32762207178

I seem to have finally learned now that I ought to push to my public Git
tree for CI, not my private one. The latter seems to consistently give me
“insufficient funds” errors. But I don’t know.

[1/3] format-patch: simplify get_notes_arg parameters
[2/3] revision.h: rename struct member to reflect notes role
[3/3] format-patch: learn --[no-]range-diff-notes

 Documentation/git-format-patch.adoc |  17 +++++
 builtin/log.c                       |  21 +++---
 log-tree.c                          |   2 +-
 revision.c                          |  13 ++++
 revision.h                          |   9 ++-
 t/t3206-range-diff.sh               | 105 ++++++++++++++++++++++++++++
 6 files changed, 156 insertions(+), 11 deletions(-)


base-commit: 1a3e64c6c4a623626ff0687008732a8e007e2a1c
-- 
2.55.0.13.g85d2d65e389

[PATCH 1/3] format-patch: simplify get_notes_arg parameters

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

85bd88a7 (revision: add rdiff_log_arg to rev_info, 2025-09-25) added
`rdiff_log_arg` to `struct rev_info`. I changed `get_notes_arg` by
simply replacing the first argument with an access on this struct
member. But the second argument was already `struct rev_info`. So I
should have just simplified to *only* passing that parameter. Let’s do
that now.

Now is also a good time to format this `for_each...` line since it’s
gotten quite long.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (testing):
    just compile tested

 builtin/log.c | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/builtin/log.c b/builtin/log.c
index 350b35c5563..560af00e2fd 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -1333,16 +1333,18 @@ static int get_notes_refs(struct string_list_item *item, void *arg)
 	return 0;
 }
 
-static void get_notes_args(struct strvec *arg, struct rev_info *rev)
+static void get_notes_args(struct rev_info *rev)
 {
 	if (!rev->show_notes) {
-		strvec_push(arg, "--no-notes");
+		strvec_push(&rev->rdiff_log_arg, "--no-notes");
 	} else if (rev->notes_opt.use_default_notes > 0 ||
 		   (rev->notes_opt.use_default_notes == -1 &&
 		    !rev->notes_opt.extra_notes_refs.nr)) {
-		strvec_push(arg, "--notes");
+		strvec_push(&rev->rdiff_log_arg, "--notes");
 	} else {
-		for_each_string_list(&rev->notes_opt.extra_notes_refs, get_notes_refs, arg);
+		for_each_string_list(&rev->notes_opt.extra_notes_refs,
+				     get_notes_refs,
+				     &rev->rdiff_log_arg);
 	}
 }
 
@@ -2404,7 +2406,7 @@ int cmd_format_patch(int argc,
 		rev.rdiff_title = diff_title(&rdiff_title, reroll_count,
 					     _("Range-diff:"),
 					     _("Range-diff against v%d:"));
-		get_notes_args(&(rev.rdiff_log_arg), &rev);
+		get_notes_args(&rev);
 	}
 
 	/*
-- 
2.55.0.13.g85d2d65e389

[PATCH 2/3] revision.h: rename struct member to reflect notes role

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The `struct rev_info` member `rdiff_log_arg` is only used to pass
`--[no-]notes` options to git-range-diff(1), which in turn passes it
on to git-log(1). The “log” in the name is fine since other code paths
could choose to use it to pass something else on to git-range-diff(1)
(as long as it makes sense to git-log(1)). However, we will in the next
commit change `revision.c:handle_revision_opt` to push and clear this
`strvec` based on notes options that the user passes. That means that
only one type of git-log(1) option will be suitable for it. So let’s
rename it to `rdiff_notes_arg`.

This structure member got its “log” name in 85bd88a7 (revision: add
rdiff_log_arg to rev_info, 2025-09-25), which was based on the renaming
of the `range-diff.c` variable `other_arg` to `log_arg`.[1] Now, in
`range-diff.c` this `log_arg` really is used for multiple different
git-log(1) options, namely `--[no-]notes` and `--remerge-diff`. But we
can keep this `rev_info` member notes-only.

† 1: in 71fd6c69 (range-diff: rename other_arg to log_arg, 2025-09-25)

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (testing):
    just compile tested

 builtin/log.c | 10 +++++-----
 log-tree.c    |  2 +-
 revision.h    |  4 ++--
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/builtin/log.c b/builtin/log.c
index 560af00e2fd..28a93c45463 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -1336,15 +1336,15 @@ static int get_notes_refs(struct string_list_item *item, void *arg)
 static void get_notes_args(struct rev_info *rev)
 {
 	if (!rev->show_notes) {
-		strvec_push(&rev->rdiff_log_arg, "--no-notes");
+		strvec_push(&rev->rdiff_notes_arg, "--no-notes");
 	} else if (rev->notes_opt.use_default_notes > 0 ||
 		   (rev->notes_opt.use_default_notes == -1 &&
 		    !rev->notes_opt.extra_notes_refs.nr)) {
-		strvec_push(&rev->rdiff_log_arg, "--notes");
+		strvec_push(&rev->rdiff_notes_arg, "--notes");
 	} else {
 		for_each_string_list(&rev->notes_opt.extra_notes_refs,
 				     get_notes_refs,
-				     &rev->rdiff_log_arg);
+				     &rev->rdiff_notes_arg);
 	}
 }
 
@@ -1475,7 +1475,7 @@ static void make_cover_letter(struct rev_info *rev, int use_separate_file,
 			.dual_color = 1,
 			.max_memory = RANGE_DIFF_MAX_MEMORY_DEFAULT,
 			.diffopt = &opts,
-			.log_arg = &rev->rdiff_log_arg
+			.log_arg = &rev->rdiff_notes_arg
 		};
 
 		repo_diff_setup(the_repository, &opts);
@@ -2569,7 +2569,7 @@ int cmd_format_patch(int argc,
 	rev.diffopt.no_free = 0;
 	release_revisions(&rev);
 	format_config_release(&cfg);
-	strvec_clear(&rev.rdiff_log_arg);
+	strvec_clear(&rev.rdiff_notes_arg);
 	return 0;
 }
 
diff --git a/log-tree.c b/log-tree.c
index 83a3c4bf9b1..fd6ddf32af4 100644
--- a/log-tree.c
+++ b/log-tree.c
@@ -718,7 +718,7 @@ static void show_diff_of_diff(struct rev_info *opt)
 			.dual_color = 1,
 			.max_memory = RANGE_DIFF_MAX_MEMORY_DEFAULT,
 			.diffopt = &opts,
-			.log_arg = &opt->rdiff_log_arg
+			.log_arg = &opt->rdiff_notes_arg
 		};
 
 		memcpy(&dq, &diff_queued_diff, sizeof(diff_queued_diff));
diff --git a/revision.h b/revision.h
index acf6d06b241..39cca04d9e5 100644
--- a/revision.h
+++ b/revision.h
@@ -351,7 +351,7 @@ struct rev_info {
 	/* range-diff */
 	const char *rdiff1;
 	const char *rdiff2;
-	struct strvec rdiff_log_arg;
+	struct strvec rdiff_notes_arg;
 	int creation_factor;
 	const char *rdiff_title;
 
@@ -432,7 +432,7 @@ struct rev_info {
 	.expand_tabs_in_log = -1, \
 	.commit_format = CMIT_FMT_DEFAULT, \
 	.expand_tabs_in_log_default = 8, \
-	.rdiff_log_arg = STRVEC_INIT, \
+	.rdiff_notes_arg = STRVEC_INIT, \
 }
 
 /**
-- 
2.55.0.13.g85d2d65e389

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

git-format-patch(1) passes on the notes behavior that it is using for
the patches to git-range-diff(1). In turn you get the same Git notes
displayed in the range diff as the ones you used to generate the
patches. And that makes sense in most cases.

However, I often make notes between series versions that mostly prepend
to the original. They end up looking like this:

    v3:
    [desc.]
    v2:
    [descr.]
    v1:
    [descr.]

These notes are meant for the git-format-patch(1) output since they
document the iterations. But including them also includes them in the
range diff. And they have nothing useful to say there.

So it would be useful to turn off range diff notes handling with
something like `--no-range-diff-notes`. This could then be turned on
again with `--range-diff-notes`.

An off/on switch is enough for this behavior. However, a bare (no arg)
option (together with the negation) is not consistent with `--[no-]notes
[=<ref>]` and could cause confusion. And we are both conceptually and
literally constructing an argument list to pass on to git-range-diff(1),
which does have the same option format as git-format-patch(1). Moreover,
it is useful to be able to specify exactly what notes you want
git-format-patch(1) and git-range-diff(1) to use.[1] So let’s generalize
it so that you can pass in whatever notes refs you want.

But now we are faced with a problem that `--notes` does not have; how do
we distinguish an empty `struct string_list` meaning these two things?:

• No such options given
• `--no-range-diff-notes`

Well, we can’t. Therefore we need `rdiff_override_notes` to set whenever
any of these options are given.

However, we may also want to turn *off* this override. Just like how we
can countermand any notes ref we pass in:

    --notes=custom --no-notes

To that end, let’s make `--range-diff-notes` when the list of options is
empty special. Then it means: go back to using whatever git-format-
patch(1) wants to use.

Now, `--notes` is a bit special in that it has an optional
argument. Implementing this with a parse-options callback is not
user-friendly; the following does *not* mean what it looks like:

    --parse-option --another-option

Namely, it is not a bare `--parse-option` followed by another
option. Rather, it’s one option:

    --parse-option=--another-option

And we need the bare `--range-diff-notes` form in order to turn off
notes overriding. For that reason, let’s implement these new options in
`revision.c:handle_revision_opt`, just like the `--notes` options are.

† 1: For example, let say we have two notes ref that are used for a
     patch series:

     1. testing. What the user has done to test this iteration.
     2. changelog. The same example from the introduction.

     You could include both notes on the patches but only show `testing` in
     the range diff.

***

Note that using `--creation-factor` without `--range-diff` will cause
the command to die. But this is not the case for `--[no-]range-diff-
notes`. Yes, we could introduce struct member `rdiff_notes_arg_used` or
something in order to detect the same condition. Or turn `rdiff_notes_
override` into a tri-state `int`. But the extra code is not worth that
in my opinion.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (testing):
    CI: https://github.com/LemmingAvalanche/git/actions/runs/32762207178

 Documentation/git-format-patch.adoc |  17 +++++
 builtin/log.c                       |   5 +-
 revision.c                          |  13 ++++
 revision.h                          |   5 ++
 t/t3206-range-diff.sh               | 105 ++++++++++++++++++++++++++++
 5 files changed, 144 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
index 191f64b77d1..e0ba435dfcf 100644
--- a/Documentation/git-format-patch.adoc
+++ b/Documentation/git-format-patch.adoc
@@ -378,6 +378,23 @@ case is to show comparison with an older iteration of the same
 topic and the tool should find more correspondence between the two
 sets of patches.
 
+`--range-diff-notes[=<ref>]`::
+`--no-range-diff-notes`::
+	Used with `--range-diff`, tweak what notes to display in the
+	range diff. For example, you can use `--no-range-diff-notes` to
+	turn off all notes in the range diff. The default behavior is
+	to display the same notes in the range diff as on the patches
+	(see `--notes`).
++
+You may want to turn off this notes override 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.
+
 `--notes[=<ref>]`::
 `--no-notes`::
 	Append the notes (see linkgit:git-notes[1]) for the commit
diff --git a/builtin/log.c b/builtin/log.c
index 28a93c45463..de997bc9ab0 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -1335,7 +1335,10 @@ static int get_notes_refs(struct string_list_item *item, void *arg)
 
 static void get_notes_args(struct rev_info *rev)
 {
-	if (!rev->show_notes) {
+	if (rev->rdiff_override_notes) {
+		if (!rev->rdiff_notes_arg.nr)
+			strvec_push(&rev->rdiff_notes_arg, "--no-notes");
+	} else if (!rev->show_notes) {
 		strvec_push(&rev->rdiff_notes_arg, "--no-notes");
 	} else if (rev->notes_opt.use_default_notes > 0 ||
 		   (rev->notes_opt.use_default_notes == -1 &&
diff --git a/revision.c b/revision.c
index 50dc8b19913..1e21f2861cc 100644
--- a/revision.c
+++ b/revision.c
@@ -2625,6 +2625,19 @@ static int handle_revision_opt(struct rev_info *revs, int argc, const char **arg
 		revs->notes_opt.use_default_notes = 1;
 	} else if (!strcmp(arg, "--no-standard-notes")) {
 		revs->notes_opt.use_default_notes = 0;
+	} else if (!strcmp(arg, "--no-range-diff-notes")) {
+		strvec_clear(&revs->rdiff_notes_arg);
+		revs->rdiff_override_notes = 1;
+	} else if (!strcmp(arg, "--range-diff-notes")) {
+		/*
+		 * Allow the user to use '--no-range-diff-notes
+		 * --range-diff-notes' in order to go back to
+		 * using the 'format-patch' notes behavior
+		 */
+		revs->rdiff_override_notes = revs->rdiff_notes_arg.nr;
+	} else if (skip_prefix(arg, "--range-diff-notes=", &optarg)) {
+		strvec_pushf(&revs->rdiff_notes_arg, "--notes=%s", optarg);
+		revs->rdiff_override_notes = 1;
 	} else if (!strcmp(arg, "--oneline")) {
 		revs->verbose_header = 1;
 		get_commit_format("oneline", revs);
diff --git a/revision.h b/revision.h
index 39cca04d9e5..e8dbf774b00 100644
--- a/revision.h
+++ b/revision.h
@@ -351,6 +351,11 @@ struct rev_info {
 	/* range-diff */
 	const char *rdiff1;
 	const char *rdiff2;
+	/*
+	 * whether to use 'rdiff_notes_arg' or inherited
+	 * notes behavior
+	 */
+	bool rdiff_override_notes;
 	struct strvec rdiff_notes_arg;
 	int creation_factor;
 	const char *rdiff_title;
diff --git a/t/t3206-range-diff.sh b/t/t3206-range-diff.sh
index ef92704de39..db238d0a5a1 100755
--- a/t/t3206-range-diff.sh
+++ b/t/t3206-range-diff.sh
@@ -845,6 +845,111 @@ test_expect_success 'format-patch --range-diff with multiple notes' '
 	test_cmp expect actual
 '
 
+test_expect_success 'format-patch --range-diff --notes=custom --no-range-diff-notes' '
+	test_when_finished "git notes --ref=custom remove topic unmodified || :" &&
+	git notes --ref=custom add -m "topic note1" topic &&
+	git notes --ref=custom add -m "unmodified note1" unmodified &&
+	test_when_finished "rm -f 000?-*" &&
+	git format-patch --range-diff=$prev --notes=custom \
+		--no-range-diff-notes --cover-letter \
+		main..unmodified >actual &&
+	test_grep "^Notes (custom):" 0004-* &&
+	test_grep "^Range-diff:" 0000-cover-letter* &&
+	test_grep ! "## Notes (custom) ##" 0000-cover-letter*
+'
+
+test_expect_success 'format-patch --range-diff --range-diff-notes uses --notes behavior' '
+	test_when_finished "git notes --ref=custom remove topic unmodified || :" &&
+	git notes --ref=custom add -m "topic note1" topic &&
+	git notes --ref=custom add -m "unmodified note1" unmodified &&
+	test_when_finished "rm -f 000?-*" &&
+	git format-patch --range-diff=$prev --notes=custom \
+		--range-diff-notes --cover-letter \
+		main..unmodified >actual &&
+	test_grep "^Notes (custom):" 0004-* &&
+	test_grep "^Range-diff:" 0000-cover-letter* &&
+	test_grep "## Notes (custom) ##" 0000-cover-letter*
+'
+
+test_expect_success 'format-patch --range-diff --notes=patch --range-diff-notes=rdiff' '
+	test_when_finished "git notes --ref=patch remove topic unmodified || :" &&
+	git notes --ref=patch add -m "only for patch 1" topic &&
+	git notes --ref=patch add -m "only for patch 2" unmodified &&
+	test_when_finished "git notes --ref=rdiff remove topic unmodified || :" &&
+	git notes --ref=rdiff add -m "only for range diff 1" topic &&
+	git notes --ref=rdiff add -m "only for range diff 2" unmodified &&
+	test_when_finished "rm -f 000?-*" &&
+	git format-patch --range-diff=$prev --notes=patch \
+		--range-diff-notes=rdiff --cover-letter \
+		main..unmodified >actual &&
+	test_grep "^Notes (patch):" 0004-* &&
+	test_grep ! "^Notes (rdiff):" 0004-* &&
+	test_grep "^Range-diff:" 0000-cover-letter* &&
+	test_grep "## Notes (rdiff) ##" 0000-cover-letter* &&
+	test_grep ! "## Notes (patch) ##" 0000-cover-letter*
+'
+
+test_expect_success 'format-patch --range-diff --no-range-diff-notes --range-diff-notes uses --notes behavior' '
+	test_when_finished "git notes --ref=custom remove topic unmodified || :" &&
+	git notes --ref=custom add -m "topic note1" topic &&
+	git notes --ref=custom add -m "unmodified note1" unmodified &&
+	test_when_finished "rm -f 000?-*" &&
+	git format-patch --range-diff=$prev --notes=custom \
+		--no-range-diff-notes --range-diff-notes --cover-letter \
+		main..unmodified >actual &&
+	test_grep "^Notes (custom):" 0004-* &&
+	test_grep "^Range-diff:" 0000-cover-letter* &&
+	test_grep "## Notes (custom) ##" 0000-cover-letter*
+'
+
+test_expect_success 'format-patch --range-diff --range-diff-notes uses --notes behavior' '
+	test_when_finished "git notes --ref=custom remove topic unmodified || :" &&
+	git notes --ref=custom add -m "topic note1" topic &&
+	git notes --ref=custom add -m "unmodified note1" unmodified &&
+	test_when_finished "rm -f 000?-*" &&
+	git format-patch --range-diff=$prev --notes=custom \
+		--range-diff-notes --cover-letter \
+		main..unmodified >actual &&
+	test_grep "^Notes (custom):" 0004-* &&
+	test_grep "^Range-diff:" 0000-cover-letter* &&
+	test_grep "## Notes (custom) ##" 0000-cover-letter*
+'
+
+test_expect_success 'format-patch --range-diff --no-range-diff-notes does not use default notes' '
+	test_when_finished "git notes remove topic unmodified || :" &&
+	git notes add -m "topic note1" topic &&
+	git notes add -m "unmodified note1" unmodified &&
+	test_when_finished "rm -f 000?-*" &&
+	git format-patch --range-diff=$prev \
+		--no-range-diff-notes --cover-letter \
+		main..unmodified >actual &&
+	test_grep ! "^Notes:" 0004-* &&
+	test_grep "^Range-diff:" 0000-cover-letter* &&
+	test_grep ! "## Notes ##" 0000-cover-letter*
+'
+
+test_expect_success 'format-patch --range-diff --no-range-diff-notes on single patch' '
+	test_when_finished "git notes --ref=custom remove HEAD unmodified || :" &&
+	git notes --ref=custom add -m "topic note (custom)" HEAD &&
+	git notes --ref=custom add -m "unmodified note (custom)" unmodified &&
+	git format-patch --notes=custom --range-diff=$prev \
+		--no-range-diff-notes -1 --stdout >actual &&
+	test_grep "Notes (custom):" actual &&
+	test_grep "^Range-diff:" actual &&
+	test_grep ! "## Notes (custom) ##" actual
+'
+
+test_expect_success 'format-patch --range-diff --range-diff-notes=custom on single patch' '
+	test_when_finished "git notes --ref=custom remove HEAD unmodified || :" &&
+	git notes --ref=custom add -m "topic note (custom)" HEAD &&
+	git notes --ref=custom add -m "unmodified note (custom)" unmodified &&
+	git format-patch --no-notes --range-diff=$prev \
+		--range-diff-notes=custom -1 --stdout >actual &&
+	test_grep ! "Notes (custom):" actual &&
+	test_grep "^Range-diff:" actual &&
+	test_grep "## Notes (custom) ##" actual
+'
+
 test_expect_success '--left-only/--right-only' '
 	git switch --orphan left-right &&
 	test_commit first &&
-- 
2.55.0.13.g85d2d65e389

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

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
> index 191f64b77d1..e0ba435dfcf 100644
> --- a/Documentation/git-format-patch.adoc
> +++ b/Documentation/git-format-patch.adoc
> @@ -378,6 +378,23 @@ case is to show comparison with an older iteration of the same
>  topic and the tool should find more correspondence between the two
>  sets of patches.
>  
> +`--range-diff-notes[=<ref>]`::
> +`--no-range-diff-notes`::
> +	Used with `--range-diff`, tweak what notes to display in the
> +	range diff. For example, you can use `--no-range-diff-notes` to
> +	turn off all notes in the range diff. The default behavior is
> +	to display the same notes in the range diff as on the patches
> +	(see `--notes`).
> ++
> +You may want to turn off this notes override 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.
> +

Hmph, this is a bit too complex for me.  When I say

    $ git format-patch --no-notes --range-diff-notes ...

I would expect that individual patches would not get notes, but the
range-diff will include them in the comparison.  But if
--range-diff-notes just falls back to default (i.e., inherit what
patches use), would I see the notes used in the range-diff?

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

[Kristoffer Haugsbakk]

On Tue, Aug 25, 2026, at 00:31, Junio C Hamano wrote:
> [snip]
>> +Now the range diff is back to displaying the same notes as the patches.
>> +
>
> Hmph, this is a bit too complex for me.  When I say
>
>     $ git format-patch --no-notes --range-diff-notes ...
>
> I would expect that individual patches would not get notes, but the
> range-diff will include them in the comparison.  But if
> --range-diff-notes just falls back to default (i.e., inherit what
> patches use), would I see the notes used in the range-diff?

You will not get patch notes and not get
range diff notes. That --range-diff-notes
told it to use the patch notes which you
just turned off/emptied the list.

Code-wise, the list of notes is cleared so you
you would have to change the --notes implementation
if you want to keep a sort of shadow list
of not-patch-notes-but-RD-notes.
And another problem, or fact, is that format-patch
does not show notes by default. So what should
--RD-notes show? The default notes?

Thanks

sent from mobile

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

>> Hmph, this is a bit too complex for me.  When I say
>>
>>     $ git format-patch --no-notes --range-diff-notes ...
>>
>> I would expect that individual patches would not get notes, but the
>> range-diff will include them in the comparison.  But if
>> --range-diff-notes just falls back to default (i.e., inherit what
>> patches use), would I see the notes used in the range-diff?
>
> You will not get patch notes and not get
> range diff notes. That --range-diff-notes
> told it to use the patch notes which you
> just turned off/emptied the list.
>
> Code-wise, the list of notes is cleared so you
> you would have to change the --notes implementation
> if you want to keep a sort of shadow list
> of not-patch-notes-but-RD-notes.

IOW, the design of how these options interact does not support the
usecase I gave?

> And another problem, or fact, is that format-patch
> does not show notes by default. So what should
> --RD-notes show? The default notes?

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.

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

[Kristoffer Haugsbakk]

On Fri, Aug 28, 2026, at 02:31, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>>> Hmph, this is a bit too complex for me.  When I say
>>>
>>>     $ git format-patch --no-notes --range-diff-notes ...
>>>
>>> I would expect that individual patches would not get notes, but the
>>> range-diff will include them in the comparison.  But if
>>> --range-diff-notes just falls back to default (i.e., inherit what
>>> patches use), would I see the notes used in the range-diff?
>>
>> You will not get patch notes and not get
>> range diff notes. That --range-diff-notes
>> told it to use the patch notes which you
>> just turned off/emptied the list.
>>
>> Code-wise, the list of notes is cleared so you
>> you would have to change the --notes implementation
>> if you want to keep a sort of shadow list
>> of not-patch-notes-but-RD-notes.
>
> IOW, the design of how these options interact does not support the
> usecase I gave?

Correct as far as I understand the use case.

>
>> And another problem, or fact, is that format-patch
>> does not show notes by default. So what should
>> --RD-notes show? The default notes?
>
> 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.

sent from mobile

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

[Junio C Hamano]

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

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

[Kristoffer Haugsbakk]

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.

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

[Kristoffer Haugsbakk]

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.

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

[D. Ben Knoble]

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

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

[Kristoffer Haugsbakk]

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

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

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

Up to this point it is quite clear how the two interact.  Even
though it does not appear in the above paragraph, the rules
essentially are "Without --range-diff-notes, the refs that are
specified by --notes are used for both purposes" and "When you use
--range-diff-notes, --notes and --range-diff-notes give independent
sets of notes, the former is shown only in the output, the latter is
used only for comparison".

But the following paragraph, while it may be correctly describing
what the code does, does not tell me why you would even want to do
so.  

For example, if you have --notes=foo --notes=bar always given in an
alias, i.e.

    [alias] fmt = format-patch --notes=foo --notes=bar

but in one invocation you would want to use different set of notes
only for comparison, you would

    git fmt --range-diff-notes=

if you do not want any notes participate in the comparison, or

    git fmt --range-diff-notes=bar

you want only 'bar' to be used in the comparison.

If you had --range-diff-notes=foo in a similar way in an alias,

    [alias] fmtr = format-patch --range-diff-notes=foo --notes=bar

you may need a way to tell that 'foo' no longer participates in the
comparison with

    git fmtr --no-range-diff-notes

If the rule is that once you say --no-range-diff-notes the internal
state is reset and the command behaves as if no --range-diff-notes
option is ever given [*], then that would still leave --notes=bar so
the command would beave as if

    git format-patch --notes=bar

were given, which means bar will now affect both, so if you want
'bar' not to be used for comparison, you would need some way to
pretend as if you said

    git format-patch --range-diff-notes= --notes=bar

and ...

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

... may be a way to do so, perhaps?

BUT I think that is a strange interpretation and notation.  Normal
people would rather assume, once you said --no-range-diff-notes, you
do not want any notes to be used for range-diff comparison.  IOW, I
find the earlier rule [*] that makes --no-range-diff-notes only tell
the command to pretend that no --range-diff-notes is ever given,
which leads to the above conclusion, a source of confusion.

If the rule were "if you say --no-range-diff-notes, you are saying
that you do not want any notes used for range-diff" (and similarly
"if you say --no-notes you are saying that you do not want any notes
used"), would it make the workaround in the last part unnecessary?
Under such a world order, 

    git fmtr --no-range-diff-notes

would mean that --no-range-diff-notes tells that you do not want any
notes participate in the comparison, so any --notes in the alias
definition of fmtr would be used only for the final display.  And

    git fmtr --no-range-diff-notes --range-diff-notes

would tell the command that on top of the previous state, you are
adding 0 notes to the set of notes used for comparisons, so it would
be a no op.  If it were

    git fmtr --no-range-diff-notes --range-diff-notes=bar

then you'd let --notes in the fmtr alias definition to be used for
final display, --range-diff-notes in the fmtr alias definition to be
totally ignored, and bar is used for comparison.

Would that logically make sense and make it easier to understand?

Thanks.

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

[D. Ben Knoble]

On Sun, Sep 6, 2026 at 12:45 PM Kristoffer Haugsbakk
<kristofferhaugsbakk@fastmail.com> wrote:
>
> 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]

Aha! I _did_ misunderstand, then :) I thought this example in the
proposal was for the case where "my-fp" has "--no-RD-notes" and we
wanted to re-add them with "--RD-notes".

Heh, definitely a bit confusing, but spelled out it makes sense.

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

I thought about that, as well, after re-absorbing the examples. I'm
not sure what to call it, though. "disable-RD-notes" is a mouthful and
doesn't seem to have precedence from my (spotty!) memory of various
subcommands.

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

Reading from the sidelines, it seems we have often gotten ourselves in
trouble because the code was easy and too easily reflected in the user
interface. OTOH, I'm not sure what else to do here ;)

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

Huh, interesting. "git help format-patch" says format.notes turns on
"--notes", so I would guess without looking further that it is a
boolean.

Yet "git help config" says it can provide a ref.

So, yeah, I would expect format-patch should use format.notes over
notes.displayRef.

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

The price of flexibility ;)

> 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

<3

-- 
D. Ben Knoble

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

[Kristoffer Haugsbakk]

On Sun, Sep 6, 2026, at 19:12, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>> 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`.
>
> Up to this point it is quite clear how the two interact.  Even
> though it does not appear in the above paragraph, the rules
> essentially are "Without --range-diff-notes, the refs that are
> specified by --notes are used for both purposes" and "When you use
> --range-diff-notes, --notes and --range-diff-notes give independent
> sets of notes, the former is shown only in the output, the latter is
> used only for comparison".
>
> But the following paragraph, while it may be correctly describing
> what the code does, does not tell me why you would even want to do
> so.
>
> For example, if you have --notes=foo --notes=bar always given in an
> alias, i.e.
>
>     [alias] fmt = format-patch --notes=foo --notes=bar
>
> but in one invocation you would want to use different set of notes
> only for comparison, you would
>
>     git fmt --range-diff-notes=

Side note: using `--range-diff-notes=` (empty arg) to signal no-notes
would be inconsistent with `--notes`. Those options just take that
value. Then they inevitably output:

    $ git log --notes=
    warning: notes ref refs/notes/ is invalid
    [output]

>
> if you do not want any notes participate in the comparison, or
>
>     git fmt --range-diff-notes=bar
>
> you want only 'bar' to be used in the comparison.
>
> If you had --range-diff-notes=foo in a similar way in an alias,
>
>     [alias] fmtr = format-patch --range-diff-notes=foo --notes=bar
>
> you may need a way to tell that 'foo' no longer participates in the
> comparison with
>
>     git fmtr --no-range-diff-notes
>
> If the rule is that once you say --no-range-diff-notes the internal
> state is reset and the command behaves as if no --range-diff-notes
> option is ever given [*], then that would still leave --notes=bar so
> the command would beave as if
>
>     git format-patch --notes=bar
>
> were given, which means bar will now affect both, so if you want
> 'bar' not to be used for comparison, you would need some way to
> pretend as if you said
>
>     git format-patch --range-diff-notes= --notes=bar
>
> and ...
>
>>     +
>>     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.
>
> ... may be a way to do so, perhaps?
>
> BUT I think that is a strange interpretation and notation.  Normal
> people would rather assume, once you said --no-range-diff-notes, you
> do not want any notes to be used for range-diff comparison.  IOW, I
> find the earlier rule [*] that makes --no-range-diff-notes only tell
> the command to pretend that no --range-diff-notes is ever given,
> which leads to the above conclusion, a source of confusion.

Thanks for the detailed walkthrough.

I don’t understand why you contrast these two approaches:

(I’m using `RD` as a shorthand for `range-diff` again)

1. `--no-RD-notes` means “revert to whatever `--notes` is up to”, as if
   no `--[no-]RD-notes` of any kind were ever given
2. `--no-RD-notes` means “no range diff/comparison notes at all”

Since (2) was the only design I presented. Is the point that you can use
these two approaches to eventually find a way to implement the “revert
to `--notes` behavior”? Well, if so I understand.

>
> If the rule were "if you say --no-range-diff-notes, you are saying
> that you do not want any notes used for range-diff" (and similarly
> "if you say --no-notes you are saying that you do not want any notes
> used"), would it make the workaround in the last part unnecessary?

You seem to be saying that (1), which is not in my implementation, is
used which in turn necessitates the workaround presented in the part of
the doc that you presented. But that’s not the case.

> Under such a world order,
>
>     git fmtr --no-range-diff-notes
>
> would mean that --no-range-diff-notes tells that you do not want any
> notes participate in the comparison, so any --notes in the alias
> definition of fmtr would be used only for the final display.  And
>
>     git fmtr --no-range-diff-notes --range-diff-notes
>
> would tell the command that on top of the previous state, you are
> adding 0 notes to the set of notes used for comparisons, so it would
> be a no op.  If it were
>
>     git fmtr --no-range-diff-notes --range-diff-notes=bar
>
> then you'd let --notes in the fmtr alias definition to be used for
> final display, --range-diff-notes in the fmtr alias definition to be
> totally ignored, and bar is used for comparison.
>
> Would that logically make sense and make it easier to understand?

Here we lose the power to revert to what `--notes` is using. (Which you
demonstrated the utility of with the alias.) But I think that is
fine. It is a niche behavior of a niche option. Does not warrant the
end-user to think this hard at all.

So here is my redesign:

• There are only `--no-RD-notes` and `--RD-notes=<ref>`, i.e. the last
  one has to have an argument. Since we have no use for arg-less
  `--RD-notes` any more.
• That means that we can use a regular pars-opts callback instead of
  adding it to `revision.c:handle_revision_opt`.
• The same rule about interaction with patch notes: no such RD notes
  means that the patches notes determine what notes the range diff
  gets. *With* any such options, however, they are determined only by
  those options. That includes turning off all range diff notes with
  `--no-RD-notes`.
• No feature for the niche behavior of turning *back on* “use the patch
  notes” behavior for the range diff notes

Thoughts? I’ll try to work on the reroll in the meantime.

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> Side note: using `--range-diff-notes=` (empty arg) to signal no-notes
> would be inconsistent with `--notes`. Those options just take that
> value. Then they inevitably output:
>
>     $ git log --notes=
>     warning: notes ref refs/notes/ is invalid
>     [output]

Ah, I didn't know that one.  It sounds like a UI bug we can safely
fix without worrying about being backward incompatible.

> I don’t understand why you contrast these two approaches:
>
> (I’m using `RD` as a shorthand for `range-diff` again)
>
> 1. `--no-RD-notes` means “revert to whatever `--notes` is up to”, as if
>    no `--[no-]RD-notes` of any kind were ever given
> 2. `--no-RD-notes` means “no range diff/comparison notes at all”
>
> Since (2) was the only design I presented. Is the point that you can use
> these two approaches to eventually find a way to implement the “revert
> to `--notes` behavior”? Well, if so I understand.

No.  I thought #1 was what you were doing, which was how I thought
was the only way for the command line you suggested in an earlier
message would make sense.

    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.

Under the interpretation #2, the first --no-RD-notes tells us that
we won't use notes for comparison, and then the next --RD-notes
tells us that we use notes listed as parameter to it (which is "no
notes") for comparison, so the "notes override behaviour" is not
turned off.  We use no notes for comparison, and use the ones that
are given with --notes=<note> only for display.

Under the interpretation #1, the first --no-RD-notes would make the
command behave as if no --RD-notes were even given, and --notes=<note>
would be used both for comparison and display.  Then --RD-notes that
says there is no particular notes you want for comparison would make
the <note> given earlier with --notes=<note> not to be used for
comparison.  After spelling it out like this, it seems that even #1
does not turn off this notes override behaviour, either.  I admit
that I wasn't thinking about interpretation #1 too deeply as I
wasn't interested in seeing it happen.

So it is good that we agree we want to use the interpretation #2.
Which means the "You may want to turn off ..." part of the
documentation inaccurate (I think I've already suggested striking it
off in an earlier message).