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-<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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Mirko Faina committed
Mar 23, 2026 at 17:57 UTC
67ea2ad7d1b006194762cbfcc0b7801ffe652ca4
4 files changed
+32
-31
Documentation/git-format-patch.adoc
+8
-9
@@ -24,7 +24,7 @@ SYNOPSIS
24
[(--reroll-count|-v) <n>]
25
[--to=<email>] [--cc=<email>]
26
[--[no-]cover-letter] [--quiet]
27
- [--cover-letter-format=<format-spec>]
27
+ [--commit-list-format=<format-spec>]
28
[--[no-]encode-email-headers]
29
[--no-notes | --notes[=<ref>]]
30
[--interdiff=<previous>]
@@ -323,16 +323,15 @@ feeding the result to `git send-email`.
323
containing the branch description, shortlog and the overall diffstat. You can
324
fill in a description in the file before sending it out.
325
326
---cover-letter-format=<format-spec>::
327
- Specify the format in which to generate the commit list of the
328
- patch series. This option is available if the user wants to use
329
- an alternative to the default `shortlog` format. The accepted
330
- values for format-spec are "shortlog" or a format string
331
- prefixed with `log:`.
326
+--commit-list-format=<format-spec>::
327
+ Specify the format in which to generate the commit list of the patch
328
+ series. The accepted values for format-spec are "shortlog" or a format
329
+ string prefixed with `log:`.
330
e.g. `log: %s (%an)`
333
- If defined, defaults to the `format.commitListFormat` configuration
331
+ If not given, defaults to the `format.commitListFormat` configuration
332
variable.
335
- This option is relevant only if a cover letter is generated.
333
+ This option implies the use of `--cover-letter` unless
334
+ `--no-cover-letter` is given.
335
336
--encode-email-headers::
337
--no-encode-email-headers::
builtin/log.c
+3
-1
@@ -2014,7 +2014,7 @@ int cmd_format_patch(int argc,
2014
N_("print patches to standard out")),
2015
OPT_BOOL(0, "cover-letter", &cover_letter,
2016
N_("generate a cover letter")),
2017
- OPT_STRING(0, "cover-letter-format", &cover_letter_fmt, N_("format-spec"),
2017
+ OPT_STRING(0, "commit-list-format", &cover_letter_fmt, N_("format-spec"),
2018
N_("format spec used for the commit list in the cover letter")),
2019
OPT_BOOL(0, "numbered-files", &just_numbers,
2020
N_("use simple number sequence for output file names")),
@@ -2358,6 +2358,8 @@ int cmd_format_patch(int argc,
2358
cover_letter_fmt = cfg.fmt_cover_letter_commit_list;
2359
if (!cover_letter_fmt)
2360
cover_letter_fmt = "shortlog";
2361
+ } else if (cover_letter == -1) {
2362
+ cover_letter = 1;
2363
}
2364
2365
if (cover_letter == -1) {
t/t4014-format-patch.sh
+21
-20
@@ -383,49 +383,50 @@ test_expect_success 'filename limit applies only to basename' '
383
test_expect_success 'cover letter with subject, author and count' '
384
rm -rf patches &&
385
test_when_finished "git reset --hard HEAD~1" &&
386
- test_when_finished "rm -rf patches result test_file" &&
386
+ test_when_finished "rm -rf patches test_file" &&
387
touch test_file &&
388
git add test_file &&
389
git commit -m "This is a subject" &&
390
- git format-patch --cover-letter \
391
- --cover-letter-format="log:[%(count)/%(total)] %s (%an)" -o patches HEAD~1 &&
392
- grep "^\[1/1\] This is a subject (A U Thor)$" patches/0000-cover-letter.patch >result &&
393
- test_line_count = 1 result
390
+ git format-patch --commit-list-format="log:[%(count)/%(total)] %s (%an)" \
391
+ -o patches HEAD~1 &&
392
+ test_grep "^\[1/1\] This is a subject (A U Thor)$" patches/0000-cover-letter.patch
393
'
394
396
-test_expected_success 'cover letter with author and count' '
395
+test_expect_success 'cover letter with author and count' '
396
test_when_finished "git reset --hard HEAD~1" &&
398
- test_when_finished "rm -rf patches result test_file" &&
397
+ test_when_finished "rm -rf patches test_file" &&
398
touch test_file &&
399
git add test_file &&
400
git commit -m "This is a subject" &&
402
- git format-patch --cover-letter \
403
- --cover-letter-format="log:[%(count)/%(total)] %an" -o patches HEAD~1 &&
404
- grep "^\[1/1\] A U Thor$" patches/0000-cover-letter.patch >result &&
405
- test_line_count = 1 result
401
+ git format-patch --commit-list-format="log:[%(count)/%(total)] %an" \
402
+ -o patches HEAD~1 &&
403
+ test_grep "^\[1/1\] A U Thor$" patches/0000-cover-letter.patch
404
'
405
406
test_expect_success 'cover letter shortlog' '
407
test_when_finished "git reset --hard HEAD~1" &&
410
- test_when_finished "rm -rf patches result test_file" &&
408
+ test_when_finished "rm -rf expect patches result test_file" &&
409
+ cat >expect <<-"EOF" &&
410
+ A U Thor (1):
411
+ This is a subject
412
+ EOF
413
touch test_file &&
414
git add test_file &&
415
git commit -m "This is a subject" &&
414
- git format-patch --cover-letter --cover-letter-format=shortlog \
415
- -o patches HEAD~1 &&
416
- sed -n -e "/^A U Thor/p;" patches/0000-cover-letter.patch >result &&
417
- test_line_count = 1 result
416
+ git format-patch --commit-list-format=shortlog -o patches HEAD~1 &&
417
+ grep -E -A 1 "^A U Thor \([[:digit:]]+\):$" patches/0000-cover-letter.patch >result &&
418
+ cat result &&
419
+ test_cmp expect result
420
'
421
420
-test_expect_success 'cover letter no format' '
422
+test_expect_success 'no cover letter but with format specified' '
423
test_when_finished "git reset --hard HEAD~1" &&
424
test_when_finished "rm -rf patches result test_file" &&
425
touch test_file &&
426
git add test_file &&
427
git commit -m "This is a subject" &&
426
- git format-patch --cover-letter -o patches HEAD~1 &&
427
- sed -n -e "/^A U Thor/p;" patches/0000-cover-letter.patch >result &&
428
- test_line_count = 1 result
428
+ git format-patch --no-cover-letter --commit-list-format="[%(count)] %s" -o patches HEAD~1 &&
429
+ test_path_is_missing patches/0000-cover-letter.patch
430
'
431
432
test_expect_success 'cover letter config with count, subject and author' '
t/t9902-completion.sh
-1
@@ -2775,7 +2775,6 @@ test_expect_success PERL 'send-email' '
2775
test_completion "git send-email --cov" <<-\EOF &&
2776
--cover-from-description=Z
2777
--cover-letter Z
2778
- --cover-letter-format=Z
2778
EOF
2779
test_completion "git send-email --val" <<-\EOF &&
2780
--validate Z