From e422c0cf1cd76e9c7957b46b317d1d8fabcdd8ee Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 19 Oct 2012 13:01:05 -0700 Subject: 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 --- Documentation/git-format-patch.txt | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'Documentation/git-format-patch.txt') diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 6d43f56279..066dc8be45 100644 --- 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=] [--cc=] - [--cover-letter] [--quiet] + [--cover-letter] [--quiet] [--notes[=]] [] [ | ] @@ -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. +--notes[=]:: + 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=:: 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 -- cgit v1.2.3 From 6454d9f166236965c84650f72ecdd17e309394d6 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sun, 21 Oct 2012 22:34:10 +0100 Subject: Doc format-patch: clarify --notes use case Remove double negative, and include the repeat usage across versions of a patch series. Signed-off-by: Philip Oakley Signed-off-by: Jeff King --- Documentation/git-format-patch.txt | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) (limited to 'Documentation/git-format-patch.txt') diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 066dc8be45..259dce4994 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -196,13 +196,12 @@ will want to ensure that threading is disabled for `git send-email`. 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. +the commit that does not belong to the commit log message proper, +and include it with the patch submission. While one can simply write +these explanations after `format-patch` has run but before sending, +keeping them as git notes allows them to be maintained between versions +of the patch series (but see the discussion of the `notes.rewrite` +configuration options in linkgit:git-notes[1] to use this workflow). --[no]-signature=:: Add a signature to each message produced. Per RFC 3676 the signature -- cgit v1.2.3