Re: [PATCH v2] docs: fix --commit-list-format related entries
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 26, 2026, 20:45 UTC
- Message-ID
- <xmqqse9mnwv8.fsf@gitster.g>
- In-Reply-To
- <20260326200643.20251-1-mroik@delayed.space>
Mirko Faina <mroik@delayed.space> writes:
Show 6 quoted lines
> Ended up with something more verbose compared to what Junio proposed, > but it might help the user to better understand why we check for the '%' > in the first place. > > Same goes for the implied `--cover-letter`. Instead of rephrasing I > added a note for the user to clear up any ambiguity.
I dunno.
Being verbose is usually a good way to discourage readers from reading.
Let's see if we can shorten them without losing information.
Show 5 quoted lines
> --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`.