git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v3 3/8] format-patch: rename --cover-letter-format option

From
Mirko Faina <mroik@delayed.space>
Date
Mar 23, 2026, 16:57 UTC
Message-ID
<5d061d6398bae368a7cc95700b5df44854d1d8e8.1774284699.git.mroik@delayed.space>
In-Reply-To
<cover.1774284699.git.mroik@delayed.space>

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-<TAB> 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 <mroik@delayed.space>
---
 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 31fa492335..45ca72e670 100644
--- a/Documentation/git-format-patch.adoc
+++ b/Documentation/git-format-patch.adoc
@@ -24,7 +24,7 @@ SYNOPSIS
 		   [(--reroll-count|-v) <n>]
 		   [--to=<email>] [--cc=<email>]
 		   [--[no-]cover-letter] [--quiet]
-		   [--cover-letter-format=<format-spec>]
+		   [--commit-list-format=<format-spec>]
 		   [--[no-]encode-email-headers]
 		   [--no-notes | --notes[=<ref>]]
 		   [--interdiff=<previous>]
@@ -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=<format-spec>::
-	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=<format-spec>::
+	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 997bdd608e..a7f129d583 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 7c67bdf922..d2a775f78d 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 35e20b5351..2f9a597ec7 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
-- 
2.53.0.1118.gaef5881109
Previous: Mirko FainaNext: Mirko Faina
Message 28 of 42 in “improve "git format-patch --commit-list-format"”
  1. 0/7 improve "git format-patch --commit-list-format"Mirko Faina, Mar 14, 2026
  2. 1/7 pretty.c: better die message %(count) and %(total)Mirko Faina, Mar 14, 2026
  3. 3/7 format-patch: rename --cover-letter-format optionMirko Faina, Mar 14, 2026
  4. 2/7 format-patch: refactor generate_commit_list_coverMirko Faina, Mar 14, 2026
  5. 4/7 format.commitListFormat: strip meaning from emptyMirko Faina, Mar 14, 2026
  6. 5/7 format-patch: wrap generate_commit_list_cover()Mirko Faina, Mar 14, 2026
  7. Kristoffer HaugsbakkMar 17, 2026
  8. Mirko FainaMar 17, 2026
  9. 6/7 format-patch: add preset for --commit-list-formatMirko Faina, Mar 14, 2026
  10. 7/7 format-patch: --commit-list-format without prefixMirko Faina, Mar 14, 2026
  11. Kristoffer HaugsbakkMar 17, 2026
  12. Mirko FainaMar 17, 2026
  13. 0/8 improve "git format-patch --commit-list-format"Mirko Faina, Mar 19, 2026
  14. 1/8 pretty.c: better die message %(count) and %(total)Mirko Faina, Mar 19, 2026
  15. 2/8 format-patch: refactor generate_commit_list_coverMirko Faina, Mar 19, 2026
  16. 4/8 docs/pretty-formats: add %(count) and %(total)Mirko Faina, Mar 19, 2026
  17. Kristoffer HaugsbakkMar 23, 2026
  18. Mirko FainaMar 23, 2026
  19. 3/8 format-patch: rename --cover-letter-format optionMirko Faina, Mar 19, 2026
  20. 5/8 format.commitListFormat: strip meaning from emptyMirko Faina, Mar 19, 2026
  21. 6/8 format-patch: wrap generate_commit_list_cover()Mirko Faina, Mar 19, 2026
  22. 8/8 format-patch: --commit-list-format without prefixMirko Faina, Mar 19, 2026
  23. 7/8 format-patch: add preset for --commit-list-formatMirko Faina, Mar 19, 2026
  24. 0/8 improve "git format-patch --commit-list-format"Mirko Faina, Mar 23, 2026
  25. 1/8 pretty.c: better die message %(count) and %(total)Mirko Faina, Mar 23, 2026
  26. 2/8 format-patch: refactor generate_commit_list_coverMirko Faina, Mar 23, 2026
  27. 4/8 docs/pretty-formats: add %(count) and %(total)Mirko Faina, Mar 23, 2026
  28. 3/8 format-patch: rename --cover-letter-format optionMirko Faina, Mar 23, 2026
  29. 5/8 format.commitListFormat: strip meaning from emptyMirko Faina, Mar 23, 2026
  30. 6/8 format-patch: wrap generate_commit_list_cover()Mirko Faina, Mar 23, 2026
  31. 8/8 format-patch: --commit-list-format without prefixMirko Faina, Mar 23, 2026
  32. 7/8 format-patch: add preset for --commit-list-formatMirko Faina, Mar 23, 2026
  33. Junio C HamanoMar 23, 2026
  34. Kristoffer HaugsbakkMar 24, 2026
  35. Phillip WoodMar 26, 2026
  36. Junio C HamanoMar 26, 2026
  37. Mirko FainaMar 27, 2026
  38. Junio C HamanoMar 27, 2026
  39. Mirko FainaMar 27, 2026
  40. Junio C HamanoMar 27, 2026
  41. D. Ben KnobleMar 26, 2026
  42. Mirko FainaMar 26, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.