doc: show usage of branch description

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 311b33674eb2bda2c8e0bd5d2de4499a156b1719..e496141bc5ec9e85c02474412309e420837fb56a 100644 (file)
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -193,7 +193,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
 
 --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
 
 --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 c0fd470da42991404c722f45ee7ac48cd774287b..037ceb21b13d03c4cbcddf9ca36e7970745bd4b3 100644 (file)
--- 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
 
 --[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>]::
        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 cf2c374b710673e891f8337cb9bcc90d72be460a..7366c3a0b6cf907c5cae9da518ac40f0cac875af 100644 (file)
--- 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'
 +
 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
 
 --[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 283577b0b6ca1ef7a35758686edf548025e6db76..c32cb0bea1d6c057dabdd3065417744f5209ba46 100644 (file)
--- 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
 -----------
 
 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
 the changes and indicates from where they can be pulled.
 
 The upstream project is expected to have the commit named by