Re: [PATCH v2] docs: fix --commit-list-format related entries
- From
Mirko Faina <mroik@delayed.space>
- Date
- Mar 26, 2026, 20:53 UTC
- Message-ID
- <acWbpJTRusOv6bPk@exploit>
- In-Reply-To
- <xmqqse9mnwv8.fsf@gitster.g>
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...
Show 33 quoted lines
> 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