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

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

[Mirko Faina]

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(-)

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

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

[Junio C Hamano]

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:`".

> -	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.

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

[Mirko Faina]

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(-)

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

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

[Junio C Hamano]

Mirko Faina <mroik@delayed.space> writes:

> 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.

>  --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`.

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

[Mirko Faina]

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...

> 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

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

[Junio C Hamano]

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.

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

[Mirko Faina]

On Thu, Mar 26, 2026 at 02:10:12PM -0700, Junio C Hamano wrote:
> 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

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

[Mirko Faina]

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

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

[Mirko Faina]

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

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

[Mirko Faina]

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(-)

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

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

[Mirko Faina]

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(-)

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

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

[Junio C Hamano]

Mirko Faina <mroik@delayed.space> writes:

> 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.