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 <mroik@delayed.space> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Mirko Faina committed
Mar 7, 2026 at 00:34 UTC
51ed9f7e724468b8e44a7c33946dda38a335acca
2 files changed
+18
Documentation/config/format.adoc
+5
@@ -101,6 +101,11 @@ format.coverLetter::
101
generate a cover-letter only when there's more than one patch.
102
Default is false.
103
104
+format.commitListFormat::
105
+ When the `--cover-letter-format` option is not given, `format-patch`
106
+ uses the value of this variable to decide how to format the title of
107
+ each commit. Default to `shortlog`.
108
+
109
format.outputDirectory::
110
Set a custom directory to store the resulting files instead of the
111
current working directory. All directory components will be created.
Documentation/git-format-patch.adoc
+13
@@ -24,6 +24,7 @@ SYNOPSIS
24
[(--reroll-count|-v) <n>]
25
[--to=<email>] [--cc=<email>]
26
[--[no-]cover-letter] [--quiet]
27
+ [--cover-letter-format=<format-spec>]
28
[--[no-]encode-email-headers]
29
[--no-notes | --notes[=<ref>]]
30
[--interdiff=<previous>]
@@ -321,6 +322,17 @@ feeding the result to `git send-email`.
322
containing the branch description, shortlog and the overall diffstat. You can
323
fill in a description in the file before sending it out.
324
325
+--cover-letter-format=<format-spec>::
326
+ Specify the format in which to generate the commit list of the
327
+ patch series. This option is available if the user wants to use
328
+ an alternative to the default `shortlog` format. The accepted
329
+ values for format-spec are "shortlog" or a format string
330
+ prefixed with `log:`.
331
+ e.g. `log: %s (%an)`
332
+ If defined, defaults to the `format.commitListFormat` configuration
333
+ variable.
334
+ This option is relevant only if a cover letter is generated.
335
+
336
--encode-email-headers::
337
--no-encode-email-headers::
338
Encode email headers that have non-ASCII characters with
@@ -452,6 +464,7 @@ with configuration variables.
464
signOff = true
465
outputDirectory = <directory>
466
coverLetter = auto
467
+ commitListFormat = shortlog
468
coverFromDescription = auto
469
------------
470