From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 06 Mar 2026 23:18:53 GMT
Subject: Re: [PATCH v6 5/5] docs: add usage for the cover-letter fmt feature
Message-ID: <xmqq8qc4wnqa.fsf@gitster.g>
In-Reply-To: <1a4ba6dc338e82df1d58c277031d3ec2ec2ccf83.1772837832.git.mroik@delayed.space>

Mirko Faina <mroik@delayed.space> writes:

> Document the new "--cover-letter-format" option in format-patch and its
> related config variable "format.commitListFormat".
>
> Signed-off-by: Mirko Faina <mroik@delayed.space>
> ---
>  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..151e574052 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 config is coupled with
> +	the `--cover-letter-format` format-patch option command and they both
> +	accept the same values. Default is `shortlog`.

Let's not call "configuration variable" a "config".  When a variable
gives the default value for a command line option, we usually do not
say "coupled with".

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

perhaps?

> diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
> index 9a7807ca71..42d2633860 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.

Somewhere in this paragraph, it must mention that format.commitListFormat
gives the default value when this command line option is not given.

Everything else in the changes since the previous iteration,
including the parameter list to generate_commit_list_cover() that
shows the level of attention to details, looked great to me.

Thanks.