docs: add usage for the cover-letter fmt feature

Document the new "--cover-letter-format" option in format-patch and its
related configuration variable "format.commitListFormat".

Signed-off-by: Mirko Faina <mroik@delayed.space>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc
index ab0710e86a3e2ca7d0724e174213cada4a611cb4..ea5ec5df7a2aee013e9ad9a9509aba5ef43af68d 100644 (file)
--- a/Documentation/config/format.adoc
+++ b/Documentation/config/format.adoc
@@ -101,6 +101,11 @@ format.coverLetter::
        generate a cover-letter only when there's more than one patch.
        Default is false.
 
+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
+       each commit. Default to `shortlog`.
+
 format.outputDirectory::
        Set a custom directory to store the resulting files instead of the
        current working directory. All directory components will be created.

diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
index 9a7807ca71a52866ed8587483475ba92f88854a3..668330a0152eb0846ca9fd2cc8f9a702a59184d4 100644 (file)
--- a/Documentation/git-format-patch.adoc
+++ b/Documentation/git-format-patch.adoc
@@ -24,6 +24,7 @@ SYNOPSIS
                   [(--reroll-count|-v) <n>]
                   [--to=<email>] [--cc=<email>]
                   [--[no-]cover-letter] [--quiet]
+                  [--cover-letter-format=<format-spec>]
                   [--[no-]encode-email-headers]
                   [--no-notes | --notes[=<ref>]]
                   [--interdiff=<previous>]
@@ -321,6 +322,17 @@ feeding the result to `git send-email`.
        containing the branch description, shortlog and the overall diffstat.  You can
        fill in a description in the file before sending it out.
 
+--cover-letter-format=<format-spec>::
+       Specify the format in which to generate the commit list of the
+       patch series. This option is available if the user wants to use
+       an alternative to the default `shortlog` format. The accepted
+       values for format-spec are "shortlog" or a format string
+       prefixed with `log:`.
+       e.g. `log: %s (%an)`
+       If defined, defaults to the `format.commitListFormat` configuration
+       variable.
+       This option is relevant only if a cover letter is generated.
+
 --encode-email-headers::
 --no-encode-email-headers::
        Encode email headers that have non-ASCII characters with
@@ -452,6 +464,7 @@ with configuration variables.
        signOff = true
        outputDirectory = <directory>
        coverLetter = auto
+       commitListFormat = shortlog
        coverFromDescription = auto
 ------------