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

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`.
Previous: Mirko FainaNext: Mirko Faina
Message 4 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.