[PATCH v2 0/3] format-patch: handle range-diff on notes correctly for single patches
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
git-format-patch(1) does not handle Git notes correctly in the range-diff output for single-commit series. It reverts to the default behavior of git-range-diff(1), which is to act like git-log(1).
Git notes can be added to patches where they go beneath the commit message (similar to git-log(1)). You can of course use any set of notes ref names. And the range-diff is supposed to use the same ref names. This works for the case when you have a cover letter (for more than one commit) but not when you have a single commit.
See patch 2/3 for a full explanation of the problem.
Fix that notes handling to always output the same notes (ref names) in the two positions:
• beneath the commit message; and • in the range diff.
Patch-by-patch:
1. Rename `other_arg` to `log_arg`
2. Refactor to use a new `rev_info` struct member
3. Use that in `log-tree.c` in order to solve the problem
§ Changes in v2
Mostly better commit messages. Fix a mistake in the `rev_info` struct handling.
Patch-by-patch (see notes on them for details):
1. (new) Better variable name
2. Rewrite commit message and fix mistake
3. Rewrite commit message by mostly stealing from patch 2/3
About the commit messages: the first one just jumped into the problem without a proper introduction (see the note on patch 2/3). Not clear enough. But I didn’t act on this review feedback:[1]
“ Would this also mean "range-diff --no-notes" would not have any
effect in squelching the note output in such a mode? If so, perhaps
we should say not just "can get different Git notes" but "can get
notes even when you asked not to"?🔗 1: https://lore.kernel.org/git/xmqqecryrvt6.fsf@gitster.g/
Since both commits in v1 already said `--[no-]notes`.
§ CC
Denton Liu wrote a commit mentioned in patch 1/3. It’s been more years than the recommended cutoff, but he has been active recently.
§ Link to the previous version
https://lore.kernel.org/git/cover.1758574974.git.code@khaugsbakk.name/
❦ ❦ ❦ ❦ ❦
(this means you can skip to the diffs)
§ How I Present Patch Series
Version: 1
The cover letter:
• Problem statement and solution
• (optional) Summary of what each commit/patch does
• Changes compared to the previous version
• Note that all versions are not included
• (optional) “CC”/“Cc” which explains all or parts of the CC list
• But some things are not noteworthy, like the standard practice of
including previous-round respondents
• Link to the previous version
• This is new. I thought it was redundant but some people (like me!)
use webapp email clients which are not that great for navigating
among tree-like email threads. So I was inspired by this practice
which many others already use.
• I like including an interdiff in addition to the range diff if I can.
They are just so convenient and complementary to the range diff.Then each commit/patch might have Git notes with a `series` namespace (ref name) These contain:
• Comments/questions to reviewers about my approach or statements made
in the commit message.
• Lines starting with `v<version>:` which introduce a changelog for that
version. Lately (Sep 2025) these have been written in the “imperative
mood”, like what is done for a commit message in this (Git) project.
A bit strange, given that most others seem to use the more immediately
natural past-tense. But on the other hand: how many new contributors
to this project use the wrong tense/mood in their commit messages?
The Git project rule is not “natural”. But I think it’s better
nonetheless and worth the effort.
(And it might be worth the effort in this context, too. We will see.)
• ... But this kind of changelog might also be conducive to a bullet
list of changes. So I might either skip the previous point, do only a
bullet point, or do both: a presentation and then the bullet points
summarizing the presentation.
• Note that all `v<version>:` are kept between versions, which is not
consistent with how I only have the “Changes” part for the previous
version.
• `v<version>:` are ordered newest-to-oldest.
Kristoffer Haugsbakk (3):
range-diff: rename other_arg to log_arg
revision: add rdiff_log_arg to rev_info
format-patch: handle range-diff on notes correctly for single patches
builtin/log.c | 7 +++----
builtin/range-diff.c | 16 ++++++++--------
log-tree.c | 3 ++-
range-diff.c | 10 +++++-----
range-diff.h | 2 +-
revision.h | 2 ++
t/t3206-range-diff.sh | 16 +++++++++++++++-
7 files changed, 36 insertions(+), 20 deletions(-)
Interdiff against v1:
Show changes to 6 files +20 −20
builtin/log.c, builtin/range-diff.c, log-tree.c, range-diff.c, range-diff.h, revision.h
diff --git a/builtin/log.c b/builtin/log.c
index 56dd9fbc057..9eff62ce111 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -1405,7 +1405,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,
- .other_arg = &rev->rdiff_other_arg
+ .log_arg = &rev->rdiff_log_arg
};
repo_diff_setup(the_repository, &opts);
@@ -2325,7 +2325,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_other_arg), &rev);
+ get_notes_args(&(rev.rdiff_log_arg), &rev);
}
/*
@@ -2485,7 +2485,7 @@ int cmd_format_patch(int argc,
rev.diffopt.no_free = 0;
release_revisions(&rev);
format_config_release(&cfg);
- strvec_clear(&rev.rdiff_other_arg);
+ strvec_clear(&rev.rdiff_log_arg);
return 0;
}
diff --git a/builtin/range-diff.c b/builtin/range-diff.c
index aafcc99b962..f88b40e3607 100644
--- a/builtin/range-diff.c
+++ b/builtin/range-diff.c
@@ -37,13 +37,13 @@ int cmd_range_diff(int argc,
struct repository *repo UNUSED)
{
struct diff_options diffopt = { NULL };
- struct strvec other_arg = STRVEC_INIT;
+ struct strvec log_arg = STRVEC_INIT;
struct strvec diff_merges_arg = STRVEC_INIT;
struct range_diff_options range_diff_opts = {
.creation_factor = RANGE_DIFF_CREATION_FACTOR_DEFAULT,
.max_memory = RANGE_DIFF_MAX_MEMORY_DEFAULT,
.diffopt = &diffopt,
- .other_arg = &other_arg
+ .log_arg = &log_arg
};
int simple_color = -1, left_only = 0, right_only = 0;
struct option range_diff_options[] = {
@@ -52,7 +52,7 @@ int cmd_range_diff(int argc,
N_("percentage by which creation is weighted")),
OPT_BOOL(0, "no-dual-color", &simple_color,
N_("use simple diff colors")),
- OPT_PASSTHRU_ARGV(0, "notes", &other_arg,
+ OPT_PASSTHRU_ARGV(0, "notes", &log_arg,
N_("notes"), N_("passed to 'git log'"),
PARSE_OPT_OPTARG),
OPT_PASSTHRU_ARGV(0, "diff-merges", &diff_merges_arg,
@@ -92,7 +92,7 @@ int cmd_range_diff(int argc,
/* If `--diff-merges` was specified, imply `--merges` */
if (diff_merges_arg.nr) {
range_diff_opts.include_merges = 1;
- strvec_pushv(&other_arg, diff_merges_arg.v);
+ strvec_pushv(&log_arg, diff_merges_arg.v);
}
for (i = 0; i < argc; i++)
@@ -124,7 +124,7 @@ int cmd_range_diff(int argc,
strbuf_addf(&range1, "%s..%s", argv[0], argv[1]);
strbuf_addf(&range2, "%s..%s", argv[0], argv[2]);
- strvec_pushv(&other_arg, argv +
+ strvec_pushv(&log_arg, argv +
(dash_dash < 0 ? 3 : dash_dash));
} else if (dash_dash == 2 ||
(dash_dash < 0 && argc > 1 &&
@@ -144,7 +144,7 @@ int cmd_range_diff(int argc,
strbuf_addstr(&range1, argv[0]);
strbuf_addstr(&range2, argv[1]);
- strvec_pushv(&other_arg, argv +
+ strvec_pushv(&log_arg, argv +
(dash_dash < 0 ? 2 : dash_dash));
} else if (dash_dash == 1 ||
(dash_dash < 0 && argc > 0 &&
@@ -175,7 +175,7 @@ int cmd_range_diff(int argc,
strbuf_addf(&range1, "%s..%.*s", b, a_len, a);
strbuf_addf(&range2, "%.*s..%s", a_len, a, b);
- strvec_pushv(&other_arg, argv +
+ strvec_pushv(&log_arg, argv +
(dash_dash < 0 ? 1 : dash_dash));
} else
usage_msg_opt(_("need two commit ranges"),
@@ -187,7 +187,7 @@ int cmd_range_diff(int argc,
range_diff_opts.right_only = right_only;
res = show_range_diff(range1.buf, range2.buf, &range_diff_opts);
- strvec_clear(&other_arg);
+ strvec_clear(&log_arg);
strvec_clear(&diff_merges_arg);
strbuf_release(&range1);
strbuf_release(&range2);
diff --git a/log-tree.c b/log-tree.c
index 831284288f9..3d38c748e45 100644
--- a/log-tree.c
+++ b/log-tree.c
@@ -719,7 +719,7 @@ static void show_diff_of_diff(struct rev_info *opt)
.dual_color = 1,
.max_memory = RANGE_DIFF_MAX_MEMORY_DEFAULT,
.diffopt = &opts,
- .other_arg = &opt->rdiff_other_arg
+ .log_arg = &opt->rdiff_log_arg
};
memcpy(&dq, &diff_queued_diff, sizeof(diff_queued_diff));
diff --git a/range-diff.c b/range-diff.c
index ca449a07693..57edff40a85 100644
--- a/range-diff.c
+++ b/range-diff.c
@@ -39,7 +39,7 @@ struct patch_util {
* as struct object_id (will need to be free()d).
*/
static int read_patches(const char *range, struct string_list *list,
- const struct strvec *other_arg,
+ const struct strvec *log_arg,
unsigned int include_merges)
{
struct child_process cp = CHILD_PROCESS_INIT;
@@ -69,8 +69,8 @@ static int read_patches(const char *range, struct string_list *list,
if (!include_merges)
strvec_push(&cp.args, "--no-merges");
strvec_push(&cp.args, range);
- if (other_arg)
- strvec_pushv(&cp.args, other_arg->v);
+ if (log_arg)
+ strvec_pushv(&cp.args, log_arg->v);
cp.out = -1;
cp.no_stdin = 1;
cp.git_cmd = 1;
@@ -594,9 +594,9 @@ int show_range_diff(const char *range1, const char *range2,
if (range_diff_opts->left_only && range_diff_opts->right_only)
res = error(_("options '%s' and '%s' cannot be used together"), "--left-only", "--right-only");
- if (!res && read_patches(range1, &branch1, range_diff_opts->other_arg, include_merges))
+ if (!res && read_patches(range1, &branch1, range_diff_opts->log_arg, include_merges))
res = error(_("could not parse log for '%s'"), range1);
- if (!res && read_patches(range2, &branch2, range_diff_opts->other_arg, include_merges))
+ if (!res && read_patches(range2, &branch2, range_diff_opts->log_arg, include_merges))
res = error(_("could not parse log for '%s'"), range2);
if (!res) {
diff --git a/range-diff.h b/range-diff.h
index 9d39818e349..9b70a80009e 100644
--- a/range-diff.h
+++ b/range-diff.h
@@ -23,7 +23,7 @@ struct range_diff_options {
unsigned include_merges:1;
size_t max_memory;
const struct diff_options *diffopt; /* may be NULL */
- const struct strvec *other_arg; /* may be NULL */
+ const struct strvec *log_arg; /* may be NULL */
};
/*
diff --git a/revision.h b/revision.h
index 26c18a0934b..ce30570d86a 100644
--- a/revision.h
+++ b/revision.h
@@ -334,7 +334,7 @@ struct rev_info {
/* range-diff */
const char *rdiff1;
const char *rdiff2;
- struct strvec rdiff_other_arg;
+ struct strvec rdiff_log_arg;
int creation_factor;
const char *rdiff_title;
@@ -411,6 +411,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, \
}
/**
Range-diff against v1:
-: ----------- > 1: bd037df14f5 range-diff: rename other_arg to log_arg
1: bb065767336 ! 2: d9419743773 revision: add rdiff_other_arg to rev_info
@@ Metadata
Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
## Commit message ##
- revision: add rdiff_other_arg to rev_info
-
- git-format-patch(1) needs to pass `--[no-]notes` options on to the
- range-diff subprocess in `range-diff.c`. This is handled in `builtin/
- log.c` by the local variable `other_arg` in the case of multiple
- commits, but not in the single commit case where there is no cover
- letter and the range-diff is on that single resulting patch; the
- range-diff is then made in `log-tree.c`, whither `other_arg` has not
- been propagated.
-
- git-format-patch(1) is supposed to treat Git notes the same between
- notes output beneath the commit message and the notes output for the
- range-diff. But this lack of notes handling in `log-tree.c` breaks
- that expected behavior; range-diff notes handling for a single patch
- acts like a normal git-range-diff(1) invocation with regards to notes.
- You can, for example, end up with a patch where the note beneath the
- commit message has the correct notes namespace, but the range-diff has
- all the notes that are configured to be displayed by git-log(1).[1]
-
- We need to fix this. But first lay the groundwork by converting
- `other_arg` to a struct member; next we can simply use that member
+ revision: add rdiff_log_arg to rev_info
+
+ git-format-patch(1) supports Git notes by showing them beneath the
+ patch/commit message, similar to git-log(1). The command also supports
+ showing those same notes ref names in the range diff output.
+
+ Note *the same* ref names; any Git notes options or configuration
+ variables need to be handed off to the range-diff machinery. This works
+ correctly in the case when the range diff is on the cover letter. But it
+ does not work correctly when the output is a single patch with an
+ embedded range diff.
+
+ Concretely, git-format-patch(1) needs to pass `--[no-]notes` options
+ on to the range-diff subprocess in `range-diff.c`. This is handled in
+ `builtin/log.c` by the local variable `log_arg` in the case of mul-
+ tiple commits, but not in the single commit case where there is no
+ cover letter and the range diff is embedded in the patch output; the
+ range diff is then made in `log-tree.c`, whither `log_arg` has not
+ been propagated. This means that the range-diff subprocess reverts
+ to its default behavior, which is to act like git-log(1) w.r.t. notes.
+
+ We need to fix this. But first lay the groundwork by converting
+ `log_arg` to a struct member; next we can simply use that member
in `log-tree.c` without having to thread it from `builtin/log.c`.
No functional changes.
- † 1: See the configuration variable `format.notes` for git-format-
- patch(1); c.f. `notes.displayRef` for git-log(1). These two
- have nothing to do with each other.
-
+ Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
## Notes (series) ##
+ v2:
+
+ Rewrite the commit message. The message jumps into the problem without
+ setting the stage. I think the problem should be presented for a future
+ reader with only some basic prerequisite knowledge of this area; they
+ might use git-format-patch(1), but they might not use Git notes *with*
+ format-patch.[1] For that reason, start with two paragraphs that pre-
+ sent how notes are handled. Then continue with the story in a format
+ similar to v1.
+
+ Note that the different “range diff” and “range-diff” spellings are
+ intentional. “Range diff” here refers to the diff output while
+ “range-diff” refers to the machinery that creates that output.
+
+ † 1: I don’t really see much Git notes use on patches on this mailing
+ list. And even less with non-default namespaces. But in any case:
+ the stage should be set properly even if regulars here *did* use
+ format-patch notes a lot.
+
+ Also fix handling of struct-in-struct (helped by Junio).
+
+ • Rewrite the commit message
+ • Fix struct-in-struct
+ • (And) Reset author date. I started this in June but the time
+ investment is mostly from these last days.
+
+ v1:
+
There is also `other_arg` in `builtin/range-diff.c` but `rev_info` does
not seem to be involved.
@@ builtin/log.c: static void make_cover_letter(struct rev_info *rev, int use_separ
* can be added later if deemed desirable.
*/
struct diff_options opts;
-- struct strvec other_arg = STRVEC_INIT;
+- struct strvec log_arg = STRVEC_INIT;
struct range_diff_options range_diff_opts = {
.creation_factor = rev->creation_factor,
.dual_color = 1,
.max_memory = RANGE_DIFF_MAX_MEMORY_DEFAULT,
.diffopt = &opts,
-- .other_arg = &other_arg
-+ .other_arg = &rev->rdiff_other_arg
+- .log_arg = &log_arg
++ .log_arg = &rev->rdiff_log_arg
};
repo_diff_setup(the_repository, &opts);
@@ builtin/log.c: static void make_cover_letter(struct rev_info *rev, int use_separ
opts.use_color = rev->diffopt.use_color;
diff_setup_done(&opts);
fprintf_ln(rev->diffopt.file, "%s", rev->rdiff_title);
-- get_notes_args(&other_arg, rev);
+- get_notes_args(&log_arg, rev);
show_range_diff(rev->rdiff1, rev->rdiff2, &range_diff_opts);
-- strvec_clear(&other_arg);
+- strvec_clear(&log_arg);
}
}
@@ builtin/log.c: 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_other_arg), &rev);
++ get_notes_args(&(rev.rdiff_log_arg), &rev);
}
/*
@@ builtin/log.c: int cmd_format_patch(int argc,
rev.diffopt.no_free = 0;
release_revisions(&rev);
format_config_release(&cfg);
-+ strvec_clear(&rev.rdiff_other_arg);
++ strvec_clear(&rev.rdiff_log_arg);
return 0;
}
@@ revision.h: struct rev_info {
/* range-diff */
const char *rdiff1;
const char *rdiff2;
-+ struct strvec rdiff_other_arg;
++ struct strvec rdiff_log_arg;
int creation_factor;
const char *rdiff_title;
+@@ revision.h: struct rev_info {
+ .expand_tabs_in_log = -1, \
+ .commit_format = CMIT_FMT_DEFAULT, \
+ .expand_tabs_in_log_default = 8, \
++ .rdiff_log_arg = STRVEC_INIT, \
+ }
+
+ /**
2: 7f2487af433 ! 3: 2be637081d4 format-patch: handle range-diff on notes correctly for single patches
@@ Metadata
## Commit message ##
format-patch: handle range-diff on notes correctly for single patches
- No `--[no-]notes` options are sent to the range-diff subprocess in
- `range-diff.c` when making a single patch. This means that you can get
- different Git notes below the commit message and in the range-diff
- part. (See the previous commit for elaboration.)
+ (The two next paragraphs are taken from the previous commit.)
- Use the struct member that we introduced and populated in the
+ git-format-patch(1) supports Git notes by showing them beneath the
+ patch/commit message, similar to git-log(1). The command also supports
+ showing those same notes ref names in the range diff output.
+
+ Note *the same* ref names; any Git notes options or configuration
+ variables need to be handed off to the range-diff machinery. This works
+ correctly in the case when the range diff is on the cover letter. But it
+ does not work correctly when the output is a single patch with an
+ embedded range diff.
+
+ Concretely, git-format-patch(1) needs to pass `--[no-]notes` options on
+ to the range-diff subprocess in `range-diff.c`. Range diffs for single-
+ commit series are handled in `log-tree.c`. But `log-tree.c` had no
+ access to any `log_arg` variable before we added it to `rev_info` in the
previous commit.
+ Use that new struct member to fix this inconsistency.
+
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
## Notes (series) ##
+ v1:
+
I’ve tried to conform to 6caa96c2 (t3206: test_when_finished before
dirtying operations, not after, 2024-08-06) in the test here.
@@ log-tree.c: static void show_diff_of_diff(struct rev_info *opt)
.max_memory = RANGE_DIFF_MAX_MEMORY_DEFAULT,
- .diffopt = &opts
+ .diffopt = &opts,
-+ .other_arg = &opt->rdiff_other_arg
++ .log_arg = &opt->rdiff_log_arg
};
memcpy(&dq, &diff_queued_diff, sizeof(diff_queued_diff));
base-commit: ca2559c1d630eb4f04cdee2328aaf1c768907a9e
