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

From: Junio C Hamano <[email-masked]>
Date: Thu, 26 Mar 2026 12:10:08 -0700

Mirko Faina <[email-masked]> writes:

>  	The user is allowed to drop the prefix if the format-string contains a
>  	`%<placeholder>`.

As you do not, and we do not want to, parse and validate
placeholder, it is more honest to phrase this like

	A format-string that contains a `%` letter is treated as a
	custom format even if it lacks the `log:` prefix.

even if we omit saying ", expecting that '%' is part of a %<prefix>",
or ", similar to how `git log --pretty=<format>` works as if the
<format> were prefixed with `format:`".

> -	If not given, defaults to the `format.commitListFormat` configuration
> -	variable.
> -	This option implies the use of `--cover-letter` unless
> -	`--no-cover-letter` is given.
> +	If not given, defaults to `shortlog` unless the
> +	`format.commitListFormat` configuration variable is set. This option
> +	implies the use of `--cover-letter` unless `--no-cover-letter` is
> +	given.

A new reader would wonder if setting the configuration variable
would count as a trigger to "This option implies", even though we
only want an explicit command line option to do so.

Here is myu attempt to rephrase it, but

    Use of this option from the command line implies `--cover-letter`;
    an explicit `--no-cover-letter` can defeat it.

I am not sure how much better it is from the original.