git format-patch documentation: clarify what --cover-letter does

[thirdparty/git.git] / Documentation / git-format-patch.txt

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index fefcd269c6658903f892a3356431599790a0f844..adb4ea7b1b6c70fb6fc2486487ef34ed280ec015 100644 (file)
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -9,7 +9,7 @@ git-format-patch - Prepare patches for e-mail submission
 SYNOPSIS
 --------
 [verse]
-'git-format-patch' [-k] [-o <dir> | --stdout] [--thread]
+'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
                   [--attach[=<boundary>] | --inline[=<boundary>]]
                   [-s | --signoff] [<common diff options>]
                   [-n | --numbered | -N | --no-numbered]
@@ -27,7 +27,7 @@ DESCRIPTION
 Prepare each commit with its patch in
 one file per commit, formatted to resemble UNIX mailbox format.
 The output of this command is convenient for e-mail submission or
-for use with linkgit:git-am[1].
+for use with 'git-am'.
 
 There are two ways to specify which commits to operate on.
 
@@ -61,7 +61,7 @@ they are created in the current working directory.
 If -n is specified, instead of "[PATCH] Subject", the first line
 is formatted as "[PATCH n/m] Subject".
 
-If given --thread, git-format-patch will generate In-Reply-To and
+If given --thread, 'git-format-patch' will generate In-Reply-To and
 References headers to make the second and subsequent patch mails appear
 as replies to the first mail; this also generates a Message-Id header to
 reference.
@@ -74,14 +74,17 @@ include::diff-options.txt[]
 -<n>::
        Limits the number of patches to prepare.
 
--o|--output-directory <dir>::
+-o <dir>::
+--output-directory <dir>::
        Use <dir> to store the resulting files, instead of the
        current working directory.
 
--n|--numbered::
+-n::
+--numbered::
        Name output in '[PATCH n/m]' format.
 
--N|--no-numbered::
+-N::
+--no-numbered::
        Name output in '[PATCH]' format.
 
 --start-number <n>::
@@ -92,11 +95,13 @@ include::diff-options.txt[]
        without the default first line of the commit appended.
        Mutually exclusive with the --stdout option.
 
--k|--keep-subject::
+-k::
+--keep-subject::
        Do not strip/add '[PATCH]' from the first line of the
        commit log message.
 
--s|--signoff::
+-s::
+--signoff::
        Add `Signed-off-by:` line to the commit message, using
        the committer identity of yourself.
 
@@ -142,9 +147,9 @@ include::diff-options.txt[]
        to any configured headers, and may be used multiple times.
 
 --cover-letter::
-       Generate a cover letter template.  You still have to fill in
-       a description, but the shortlog and the diffstat will be
-       generated for you.
+       In addition to the patches, generate a cover letter file
+       containing the shortlog and the overall diffstat.  You can
+       fill in a description in the file before sending it out.
 
 --suffix=.<sfx>::
        Instead of using `.patch` as the suffix for generated
@@ -170,10 +175,10 @@ and file suffix, and number patches when outputting more than one.
 
 ------------
 [format]
-        headers = "Organization: git-foo\n"
-        subjectprefix = CHANGE
-        suffix = .txt
-        numbered = auto
+       headers = "Organization: git-foo\n"
+       subjectprefix = CHANGE
+       suffix = .txt
+       numbered = auto
        cc = <email>
 ------------
 
@@ -182,10 +187,10 @@ EXAMPLES
 --------
 
 * Extract commits between revisions R1 and R2, and apply them on top of
-the current branch using `git-am` to cherry-pick them:
+the current branch using 'git-am' to cherry-pick them:
 +
 ------------
-$ git format-patch -k --stdout R1..R2 | git-am -3 -k
+$ git format-patch -k --stdout R1..R2 | git am -3 -k
 ------------
 
 * Extract all commits which are in the current branch but not in the
@@ -201,7 +206,7 @@ For each commit a separate file is created in the current directory.
 project:
 +
 ------------
-$ git format-patch \--root origin
+$ git format-patch --root origin
 ------------
 
 * The same as the previous one:
@@ -230,7 +235,7 @@ linkgit:git-am[1], linkgit:git-send-email[1]
 
 Author
 ------
-Written by Junio C Hamano <junkio@cox.net>
+Written by Junio C Hamano <gitster@pobox.com>
 
 Documentation
 --------------
@@ -238,4 +243,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT
 ---
-Part of the linkgit:git[7] suite
+Part of the linkgit:git[1] suite