Subject: Re: [PATCH v2] docs: fix --commit-list-format related entries

From: Mirko Faina <[email-masked]>
Date: Thu, 26 Mar 2026 21:53:56 +0100

On Thu, Mar 26, 2026 at 01:45:15PM -0700, Junio C Hamano wrote:
> Being verbose is usually a good way to discourage readers from
> reading.

You're right, and most of the proposed changes do shorten the text very
well (will apply), but...

> Let's see if we can shorten them without losing information.
> 
> >  --commit-list-format=<format-spec>::
> >  	Specify the format in which to generate the commit list of the patch
> > +	series. The accepted values for format-spec are `shortlog`, `modern` or
> > +	a format-string prefixed with `log:`. E.g. `log: %s (%an)`.
> > +	Modern is the same as `log:[%(count)/%(total)] %s`.
> 
> "Modern" -> "`modern`".
> 
> This is necessary to stress the fact that this is a fixed token the
> user must give verbatim.
> 
> > +	The user is allowed to drop the `log:` prefix if the format-string
> > +	contains a '%' character. The '%' is expected as part of a placeholder
> > +	but this is not validated by git.
> 
>     The `log:` prefix can be omitted if the format-string has a `%`
>     in it (expecting that it is part of `%<placeholder>`).
> 
> > +	If not given, defaults to `shortlog` unless the
> > +	`format.commitListFormat` configuration variable is set.
> 
>     Defaults to the `format.commitListFormat` configuration
>     variable, if set, or `shortlog`.
> 
> > +	This option given from the command-line implies the use of
> > +	`--cover-letter` unless `--no-cover-letter` is given. Note that
> > +	`format.commitListFormat` being set does not imply the use of
> > +	`--cover-letter`.
> 
>     The use of this command line option implies `--cover-letter`,
>     unless explicitly countermanded with `--no-cover-letter`.

this part in particular is no different than the original text:

    This option implies the use of `--cover-letter` unless
    `--no-cover-letter` is given.

If we want to emphasize that the configuration variable doesn't imply
--cover-letter, we have to add the note on `format.commitListFormat`.

Thank you