From 51ed9f7e724468b8e44a7c33946dda38a335acca Mon Sep 17 00:00:00 2001
From: Mirko Faina <mroik@delayed.space>
Date: Sat, 7 Mar 2026 00:34:44 +0100
Subject: 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>
---
 Documentation/git-format-patch.adoc | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'Documentation/git-format-patch.adoc')

diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
index 9a7807ca71..668330a015 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,17 @@ 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)`
+	If defined, defaults to the `format.commitListFormat` configuration
+	variable.
+	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 +464,7 @@ with configuration variables.
 	signOff = true
 	outputDirectory = <directory>
 	coverLetter = auto
+	commitListFormat = shortlog
 	coverFromDescription = auto
 ------------
 
-- 
cgit v1.3

