From: Mirko Faina <mroik@delayed•space>
To: git@vger•kernel.org
Cc: Mirko Faina <mroik@delayed•space>,
Junio C Hamano <gitster@pobox•com>, Jeff King <peff@peff•net>
Subject: [PATCH v6 3/5] format-patch: add ability to use alt cover format
Date: Fri, 6 Mar 2026 23:58:46 +0100 [thread overview]
Message-ID: <316c9e76ee49d73aff75b63299c970e9f55f79b6.1772837832.git.mroik@delayed.space> (raw)
In-Reply-To: <cover.1772837832.git.mroik@delayed.space>
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 <mroik@delayed•space>
---
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 0d12272031..95e5d9755f 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 21d6d0cd9e..458da80721 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 964e1f1569..4f760a7468 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
--
2.53.0.5.g1a4ba6dc33
next prev parent reply other threads:[~2026-03-06 22:59 UTC|newest]
Thread overview: 113+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-02-20 23:06 [RFC PATCH] format-patch: better commit list for cover letter Mirko Faina
2026-02-20 23:55 ` [RFC PATCH v2] " Mirko Faina
2026-02-21 0:51 ` Mirko Faina
2026-02-21 4:54 ` [RFC PATCH] " Junio C Hamano
2026-02-21 5:18 ` Mirko Faina
2026-02-21 5:55 ` Junio C Hamano
2026-02-21 6:02 ` Junio C Hamano
2026-02-21 15:59 ` Mirko Faina
2026-02-21 17:33 ` Junio C Hamano
2026-02-21 19:16 ` Mirko Faina
2026-02-24 4:03 ` [PATCH 0/3] format-patch: add cover-letter-format option Mirko Faina
2026-02-24 4:06 ` Mirko Faina
2026-02-24 9:29 ` [PATCH v2 0/2] " Mirko Faina
2026-02-24 9:29 ` [PATCH v2 1/2] format-patch: add ability to use alt cover format Mirko Faina
2026-02-24 17:40 ` Junio C Hamano
2026-02-24 23:54 ` Mirko Faina
2026-02-25 0:29 ` Junio C Hamano
2026-02-25 13:47 ` Jeff King
2026-02-24 20:25 ` Junio C Hamano
2026-02-25 13:56 ` Jeff King
2026-02-25 22:55 ` Mirko Faina
2026-02-24 9:29 ` [PATCH v2 2/2] format-patch: add commitListFormat config Mirko Faina
2026-02-24 18:07 ` Junio C Hamano
2026-02-25 0:14 ` Mirko Faina
2026-02-25 17:25 ` Junio C Hamano
2026-02-26 21:40 ` Mirko Faina
2026-02-26 22:19 ` Junio C Hamano
2026-02-24 20:38 ` [PATCH v2 0/2] format-patch: add cover-letter-format option Junio C Hamano
2026-02-24 21:39 ` Junio C Hamano
2026-02-25 0:19 ` Mirko Faina
2026-02-25 2:46 ` Junio C Hamano
2026-02-27 1:52 ` [PATCH v3 0/4] " Mirko Faina
2026-02-27 1:52 ` [PATCH v3 1/4] pretty.c: add %(count) and %(total) placeholders Mirko Faina
2026-02-27 1:52 ` [PATCH v3 2/4] format-patch: move cover letter summary generation Mirko Faina
2026-02-27 1:52 ` [PATCH v3 3/4] format-patch: add ability to use alt cover format Mirko Faina
2026-02-27 4:23 ` Junio C Hamano
2026-02-27 12:41 ` Mirko Faina
2026-02-27 1:52 ` [PATCH v3 4/4] format-patch: add commitListFormat config Mirko Faina
2026-02-27 13:18 ` [PATCH v4 0/4] format-patch: add cover-letter-format option Mirko Faina
2026-02-27 13:18 ` [PATCH v4 1/4] pretty.c: add %(count) and %(total) placeholders Mirko Faina
2026-02-27 13:18 ` [PATCH v4 2/4] format-patch: move cover letter summary generation Mirko Faina
2026-02-27 13:18 ` [PATCH v4 3/4] format-patch: add ability to use alt cover format Mirko Faina
2026-02-27 13:18 ` [PATCH v4 4/4] format-patch: add commitListFormat config Mirko Faina
2026-02-27 16:42 ` [PATCH v4 5/4] docs: add usage for the cover-letter fmt feature Mirko Faina
2026-02-27 17:51 ` [PATCH v4 4/4] format-patch: add commitListFormat config Junio C Hamano
2026-02-27 21:51 ` Mirko Faina
2026-02-27 22:21 ` Junio C Hamano
2026-02-27 22:48 ` [PATCH v5 0/5] format-patch: add cover-letter-format option Mirko Faina
2026-02-27 22:48 ` [PATCH v5 1/5] pretty.c: add %(count) and %(total) placeholders Mirko Faina
2026-02-27 22:48 ` [PATCH v5 2/5] format-patch: move cover letter summary generation Mirko Faina
2026-02-27 22:48 ` [PATCH v5 3/5] format-patch: add ability to use alt cover format Mirko Faina
2026-02-27 22:48 ` [PATCH v5 4/5] format-patch: add commitListFormat config Mirko Faina
2026-02-27 22:48 ` [PATCH v5 5/5] docs: add usage for the cover-letter fmt feature Mirko Faina
2026-03-06 22:33 ` [PATCH v5 0/5] format-patch: add cover-letter-format option Junio C Hamano
2026-03-06 22:49 ` Mirko Faina
2026-03-06 22:58 ` [PATCH v6 " Mirko Faina
2026-03-06 22:58 ` [PATCH v6 1/5] pretty.c: add %(count) and %(total) placeholders Mirko Faina
2026-03-06 22:58 ` [PATCH v6 2/5] format-patch: move cover letter summary generation Mirko Faina
2026-03-06 22:58 ` Mirko Faina [this message]
2026-03-10 22:14 ` [PATCH v6 3/5] format-patch: add ability to use alt cover format Junio C Hamano
2026-03-10 22:32 ` Mirko Faina
2026-03-06 22:58 ` [PATCH v6 4/5] format-patch: add commitListFormat config Mirko Faina
2026-03-06 22:58 ` [PATCH v6 5/5] docs: add usage for the cover-letter fmt feature Mirko Faina
2026-03-06 23:18 ` Junio C Hamano
2026-03-06 23:34 ` [PATCH v7 0/5] format-patch: add cover-letter-format option Mirko Faina
2026-03-06 23:34 ` [PATCH v7 1/5] pretty.c: add %(count) and %(total) placeholders Mirko Faina
2026-03-10 14:32 ` Phillip Wood
2026-03-10 20:55 ` Mirko Faina
2026-03-06 23:34 ` [PATCH v7 2/5] format-patch: move cover letter summary generation Mirko Faina
2026-03-06 23:34 ` [PATCH v7 3/5] format-patch: add ability to use alt cover format Mirko Faina
2026-03-10 14:33 ` Phillip Wood
2026-03-10 21:05 ` Mroik
2026-03-06 23:34 ` [PATCH v7 4/5] format-patch: add commitListFormat config Mirko Faina
2026-03-10 14:34 ` Phillip Wood
2026-03-10 16:45 ` Junio C Hamano
2026-03-10 21:23 ` Mirko Faina
2026-03-11 10:38 ` Phillip Wood
2026-03-11 17:13 ` Junio C Hamano
2026-03-11 10:32 ` Phillip Wood
2026-03-11 17:18 ` Junio C Hamano
2026-03-10 21:19 ` Mirko Faina
2026-03-06 23:34 ` [PATCH v7 5/5] docs: add usage for the cover-letter fmt feature Mirko Faina
2026-03-10 9:51 ` Bert Wesarg
2026-03-10 14:34 ` Phillip Wood
2026-03-12 16:20 ` [PATCH v8 0/4] format-patch: add cover-letter-format option Mirko Faina
2026-03-12 16:20 ` [PATCH v8 1/4] format-patch: move cover letter summary generation Mirko Faina
2026-03-12 16:28 ` Junio C Hamano
2026-03-12 16:20 ` [PATCH v8 2/4] format-patch: add ability to use alt cover format Mirko Faina
2026-03-12 16:52 ` Junio C Hamano
2026-03-12 17:18 ` Mirko Faina
2026-03-12 17:25 ` Junio C Hamano
2026-03-12 17:27 ` Junio C Hamano
2026-03-13 10:38 ` Phillip Wood
2026-03-13 17:20 ` Junio C Hamano
2026-03-13 19:17 ` Mirko Faina
2026-03-13 20:22 ` Junio C Hamano
2026-03-12 16:20 ` [PATCH v8 3/4] format-patch: add "chronological" format for cover Mirko Faina
2026-03-12 16:55 ` Junio C Hamano
2026-03-12 16:20 ` [PATCH v8 4/4] format-patch: add commitListFormat config Mirko Faina
2026-03-12 17:00 ` Junio C Hamano
2026-03-12 17:20 ` [PATCH v8 0/4] format-patch: add cover-letter-format option Junio C Hamano
2026-03-12 17:45 ` Mirko Faina
2026-03-12 18:12 ` Junio C Hamano
2026-02-24 4:03 ` [PATCH 1/3] pretty.c: fix null pointer dereference Mirko Faina
2026-02-24 6:25 ` Junio C Hamano
2026-02-24 7:08 ` Mirko Faina
2026-02-24 7:43 ` Mirko Faina
2026-02-24 8:41 ` Jeff King
2026-02-24 4:03 ` [PATCH 2/3] format-patch: add ability to use alt cover format Mirko Faina
2026-02-24 9:02 ` Jeff King
2026-02-24 9:09 ` Mirko Faina
2026-02-24 9:18 ` Jeff King
2026-02-24 4:03 ` [PATCH 3/3] format-patch: add commitListFormat config Mirko Faina
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=316c9e76ee49d73aff75b63299c970e9f55f79b6.1772837832.git.mroik@delayed.space \
--to=mroik@delayed$(echo .)space \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=peff@peff$(echo .)net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox