Documentation: decribe format-patch --notes

Even though I coded this, I am not sure what use scenarios would benefit
from this option, so the description is unnecessarily negative at this
moment. People who do want to use this feature need to come up with a
more plausible use case and replace it.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 6d43f56279fe7a0d42510035e33424df0bc584f1..066dc8be4540c1a676e0a59f583bb843d59e0da4 100644 (file)
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -20,7 +20,7 @@ SYNOPSIS
                   [--ignore-if-in-upstream]
                   [--subject-prefix=Subject-Prefix]
                   [--to=<email>] [--cc=<email>]
                   [--ignore-if-in-upstream]
                   [--subject-prefix=Subject-Prefix]
                   [--to=<email>] [--cc=<email>]

-                  [--cover-letter] [--quiet]
+                  [--cover-letter] [--quiet] [--notes[=<ref>]]

                   [<common diff options>]
                   [ <since> | <revision range> ]
 
                   [<common diff options>]
                   [ <since> | <revision range> ]
 


@@ -191,6 +191,19 @@ will want to ensure that threading is disabled for `git send-email`.
        containing the shortlog and the overall diffstat.  You can
        fill in a description in the file before sending it out.
 
        containing the shortlog and the overall diffstat.  You can
        fill in a description in the file before sending it out.
 

+--notes[=<ref>]::
+       Append the notes (see linkgit:git-notes[1]) for the commit
+       after the three-dash line.
++
+The expected use case of this is to write supporting explanation for
+the commit that does not belong to the commit log message proper
+when (or after) you create the commit, and include it in your patch
+submission.  But if you can plan ahead and write it down, there may
+not be a good reason not to write it in your commit message, and if
+you can't, you can always edit the output of format-patch before
+sending it out, so the practical value of this option is somewhat
+dubious, unless your workflow is broken.
+

 --[no]-signature=<signature>::
        Add a signature to each message produced. Per RFC 3676 the signature
        is separated from the body by a line with '-- ' on it. If the
 --[no]-signature=<signature>::
        Add a signature to each message produced. Per RFC 3676 the signature
        is separated from the body by a line with '-- ' on it. If the