Volume XXII, number 280Wednesday, October 7, 2026Latest message 56 minutes ago

The Git List

News and archive of git@vger.kernel.org, since April 2005

patchdocs: fix --commit-list-format related entries

12 messages between Mar 26, 2026 and Mar 27, 2026, from Mirko Faina, Junio C Hamano.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Mirko FainaMar 26, 2026, 18:55 UTC on lore

Documentation specifies that "git format-patch" would default to format.commitListFormat if --commit-list-format is not given, but doesn't specify the default if the format.commitListFormat is not set. The text for --cover-letter is also obsolete as the commit list can now be something other than a shortlog.

Document to reflect changes.
Signed-off-by: Mirko Faina <mroik@delayed.space>
---
This series is based on top of 41688c1a23 (The 21st batch, 2026-03-25)
with the following series merged into it:
  - mf/format-patch-commit-list-format at 36c16a5b7f (format-patch:
    --commit-list-format without prefix, 2026-03-23)
 Documentation/config/format.adoc    |  2 +-
 Documentation/git-format-patch.adoc | 20 ++++++++++----------
 2 files changed, 11 insertions(+), 11 deletions(-)
Show changes to 2 files +11 −11

Documentation/config/format.adoc, Documentation/git-format-patch.adoc

diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc
index ef1ed1d250..dbd186290b 100644
--- a/Documentation/config/format.adoc
+++ b/Documentation/config/format.adoc
@@ -103,7 +103,7 @@ format.coverLetter::
 
 format.commitListFormat::
 	When the `--cover-letter-format` option is not given, `format-patch`
-	uses the value of this variable to decide how to format the title of
+	uses the value of this variable to decide how to format the entry of
 	each commit. Defaults to `shortlog`.
 
 format.outputDirectory::
diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
index c52dbcc170..e74b085c77 100644
--- a/Documentation/git-format-patch.adoc
+++ b/Documentation/git-format-patch.adoc
@@ -319,21 +319,21 @@ feeding the result to `git send-email`.
 
 --cover-letter::
 --no-cover-letter::
-	In addition to the patches, generate a cover letter file
-	containing the branch description, shortlog and the overall diffstat.  You can
-	fill in a description in the file before sending it out.
+	In addition to the patches, generate a cover letter file containing the
+	branch description, commit list and the overall diffstat.  You can fill
+	in a description in the file before sending it out.
 
 --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)`
+	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`.
 	The user is allowed to drop the prefix if the format-string contains a
 	`%<placeholder>`.
-	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.
 
 --encode-email-headers::
 --no-encode-email-headers::

-- 
2.53.0.1181.g1066ffbbbe
Junio C HamanoMar 26, 2026, 19:10 UTC in reply to Mirko Faina on lore

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

Mirko Faina <mroik@delayed.space> 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:`".

Show 8 quoted lines
> -	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.
Mirko FainaMar 26, 2026, 20:06 UTC in reply to Mirko Faina on lore

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

Documentation specifies that "git format-patch" would default to format.commitListFormat if --commit-list-format is not given, but doesn't specify the default if the format.commitListFormat is not set. The text for --cover-letter is also obsolete as the commit list can now be something other than a shortlog.

Document to reflect changes.
Signed-off-by: Mirko Faina <mroik@delayed.space>
---
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.

 Documentation/config/format.adoc    |  2 +-
 Documentation/git-format-patch.adoc | 27 +++++++++++++++------------
 2 files changed, 16 insertions(+), 13 deletions(-)
Show changes to 2 files +16 −13

Documentation/config/format.adoc, Documentation/git-format-patch.adoc

diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc
index ef1ed1d250..dbd186290b 100644
--- a/Documentation/config/format.adoc
+++ b/Documentation/config/format.adoc
@@ -103,7 +103,7 @@ format.coverLetter::
 
 format.commitListFormat::
 	When the `--cover-letter-format` option is not given, `format-patch`
-	uses the value of this variable to decide how to format the title of
+	uses the value of this variable to decide how to format the entry of
 	each commit. Defaults to `shortlog`.
 
 format.outputDirectory::
diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
index c52dbcc170..fc0023b9b7 100644
--- a/Documentation/git-format-patch.adoc
+++ b/Documentation/git-format-patch.adoc
@@ -319,21 +319,24 @@ feeding the result to `git send-email`.
 
 --cover-letter::
 --no-cover-letter::
-	In addition to the patches, generate a cover letter file
-	containing the branch description, shortlog and the overall diffstat.  You can
-	fill in a description in the file before sending it out.
+	In addition to the patches, generate a cover letter file containing the
+	branch description, commit list and the overall diffstat.  You can fill
+	in a description in the file before sending it out.
 
 --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)`
-	The user is allowed to drop the prefix if the format-string contains a
-	`%<placeholder>`.
-	If not given, defaults to the `format.commitListFormat` configuration
-	variable.
-	This option implies the use of `--cover-letter` unless
-	`--no-cover-letter` is given.
+	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`.
+	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.
+	If not given, defaults to `shortlog` unless the
+	`format.commitListFormat` configuration variable is set.
+	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`.
 
 --encode-email-headers::
 --no-encode-email-headers::

-- 
2.53.0.1181.g1066ffbbbe
Junio C HamanoMar 26, 2026, 20:45 UTC in reply to Mirko Faina on lore

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

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`.
Mirko FainaMar 26, 2026, 20:53 UTC in reply to Junio C Hamano on lore

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

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
Junio C HamanoMar 26, 2026, 21:10 UTC in reply to Mirko Faina on lore

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

Mirko Faina <mroik@delayed.space> writes:
Show 14 quoted lines
> 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.
> ...
>>     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`.
I do not think so.

If we mention a variable, the readers would wonder if the variable has effects. You can explicitly say that that it does *not* have effect, but we are often better of not mentioning what is not relevant.

Mirko FainaMar 27, 2026, 00:20 UTC in reply to Junio C Hamano on lore

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

On Thu, Mar 26, 2026 at 02:10:12PM -0700, Junio C Hamano wrote:
Show 23 quoted lines
> Mirko Faina <mroik@delayed.space> writes:
> 
> > 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.
> > ...
> >>     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`.
> 
> I do not think so.  
> 
> If we mention a variable, the readers would wonder if the variable
> has effects.  You can explicitly say that that it does *not* have
> effect, but we are often better of not mentioning what is not
> relevant.

So the issue with the original is simply the fact that it wasn't explicitly said from the command line? If that's the case then the v2 should be fine but without the note about the configuration variable, i.e. "This option given from the command-line implies the use of `--cover-letter` unless `--no-cover-letter` is given."

Thank you
Mirko FainaMar 27, 2026, 00:25 UTC in reply to Mirko Faina on lore

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

I will wait for tomorrow to send a reroll just in case someone wants to comment on v2.

Mirko FainaMar 27, 2026, 19:48 UTC in reply to Mirko Faina on lore

[PATCH 0/2] format-patch: remove wrapping and update docs

This series adds the missing default value for --commit-list-format in the documentation and removes unconditional wrapping from the commit list entries.

This series is based on top of 41688c1a23 (The 21st batch, 2026-03-25)
with the following series merged into it:
  - mf/format-patch-commit-list-format at 36c16a5b7f (format-patch:
    --commit-list-format without prefix, 2026-03-23)

[1/2] docs: fix --commit-list-format related entries (Mirko Faina) [2/2] format-patch: removing unconditional wrapping (Mirko Faina)

 Documentation/config/format.adoc    |  2 +-
 Documentation/git-format-patch.adoc | 24 ++++++++++++------------
 builtin/log.c                       |  9 ++-------
 3 files changed, 15 insertions(+), 20 deletions(-)
-- 
2.53.0.1181.g1066ffbbbe
Mirko FainaMar 27, 2026, 19:48 UTC in reply to Mirko Faina on lore

[PATCH 1/2] docs: fix --commit-list-format related entries

Documentation specifies that "git format-patch" would default to format.commitListFormat if --commit-list-format is not given, but doesn't specify the default if the format.commitListFormat is not set. The text for --cover-letter is also obsolete as the commit list can now be something other than a shortlog.

Document to reflect changes.
Signed-off-by: Mirko Faina <mroik@delayed.space>
---
 Documentation/config/format.adoc    |  2 +-
 Documentation/git-format-patch.adoc | 24 ++++++++++++------------
 2 files changed, 13 insertions(+), 13 deletions(-)
Show changes to 2 files +13 −13

Documentation/config/format.adoc, Documentation/git-format-patch.adoc

diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc
index ef1ed1d250..dbd186290b 100644
--- a/Documentation/config/format.adoc
+++ b/Documentation/config/format.adoc
@@ -103,7 +103,7 @@ format.coverLetter::
 
 format.commitListFormat::
 	When the `--cover-letter-format` option is not given, `format-patch`
-	uses the value of this variable to decide how to format the title of
+	uses the value of this variable to decide how to format the entry of
 	each commit. Defaults to `shortlog`.
 
 format.outputDirectory::
diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
index c52dbcc170..cbbb292cb5 100644
--- a/Documentation/git-format-patch.adoc
+++ b/Documentation/git-format-patch.adoc
@@ -319,21 +319,21 @@ feeding the result to `git send-email`.
 
 --cover-letter::
 --no-cover-letter::
-	In addition to the patches, generate a cover letter file
-	containing the branch description, shortlog and the overall diffstat.  You can
-	fill in a description in the file before sending it out.
+	In addition to the patches, generate a cover letter file containing the
+	branch description, commit list and the overall diffstat.  You can fill
+	in a description in the file before sending it out.
 
 --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)`
-	The user is allowed to drop the prefix if the format-string contains a
-	`%<placeholder>`.
-	If not given, defaults to the `format.commitListFormat` configuration
-	variable.
-	This option implies the use of `--cover-letter` unless
-	`--no-cover-letter` is given.
+	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`.
+	The `log:` prefix can be omitted if the format-string has a `%` in it
+	(expecting that it is part of `%<placeholder>`).
+	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.
 
 --encode-email-headers::
 --no-encode-email-headers::

-- 
2.53.0.1181.g1066ffbbbe
Mirko FainaMar 27, 2026, 19:48 UTC in reply to Mirko Faina on lore

[PATCH 2/2] format-patch: removing unconditional wrapping

Using format-patch with --commit-list-format different than shortlog, causes the commit entry lines to wrap if they get longer than MAIL_DEFAULT_WRAP (72 characters).

While this might be sensible for many when sending changes through email, it forces this decision of wrapping on the user, reducing the control granularity of --commit-list-format.

Teach generate_commit_list_cover() to respect commit entry line lengths and place this wrapping rule on the "modern" preset format instead.

Signed-off-by: Mirko Faina <mroik@delayed.space>
---
 Documentation/git-format-patch.adoc | 2 +-
 builtin/log.c                       | 9 ++-------
 2 files changed, 3 insertions(+), 8 deletions(-)
Show changes to 2 files +3 −8

Documentation/git-format-patch.adoc, builtin/log.c

diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
index cbbb292cb5..5662382450 100644
--- a/Documentation/git-format-patch.adoc
+++ b/Documentation/git-format-patch.adoc
@@ -327,7 +327,7 @@ feeding the result to `git send-email`.
 	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` is the same as `log:%w(72)[%(count)/%(total)] %s`.
 	The `log:` prefix can be omitted if the format-string has a `%` in it
 	(expecting that it is part of `%<placeholder>`).
 	Defaults to the `format.commitListFormat` configuration variable, if
diff --git a/builtin/log.c b/builtin/log.c
index ad7b7215fe..8c0939dd42 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -1365,7 +1365,6 @@ static void generate_commit_list_cover(FILE *cover_file, const char *format,
 				       struct commit **list, int n)
 {
 	struct strbuf commit_line = STRBUF_INIT;
-	struct strbuf wrapped_line = STRBUF_INIT;
 	struct pretty_print_context ctx = {0};
 	struct rev_info rev = REV_INFO_INIT;
 
@@ -1375,16 +1374,12 @@ static void generate_commit_list_cover(FILE *cover_file, const char *format,
 		rev.nr = i;
 		repo_format_commit_message(the_repository, list[n - i], format,
 				&commit_line, &ctx);
-		strbuf_add_wrapped_text(&wrapped_line, commit_line.buf, 0, 0,
-					MAIL_DEFAULT_WRAP);
-		fprintf(cover_file, "%s\n", wrapped_line.buf);
+		fprintf(cover_file, "%s\n", commit_line.buf);
 		strbuf_reset(&commit_line);
-		strbuf_reset(&wrapped_line);
 	}
 	fprintf(cover_file, "\n");
 
 	strbuf_release(&commit_line);
-	strbuf_release(&wrapped_line);
 }
 
 static void make_cover_letter(struct rev_info *rev, int use_separate_file,
@@ -1446,7 +1441,7 @@ static void make_cover_letter(struct rev_info *rev, int use_separate_file,
 	else if (!strcmp(format, "shortlog"))
 		generate_shortlog_cover_letter(&log, rev, list, nr);
 	else if (!strcmp(format, "modern"))
-		generate_commit_list_cover(rev->diffopt.file, "[%(count)/%(total)] %s",
+		generate_commit_list_cover(rev->diffopt.file, "%w(72)[%(count)/%(total)] %s",
 					   list, nr);
 	else if (strchr(format, '%'))
 		generate_commit_list_cover(rev->diffopt.file, format, list, nr);

-- 
2.53.0.1181.g1066ffbbbe
Junio C HamanoMar 27, 2026, 20:27 UTC in reply to Mirko Faina on lore

Re: [PATCH 2/2] format-patch: removing unconditional wrapping

Mirko Faina <mroik@delayed.space> writes:
Show 10 quoted lines
> Using format-patch with --commit-list-format different than shortlog,
> causes the commit entry lines to wrap if they get longer than
> MAIL_DEFAULT_WRAP (72 characters).
>
> While this might be sensible for many when sending changes through
> email, it forces this decision of wrapping on the user, reducing the
> control granularity of --commit-list-format.
>
> Teach generate_commit_list_cover() to respect commit entry line lengths
> and place this wrapping rule on the "modern" preset format instead.

Well explained. I would have personally picked a sligntly different default format, but this topic is your itch, so it's OK.

Will queue.  Looks very good.  Thanks.

Back to recent threads