[PATCH v2] docs: fix --commit-list-format related entries
- From
Mirko Faina <mroik@delayed.space>
- Date
- Mar 26, 2026, 20:06 UTC
- Message-ID
- <20260326200643.20251-1-mroik@delayed.space>
- In-Reply-To
- <20260326185541.17523-1-mroik@delayed.space>
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