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') 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.3-5-g9baa From 76323c67b7729076e4f905f6d227329a47e6443f Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sun, 21 Oct 2012 22:34:07 +0100 Subject: Doc SubmittingPatches: Mention --notes option after "cover letter" The git format-patch --notes option can now insert the commit notes after the three dashes. Mention this after the regular cover letter guidance for submitting patches. Signed-off-by: Philip Oakley Signed-off-by: Jeff King --- Documentation/SubmittingPatches | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0dbf2c9843..3d8b2fe4d1 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -179,7 +179,8 @@ message starts, you can put a "From: " line to name that person. You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" -material between the three dash lines and the diffstat. +material between the three dash lines and the diffstat. Git-notes +can also be inserted using the `--notes` option. Do not attach the patch as a MIME attachment, compressed or not. Do not let your e-mail client send quoted-printable. Do not let -- cgit v1.3-5-g9baa From e39b307d09c41ff660f4ddfcecbcb08177fcd4f3 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sun, 21 Oct 2012 22:34:09 +0100 Subject: Doc notes: Include the format-patch --notes option git format-patch gained a --notes option. Tell the notes user. Signed-off-by: Philip Oakley Signed-off-by: Jeff King --- Documentation/git-notes.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index b95aafae2d..46ef0466be 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -39,6 +39,10 @@ message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes ():" (or "Notes:" for `refs/notes/commits`). +Notes can also be added to patches prepared with `git format-patch` by +using the `--notes` option. Such notes are added as a patch commentary +after a three dash separator line. + To change which notes are shown by 'git log', see the "notes.displayRef" configuration in linkgit:git-log[1]. -- cgit v1.3-5-g9baa 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') 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.3-5-g9baa From d84cef1817be9615729b26e3965e8cb8da926dc5 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sun, 21 Oct 2012 22:34:08 +0100 Subject: Doc User-Manual: Patch cover letter, three dashes, and --notes Show that git format-patch can have a cover letter, include patch commentary below the three dashes, and notes can also be included. Signed-off-by: Philip Oakley Signed-off-by: Jeff King --- Documentation/user-manual.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 85651b57ae..1b377dc207 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1787,6 +1787,13 @@ $ git format-patch origin will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD. +`git format-patch` can include an initial "cover letter". You can insert +commentary on individual patches after the three dash line which +`format-patch` places after the commit message but before the patch +itself. If you use `git notes` to track your cover letter material, +`git format-patch --notes` will include the commit's notes in a similar +manner. + You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the linkgit:git-send-email[1] script to automate the process. -- cgit v1.3-5-g9baa