git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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
Previous: Junio C HamanoNext: Junio C Hamano
Message 5 of 12 in “docs: fix --commit-list-format related entries”
  1. docs: fix --commit-list-format related entriesMirko Faina, Mar 26, 2026
  2. Junio C HamanoMar 26, 2026
  3. docs: fix --commit-list-format related entriesMirko Faina, Mar 26, 2026
  4. Junio C HamanoMar 26, 2026
  5. Mirko FainaMar 26, 2026
  6. Junio C HamanoMar 26, 2026
  7. Mirko FainaMar 27, 2026
  8. Mirko FainaMar 27, 2026
  9. 0/2 format-patch: remove wrapping and update docsMirko Faina, Mar 27, 2026
  10. 1/2 docs: fix --commit-list-format related entriesMirko Faina, Mar 27, 2026
  11. 2/2 format-patch: removing unconditional wrappingMirko Faina, Mar 27, 2026
  12. Junio C HamanoMar 27, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.