From 9ccd9e6fcab2573a04b24f81d96cfdc355a7d51f Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Sat, 7 Mar 2026 00:34:40 +0100 Subject: [PATCH 01/41] pretty.c: add %(count) and %(total) placeholders In many commands we can customize the output through the "--format" or the "--pretty" options. This patch adds two new placeholders used mainly when there's a range of commits that we want to show. Currently these two placeholders are not usable as they're coupled with the rev_info->nr and rev_info->total fields, fields that are used only by the format-patch numbered email subjects. Teach repo_format_commit_message() the %(count) and %(total) placeholders. Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- pretty.c | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/pretty.c b/pretty.c index e0646bbc5d49cc..e29bb8b877411d 100644 --- a/pretty.c +++ b/pretty.c @@ -1549,6 +1549,21 @@ static size_t format_commit_one(struct strbuf *sb, /* in UTF-8 */ if (!commit->object.parsed) parse_object(the_repository, &commit->object.oid); + if (starts_with(placeholder, "(count)")) { + if (!c->pretty_ctx->rev) + die(_("this format specifier can't be used with this command")); + strbuf_addf(sb, "%0*d", decimal_width(c->pretty_ctx->rev->total), + c->pretty_ctx->rev->nr); + return 7; + } + + if (starts_with(placeholder, "(total)")) { + if (!c->pretty_ctx->rev) + die(_("this format specifier can't be used with this command")); + strbuf_addf(sb, "%d", c->pretty_ctx->rev->total); + return 7; + } + switch (placeholder[0]) { case 'H': /* commit hash */ strbuf_addstr(sb, diff_get_color(c->auto_color, DIFF_COMMIT)); From 2af59cbcf4375f4d7c61954a19244d130de0a0db Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Sat, 7 Mar 2026 00:34:41 +0100 Subject: [PATCH 02/41] format-patch: move cover letter summary generation As of now format-patch allows generation of a template cover letter for patch series through "--cover-letter". Move shortlog summary code generation to its own function. This is done in preparation to other patches where we enable the user to format the commit list using thier own format string. Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- builtin/log.c | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/builtin/log.c b/builtin/log.c index 5c9a8ef3632906..0d12272031f003 100644 --- a/builtin/log.c +++ b/builtin/log.c @@ -1324,6 +1324,25 @@ static void get_notes_args(struct strvec *arg, struct rev_info *rev) } } +static void generate_shortlog_cover_letter(struct shortlog *log, + struct rev_info *rev, + struct commit **list, + int nr) +{ + shortlog_init(log); + log->wrap_lines = 1; + log->wrap = MAIL_DEFAULT_WRAP; + log->in1 = 2; + log->in2 = 4; + log->file = rev->diffopt.file; + log->groups = SHORTLOG_GROUP_AUTHOR; + shortlog_finish_setup(log); + for (int i = 0; i < nr; i++) + shortlog_add_commit(log, list[i]); + + shortlog_output(log); +} + static void make_cover_letter(struct rev_info *rev, int use_separate_file, struct commit *origin, int nr, struct commit **list, @@ -1377,18 +1396,7 @@ static void make_cover_letter(struct rev_info *rev, int use_separate_file, free(pp.after_subject); strbuf_release(&sb); - shortlog_init(&log); - log.wrap_lines = 1; - log.wrap = MAIL_DEFAULT_WRAP; - log.in1 = 2; - log.in2 = 4; - log.file = rev->diffopt.file; - log.groups = SHORTLOG_GROUP_AUTHOR; - shortlog_finish_setup(&log); - for (i = 0; i < nr; i++) - shortlog_add_commit(&log, list[i]); - - shortlog_output(&log); + generate_shortlog_cover_letter(&log, rev, list, nr); /* We can only do diffstat with a unique reference point */ if (origin) From 6005932d95ff05541f9dbe8c49a45b7abaf7432e Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Sat, 7 Mar 2026 00:34:42 +0100 Subject: [PATCH 03/41] format-patch: add ability to use alt cover format Often when sending patch series there's a need to clarify to the reviewer what's the purpose of said series, since it might be difficult to understand it from reading the commits messages one by one. "git format-patch" provides the useful "--cover-letter" flag to declare if we want it to generate a template for us to use. By default it will generate a "git shortlog" of the changes, which developers find less useful than they'd like, mainly because the shortlog groups commits by author, and gives no obvious chronological order. Give format-patch the ability to specify an alternative format spec through the "--cover-letter-format" option. This option either takes "shortlog", which is the current format, or a format spec prefixed with "log:". Example: git format-patch --cover-letter \ --cover-letter-format="log:[%(count)/%(total)] %s (%an)" HEAD~3 [1/3] this is a commit summary (Mirko Faina) [2/3] this is another commit summary (Mirko Faina) ... Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- builtin/log.c | 40 +++++++++++++++++++++++++++++++--- t/t4014-format-patch.sh | 48 +++++++++++++++++++++++++++++++++++++++++ t/t9902-completion.sh | 1 + 3 files changed, 86 insertions(+), 3 deletions(-) diff --git a/builtin/log.c b/builtin/log.c index 0d12272031f003..95e5d9755fac6d 100644 --- a/builtin/log.c +++ b/builtin/log.c @@ -1343,13 +1343,36 @@ static void generate_shortlog_cover_letter(struct shortlog *log, shortlog_output(log); } +static void generate_commit_list_cover(FILE *cover_file, const char *format, + struct commit **list, int n) +{ + struct strbuf commit_line = STRBUF_INIT; + struct pretty_print_context ctx = {0}; + struct rev_info rev = REV_INFO_INIT; + + strbuf_init(&commit_line, 0); + rev.total = n; + ctx.rev = &rev; + for (int i = n - 1; i >= 0; i--) { + rev.nr = n - i; + repo_format_commit_message(the_repository, list[i], format, + &commit_line, &ctx); + fprintf(cover_file, "%s\n", commit_line.buf); + strbuf_reset(&commit_line); + } + fprintf(cover_file, "\n"); + + strbuf_release(&commit_line); +} + static void make_cover_letter(struct rev_info *rev, int use_separate_file, struct commit *origin, int nr, struct commit **list, const char *description_file, const char *branch_name, int quiet, - const struct format_config *cfg) + const struct format_config *cfg, + const char *format) { const char *committer; struct shortlog log; @@ -1396,7 +1419,12 @@ static void make_cover_letter(struct rev_info *rev, int use_separate_file, free(pp.after_subject); strbuf_release(&sb); - generate_shortlog_cover_letter(&log, rev, list, nr); + if (skip_prefix(format, "log:", &format)) + generate_commit_list_cover(rev->diffopt.file, format, list, nr); + else if (!strcmp(format, "shortlog")) + generate_shortlog_cover_letter(&log, rev, list, nr); + else + die(_("'%s' is not a valid format string"), format); /* We can only do diffstat with a unique reference point */ if (origin) @@ -1914,6 +1942,7 @@ int cmd_format_patch(int argc, int just_numbers = 0; int ignore_if_in_upstream = 0; int cover_letter = -1; + const char *cover_letter_fmt = NULL; int boundary_count = 0; int no_binary_diff = 0; int zero_commit = 0; @@ -1960,6 +1989,8 @@ int cmd_format_patch(int argc, N_("print patches to standard out")), OPT_BOOL(0, "cover-letter", &cover_letter, N_("generate a cover letter")), + OPT_STRING(0, "cover-letter-format", &cover_letter_fmt, N_("format-spec"), + N_("format spec used for the commit list in the cover letter")), OPT_BOOL(0, "numbered-files", &just_numbers, N_("use simple number sequence for output file names")), OPT_STRING(0, "suffix", &fmt_patch_suffix, N_("sfx"), @@ -2297,6 +2328,7 @@ int cmd_format_patch(int argc, /* nothing to do */ goto done; total = list.nr; + if (cover_letter == -1) { if (cfg.config_cover_letter == COVER_AUTO) cover_letter = (total > 1); @@ -2383,12 +2415,14 @@ int cmd_format_patch(int argc, } rev.numbered_files = just_numbers; rev.patch_suffix = fmt_patch_suffix; + if (cover_letter) { if (cfg.thread) gen_message_id(&rev, "cover"); make_cover_letter(&rev, !!output_directory, origin, list.nr, list.items, - description_file, branch_name, quiet, &cfg); + description_file, branch_name, quiet, &cfg, + cover_letter_fmt); print_bases(&bases, rev.diffopt.file); print_signature(signature, rev.diffopt.file); total++; diff --git a/t/t4014-format-patch.sh b/t/t4014-format-patch.sh index 21d6d0cd9ef679..458da80721a1e9 100755 --- a/t/t4014-format-patch.sh +++ b/t/t4014-format-patch.sh @@ -380,6 +380,54 @@ test_expect_success 'filename limit applies only to basename' ' done ' +test_expect_success 'cover letter with subject, author and count' ' + rm -rf patches && + test_when_finished "git reset --hard HEAD~1" && + test_when_finished "rm -rf patches result test_file" && + touch test_file && + git add test_file && + git commit -m "This is a subject" && + git format-patch --cover-letter \ + --cover-letter-format="log:[%(count)/%(total)] %s (%an)" -o patches HEAD~1 && + grep "^\[1/1\] This is a subject (A U Thor)$" patches/0000-cover-letter.patch >result && + test_line_count = 1 result +' + +test_expected_success 'cover letter with author and count' ' + test_when_finished "git reset --hard HEAD~1" && + test_when_finished "rm -rf patches result test_file" && + touch test_file && + git add test_file && + git commit -m "This is a subject" && + git format-patch --cover-letter \ + --cover-letter-format="log:[%(count)/%(total)] %an" -o patches HEAD~1 && + grep "^\[1/1\] A U Thor$" patches/0000-cover-letter.patch >result && + test_line_count = 1 result +' + +test_expect_success 'cover letter shortlog' ' + test_when_finished "git reset --hard HEAD~1" && + test_when_finished "rm -rf patches result test_file" && + touch test_file && + git add test_file && + git commit -m "This is a subject" && + git format-patch --cover-letter --cover-letter-format=shortlog \ + -o patches HEAD~1 && + sed -n -e "/^A U Thor/p;" patches/0000-cover-letter.patch >result && + test_line_count = 1 result +' + +test_expect_success 'cover letter no format' ' + test_when_finished "git reset --hard HEAD~1" && + test_when_finished "rm -rf patches result test_file" && + touch test_file && + git add test_file && + git commit -m "This is a subject" && + git format-patch --cover-letter -o patches HEAD~1 && + sed -n -e "/^A U Thor/p;" patches/0000-cover-letter.patch >result && + test_line_count = 1 result +' + test_expect_success 'reroll count' ' rm -fr patches && git format-patch -o patches --cover-letter --reroll-count 4 main..side >list && diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh index 964e1f156932c6..4f760a746862c3 100755 --- a/t/t9902-completion.sh +++ b/t/t9902-completion.sh @@ -2774,6 +2774,7 @@ test_expect_success PERL 'send-email' ' test_completion "git send-email --cov" <<-\EOF && --cover-from-description=Z --cover-letter Z + --cover-letter-format=Z EOF test_completion "git send-email --val" <<-\EOF && --validate Z From be0ef6fcd2379ea3dc1569d6d8c360d6d59d031f Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Sat, 7 Mar 2026 00:34:43 +0100 Subject: [PATCH 04/41] format-patch: add commitListFormat config Using "--cover-letter" we can tell format-patch to generate a cover letter, in this cover letter there's a list of commits included in the patch series and the format is specified by the "--cover-letter-format" option. Would be useful if this format could be configured from the config file instead of always needing to pass it from the command line. Teach format-patch how to read the format spec for the cover letter from the config files. The variable it should look for is called format.commitListFormat. Possible values: - commitListFormat is set but no string is passed: it will default to "[%(count)/%(total)] %s" - if a string is passed: will use it as a format spec. Note that this is either "shortlog" or a format spec prefixed by "log:" e.g."log:%s (%an)" - if commitListFormat is not set: it will default to the shortlog format. Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- builtin/log.c | 21 ++++++++++++++++ t/t4014-format-patch.sh | 53 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) diff --git a/builtin/log.c b/builtin/log.c index 95e5d9755fac6d..5fec0ddaf91b0a 100644 --- a/builtin/log.c +++ b/builtin/log.c @@ -886,6 +886,7 @@ struct format_config { char *signature; char *signature_file; enum cover_setting config_cover_letter; + char *fmt_cover_letter_commit_list; char *config_output_directory; enum cover_from_description cover_from_description_mode; int show_notes; @@ -930,6 +931,7 @@ static void format_config_release(struct format_config *cfg) string_list_clear(&cfg->extra_cc, 0); strbuf_release(&cfg->sprefix); free(cfg->fmt_patch_suffix); + free(cfg->fmt_cover_letter_commit_list); } static enum cover_from_description parse_cover_from_description(const char *arg) @@ -1052,6 +1054,19 @@ static int git_format_config(const char *var, const char *value, cfg->config_cover_letter = git_config_bool(var, value) ? COVER_ON : COVER_OFF; return 0; } + if (!strcmp(var, "format.commitlistformat")) { + struct strbuf tmp = STRBUF_INIT; + strbuf_init(&tmp, 0); + if (value) + strbuf_addstr(&tmp, value); + else + strbuf_addstr(&tmp, "log:[%(count)/%(total)] %s"); + + FREE_AND_NULL(cfg->fmt_cover_letter_commit_list); + git_config_string(&cfg->fmt_cover_letter_commit_list, var, tmp.buf); + strbuf_release(&tmp); + return 0; + } if (!strcmp(var, "format.outputdirectory")) { FREE_AND_NULL(cfg->config_output_directory); return git_config_string(&cfg->config_output_directory, var, value); @@ -2329,6 +2344,12 @@ int cmd_format_patch(int argc, goto done; total = list.nr; + if (!cover_letter_fmt) { + cover_letter_fmt = cfg.fmt_cover_letter_commit_list; + if (!cover_letter_fmt) + cover_letter_fmt = "shortlog"; + } + if (cover_letter == -1) { if (cfg.config_cover_letter == COVER_AUTO) cover_letter = (total > 1); diff --git a/t/t4014-format-patch.sh b/t/t4014-format-patch.sh index 458da80721a1e9..4891389a53aed4 100755 --- a/t/t4014-format-patch.sh +++ b/t/t4014-format-patch.sh @@ -428,6 +428,59 @@ test_expect_success 'cover letter no format' ' test_line_count = 1 result ' +test_expect_success 'cover letter config with count, subject and author' ' + test_when_finished "rm -rf patches result" && + test_when_finished "git config unset format.coverletter" && + test_when_finished "git config unset format.commitlistformat" && + git config set format.coverletter true && + git config set format.commitlistformat "log:[%(count)/%(total)] %s (%an)" && + git format-patch -o patches HEAD~2 && + grep -E "^[[[:digit:]]+/[[:digit:]]+] .* \(A U Thor\)" patches/0000-cover-letter.patch >result && + test_line_count = 2 result +' + +test_expect_success 'cover letter config with count and author' ' + test_when_finished "rm -rf patches result" && + test_when_finished "git config unset format.coverletter" && + test_when_finished "git config unset format.commitlistformat" && + git config set format.coverletter true && + git config set format.commitlistformat "log:[%(count)/%(total)] (%an)" && + git format-patch -o patches HEAD~2 && + grep -E "^[[[:digit:]]+/[[:digit:]]+] \(A U Thor\)" patches/0000-cover-letter.patch >result && + test_line_count = 2 result +' + +test_expect_success 'cover letter config commitlistformat set but no format' ' + test_when_finished "rm -rf patches result" && + test_when_finished "git config unset format.coverletter" && + test_when_finished "git config unset format.commitlistformat" && + git config set format.coverletter true && + printf "\tcommitlistformat" >> .git/config && + git format-patch -o patches HEAD~2 && + grep -E "^[[[:digit:]]+/[[:digit:]]+] .*" patches/0000-cover-letter.patch >result && + test_line_count = 2 result +' + +test_expect_success 'cover letter config commitlistformat set to shortlog' ' + test_when_finished "rm -rf patches result" && + test_when_finished "git config unset format.coverletter" && + test_when_finished "git config unset format.commitlistformat" && + git config set format.coverletter true && + git config set format.commitlistformat shortlog && + git format-patch -o patches HEAD~2 && + grep -E "^A U Thor \([[:digit:]]+\)" patches/0000-cover-letter.patch >result && + test_line_count = 1 result +' + +test_expect_success 'cover letter config commitlistformat not set' ' + test_when_finished "rm -rf patches result" && + test_when_finished "git config unset format.coverletter" && + git config set format.coverletter true && + git format-patch -o patches HEAD~2 && + grep -E "^A U Thor \([[:digit:]]+\)" patches/0000-cover-letter.patch >result && + test_line_count = 1 result +' + test_expect_success 'reroll count' ' rm -fr patches && git format-patch -o patches --cover-letter --reroll-count 4 main..side >list && From 51ed9f7e724468b8e44a7c33946dda38a335acca Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Sat, 7 Mar 2026 00:34:44 +0100 Subject: [PATCH 05/41] docs: add usage for the cover-letter fmt feature Document the new "--cover-letter-format" option in format-patch and its related configuration variable "format.commitListFormat". Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- Documentation/config/format.adoc | 5 +++++ Documentation/git-format-patch.adoc | 13 +++++++++++++ 2 files changed, 18 insertions(+) diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc index ab0710e86a3e2c..ea5ec5df7a2aee 100644 --- a/Documentation/config/format.adoc +++ b/Documentation/config/format.adoc @@ -101,6 +101,11 @@ format.coverLetter:: generate a cover-letter only when there's more than one patch. Default is false. +format.commitListFormat:: + When the `--cover-letter-format` option is not given, `format-patch` + uses the value of this variable to decide how to format the title of + each commit. Default to `shortlog`. + format.outputDirectory:: Set a custom directory to store the resulting files instead of the current working directory. All directory components will be created. diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index 9a7807ca71a528..668330a0152eb0 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -24,6 +24,7 @@ SYNOPSIS [(--reroll-count|-v) ] [--to=] [--cc=] [--[no-]cover-letter] [--quiet] + [--cover-letter-format=] [--[no-]encode-email-headers] [--no-notes | --notes[=]] [--interdiff=] @@ -321,6 +322,17 @@ feeding the result to `git send-email`. containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--cover-letter-format=:: + Specify the format in which to generate the commit list of the + patch series. This option is available if the user wants to use + an alternative to the default `shortlog` format. The accepted + values for format-spec are "shortlog" or a format string + prefixed with `log:`. + e.g. `log: %s (%an)` + If defined, defaults to the `format.commitListFormat` configuration + variable. + This option is relevant only if a cover letter is generated. + --encode-email-headers:: --no-encode-email-headers:: Encode email headers that have non-ASCII characters with @@ -452,6 +464,7 @@ with configuration variables. signOff = true outputDirectory = coverLetter = auto + commitListFormat = shortlog coverFromDescription = auto ------------ From 60cb27ed6575daafe86938fa5fcf3778fc4876f2 Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Mon, 23 Mar 2026 17:57:28 +0100 Subject: [PATCH 06/41] pretty.c: better die message %(count) and %(total) Improve die messages for commands that do not support %(count) and %(total) Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- pretty.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pretty.c b/pretty.c index 74673714c8d39a..814803980b8d1a 100644 --- a/pretty.c +++ b/pretty.c @@ -1551,7 +1551,7 @@ static size_t format_commit_one(struct strbuf *sb, /* in UTF-8 */ if (starts_with(placeholder, "(count)")) { if (!c->pretty_ctx->rev) - die(_("this format specifier can't be used with this command")); + die(_("%s is not supported by this command"), "%(count)"); strbuf_addf(sb, "%0*d", decimal_width(c->pretty_ctx->rev->total), c->pretty_ctx->rev->nr); return 7; @@ -1559,7 +1559,7 @@ static size_t format_commit_one(struct strbuf *sb, /* in UTF-8 */ if (starts_with(placeholder, "(total)")) { if (!c->pretty_ctx->rev) - die(_("this format specifier can't be used with this command")); + die(_("%s is not supported by this command"), "%(total)"); strbuf_addf(sb, "%d", c->pretty_ctx->rev->total); return 7; } From 3482b4278793f3adb1fa811dd30c637563ca9cec Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Mon, 23 Mar 2026 17:57:29 +0100 Subject: [PATCH 07/41] format-patch: refactor generate_commit_list_cover Refactor for readability and remove unnecessary initialization. Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- builtin/log.c | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/builtin/log.c b/builtin/log.c index 716ebc2701e495..997bdd608e0c11 100644 --- a/builtin/log.c +++ b/builtin/log.c @@ -1376,12 +1376,11 @@ static void generate_commit_list_cover(FILE *cover_file, const char *format, struct pretty_print_context ctx = {0}; struct rev_info rev = REV_INFO_INIT; - strbuf_init(&commit_line, 0); rev.total = n; ctx.rev = &rev; - for (int i = n - 1; i >= 0; i--) { - rev.nr = n - i; - repo_format_commit_message(the_repository, list[i], format, + for (int i = 1; i <= n; i++) { + rev.nr = i; + repo_format_commit_message(the_repository, list[n - i], format, &commit_line, &ctx); fprintf(cover_file, "%s\n", commit_line.buf); strbuf_reset(&commit_line); From 67ea2ad7d1b006194762cbfcc0b7801ffe652ca4 Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Mon, 23 Mar 2026 17:57:30 +0100 Subject: [PATCH 08/41] format-patch: rename --cover-letter-format option To align the name of the configuration variable and the name of the command line option, either one should change name. By changing the name of the option we get the added benefit of having --cover- expand to --cover-letter without ambiguity. If the user gives the --cover-letter-format option it would be reasonable to expect that the user wants to generate the cover letter despite not giving --cover-letter. Rename --cover-letter-format to --commit-list-format and make it imply --cover-letter unless --no-cover-letter is given. Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- Documentation/git-format-patch.adoc | 17 ++++++------ builtin/log.c | 4 ++- t/t4014-format-patch.sh | 41 +++++++++++++++-------------- t/t9902-completion.sh | 1 - 4 files changed, 32 insertions(+), 31 deletions(-) diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index 31fa4923354b38..45ca72e6703cff 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -24,7 +24,7 @@ SYNOPSIS [(--reroll-count|-v) ] [--to=] [--cc=] [--[no-]cover-letter] [--quiet] - [--cover-letter-format=] + [--commit-list-format=] [--[no-]encode-email-headers] [--no-notes | --notes[=]] [--interdiff=] @@ -323,16 +323,15 @@ feeding the result to `git send-email`. containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. ---cover-letter-format=:: - Specify the format in which to generate the commit list of the - patch series. This option is available if the user wants to use - an alternative to the default `shortlog` format. The accepted - values for format-spec are "shortlog" or a format string - prefixed with `log:`. +--commit-list-format=:: + Specify the format in which to generate the commit list of the patch + series. The accepted values for format-spec are "shortlog" or a format + string prefixed with `log:`. e.g. `log: %s (%an)` - If defined, defaults to the `format.commitListFormat` configuration + If not given, defaults to the `format.commitListFormat` configuration variable. - This option is relevant only if a cover letter is generated. + This option implies the use of `--cover-letter` unless + `--no-cover-letter` is given. --encode-email-headers:: --no-encode-email-headers:: diff --git a/builtin/log.c b/builtin/log.c index 997bdd608e0c11..a7f129d583f0bd 100644 --- a/builtin/log.c +++ b/builtin/log.c @@ -2014,7 +2014,7 @@ int cmd_format_patch(int argc, N_("print patches to standard out")), OPT_BOOL(0, "cover-letter", &cover_letter, N_("generate a cover letter")), - OPT_STRING(0, "cover-letter-format", &cover_letter_fmt, N_("format-spec"), + OPT_STRING(0, "commit-list-format", &cover_letter_fmt, N_("format-spec"), N_("format spec used for the commit list in the cover letter")), OPT_BOOL(0, "numbered-files", &just_numbers, N_("use simple number sequence for output file names")), @@ -2358,6 +2358,8 @@ int cmd_format_patch(int argc, cover_letter_fmt = cfg.fmt_cover_letter_commit_list; if (!cover_letter_fmt) cover_letter_fmt = "shortlog"; + } else if (cover_letter == -1) { + cover_letter = 1; } if (cover_letter == -1) { diff --git a/t/t4014-format-patch.sh b/t/t4014-format-patch.sh index 7c67bdf92267f6..d2a775f78d2cf2 100755 --- a/t/t4014-format-patch.sh +++ b/t/t4014-format-patch.sh @@ -383,49 +383,50 @@ test_expect_success 'filename limit applies only to basename' ' test_expect_success 'cover letter with subject, author and count' ' rm -rf patches && test_when_finished "git reset --hard HEAD~1" && - test_when_finished "rm -rf patches result test_file" && + test_when_finished "rm -rf patches test_file" && touch test_file && git add test_file && git commit -m "This is a subject" && - git format-patch --cover-letter \ - --cover-letter-format="log:[%(count)/%(total)] %s (%an)" -o patches HEAD~1 && - grep "^\[1/1\] This is a subject (A U Thor)$" patches/0000-cover-letter.patch >result && - test_line_count = 1 result + git format-patch --commit-list-format="log:[%(count)/%(total)] %s (%an)" \ + -o patches HEAD~1 && + test_grep "^\[1/1\] This is a subject (A U Thor)$" patches/0000-cover-letter.patch ' -test_expected_success 'cover letter with author and count' ' +test_expect_success 'cover letter with author and count' ' test_when_finished "git reset --hard HEAD~1" && - test_when_finished "rm -rf patches result test_file" && + test_when_finished "rm -rf patches test_file" && touch test_file && git add test_file && git commit -m "This is a subject" && - git format-patch --cover-letter \ - --cover-letter-format="log:[%(count)/%(total)] %an" -o patches HEAD~1 && - grep "^\[1/1\] A U Thor$" patches/0000-cover-letter.patch >result && - test_line_count = 1 result + git format-patch --commit-list-format="log:[%(count)/%(total)] %an" \ + -o patches HEAD~1 && + test_grep "^\[1/1\] A U Thor$" patches/0000-cover-letter.patch ' test_expect_success 'cover letter shortlog' ' test_when_finished "git reset --hard HEAD~1" && - test_when_finished "rm -rf patches result test_file" && + test_when_finished "rm -rf expect patches result test_file" && + cat >expect <<-"EOF" && + A U Thor (1): + This is a subject + EOF touch test_file && git add test_file && git commit -m "This is a subject" && - git format-patch --cover-letter --cover-letter-format=shortlog \ - -o patches HEAD~1 && - sed -n -e "/^A U Thor/p;" patches/0000-cover-letter.patch >result && - test_line_count = 1 result + git format-patch --commit-list-format=shortlog -o patches HEAD~1 && + grep -E -A 1 "^A U Thor \([[:digit:]]+\):$" patches/0000-cover-letter.patch >result && + cat result && + test_cmp expect result ' -test_expect_success 'cover letter no format' ' +test_expect_success 'no cover letter but with format specified' ' test_when_finished "git reset --hard HEAD~1" && test_when_finished "rm -rf patches result test_file" && touch test_file && git add test_file && git commit -m "This is a subject" && - git format-patch --cover-letter -o patches HEAD~1 && - sed -n -e "/^A U Thor/p;" patches/0000-cover-letter.patch >result && - test_line_count = 1 result + git format-patch --no-cover-letter --commit-list-format="[%(count)] %s" -o patches HEAD~1 && + test_path_is_missing patches/0000-cover-letter.patch ' test_expect_success 'cover letter config with count, subject and author' ' diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh index 35e20b53511499..2f9a597ec7f493 100755 --- a/t/t9902-completion.sh +++ b/t/t9902-completion.sh @@ -2775,7 +2775,6 @@ test_expect_success PERL 'send-email' ' test_completion "git send-email --cov" <<-\EOF && --cover-from-description=Z --cover-letter Z - --cover-letter-format=Z EOF test_completion "git send-email --val" <<-\EOF && --validate Z From 344f00ef9d0863f8b05e26253664fa6993ac5ac9 Mon Sep 17 00:00:00 2001 From: Mirko Faina Date: Mon, 23 Mar 2026 17:57:31 +0100 Subject: [PATCH 09/41] docs/pretty-formats: add %(count) and %(total) When --commit-list-format was introduced to format-patch, two new placeholders were added to the PRETTY FORMATS code without being documented. Do so now. Signed-off-by: Mirko Faina Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc index 5405e57a6079c5..2ae0eb11a97988 100644 --- a/Documentation/pretty-formats.adoc +++ b/Documentation/pretty-formats.adoc @@ -253,6 +253,10 @@ The placeholders are: linkgit:git-rev-list[1]) +%d+:: ref names, like the --decorate option of linkgit:git-log[1] +%D+:: ref names without the " (", ")" wrapping. ++%(count)+:: the number of a patch within a patch series. Used only in + `--commit-list-format` in `format-patch` ++%(total)+:: the total number of patches in a patch series. Used only in + `--commit-list-format` in `format-patch` ++%(decorate++`[: