[PATCH v2] doc: show usage of branch description

[Philip Oakley <philipoakley@iee.org>]

The branch description will be included in 'git format-patch
--cover-letter' and in 'git pull-request' emails. It can also
be used in the automatic merge message. Tell the reader.

While here, clarify that the description may be a multi-line
explanation of the purpose of the branch's patch series.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
fc0aa39 (Documentation: include 'merge.branchdesc' for merge
and config as well, 2015-05-27) recently added details of the
low level config flag.

Changes since V1: discovered that git merge can also include
the branch description if enabled, so added a minimal mention to
flag it to the reader. 
---
 Documentation/git-branch.txt       | 4 +++-
 Documentation/git-format-patch.txt | 2 +-
 Documentation/git-merge.txt        | 2 +-
 Documentation/git-request-pull.txt | 3 ++-
 4 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index a67138a..bbbade4 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -197,7 +197,9 @@ start-point is either a local or remote-tracking branch.
 
 --edit-description::
 	Open an editor and edit the text to explain what the branch is
-	for, to be used by various other commands (e.g. `request-pull`).
+	for, to be used by various other commands (e.g. `format-patch`,
+	`request-pull`, and `merge` (if enabled)). Multi-line explanations
+	may be used.
 
 --contains [<commit>]::
 	Only list branches which contain the specified commit (HEAD
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 0dac4e9..4035649 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -213,7 +213,7 @@ feeding the result to `git send-email`.
 
 --[no-]cover-letter::
 	In addition to the patches, generate a cover letter file
-	containing the shortlog and the overall diffstat.  You can
+	containing the branch description, shortlog and the overall diffstat.  You can
 	fill in a description in the file before sending it out.
 
 --notes[=<ref>]::
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 273a100..a62d672 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -78,7 +78,7 @@ will be appended to the specified message.
 +
 The 'git fmt-merge-msg' command can be
 used to give a good default for automated 'git merge'
-invocations.
+invocations. The automated message can include the branch description.
 
 --[no-]rerere-autoupdate::
 	Allow the rerere mechanism to update the index with the
diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt
index 283577b..c32cb0b 100644
--- a/Documentation/git-request-pull.txt
+++ b/Documentation/git-request-pull.txt
@@ -14,7 +14,8 @@ DESCRIPTION
 -----------
 
 Generate a request asking your upstream project to pull changes into
-their tree.  The request, printed to the standard output, summarizes
+their tree.  The request, printed to the standard output,
+begins with the branch description, summarizes
 the changes and indicates from where they can be pulled.
 
 The upstream project is expected to have the commit named by
-- 
2.4.2.windows.1.5.gd32afb6