[PATCH v4 5/4] docs: add usage for the cover-letter fmt feature

From

Mirko Faina <mroik@delayed.space>

Date

Feb 27, 2026, 16:42 UTC

Message-ID

<20260227164234.11632-1-mroik@delayed.space>

In-Reply-To

<f9ee8e24001aa16e5df3dc0bbfccd1b381e37d85.1772196510.git.mroik@delayed.space>

Signed-off-by: Mirko Faina <mroik@delayed.space>
---
Sorry, forgot to update the docs. This patch is to be applied on top of
patch #4 of the series.

 Documentation/config/format.adoc    |  6 ++++++
 Documentation/git-format-patch.adoc | 11 +++++++++++
 2 files changed, 17 insertions(+)

diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc
index ab0710e86a..b91e59321c 100644
--- a/Documentation/config/format.adoc
+++ b/Documentation/config/format.adoc
@@ -101,6 +101,12 @@ format.coverLetter::
 	generate a cover-letter only when there's more than one patch.
 	Default is false.
 
+format.commitListFormat::
+	A format string that specifies how to generate the commit list of a
+	cover-letter when format-patch is invoked. This is the config coupled
+	with `--cover-letter-format` in the format-patch command.
+	Default is "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 9a7807ca71..bdcb5f989c 100644
--- a/Documentation/git-format-patch.adoc
+++ b/Documentation/git-format-patch.adoc
@@ -24,6 +24,7 @@ SYNOPSIS
 		   [(--reroll-count|-v) <n>]
 		   [--to=<email>] [--cc=<email>]
 		   [--[no-]cover-letter] [--quiet]
+		   [--cover-letter-format=<format-spec>]
 		   [--[no-]encode-email-headers]
 		   [--no-notes | --notes[=<ref>]]
 		   [--interdiff=<previous>]
@@ -321,6 +322,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:`.  
+	e.g. `log: %s (%an)`  
+	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 +462,7 @@ with configuration variables.
 	signOff = true
 	outputDirectory = <directory>
 	coverLetter = auto
+	commitListFormat = shortlog
 	coverFromDescription = auto
 ------------
 

-- 
2.53.0