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

[Phillip Wood <phillip.wood123@gmail.com>]

On 06/03/2026 23:34, Mirko Faina wrote:
> 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>
> ---
>   Documentation/config/format.adoc    |  5 +++++
>   Documentation/git-format-patch.adoc | 13 +++++++++++++
>   2 files changed, 18 insertions(+)
> 
> diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc
> index ab0710e86a..ea5ec5df7a 100644
> --- a/Documentation/config/format.adoc
> +++ b/Documentation/config/format.adoc
> @@ -101,6 +101,11 @@ format.coverLetter::
>   	generate a cover-letter only when there's more than one patch.
>   	Default is false.
>   
> +format.commitListFormat::
> +	When the `--cover-letter-format` option is not given, `format-patch`
> +	uses the value of this variable to decide how to format the title of
> +	each commit. Default to `shortlog`.

Being able to set a default format like this is useful. It would be 
helpful to document what the expected format is. This should be added to 
patch 4 which adds support for the config variable.

> +
>   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..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.

This should be added in patch 3 which adds the --cover-letter-format option.

Thanks

Phillip

>   --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
>   ------------
>