Hi Jim,
Jim Meyering wrote:
> I hope I haven't caused Junio or anyone else undue trouble.
> I know well how format-patch output can be used, but in the vast
> majority of patch-including messages I send, I include format-patch
> output mainly as an FYI, *following* commentary that does not
> belong in the log, so it's ok there -- desirable, even.
Sure, that's true. The main problem with including a patch in mbox
format inline is that the "From " line tends to get corrupted. How
about something like patch?
-- 8< --
Subject: Documentation/format-patch: summarize patch-sending workflow
Add a DISCUSSION section to encourage people to send patches in a
form that can be applied by "git am" automatically. There are two
such forms:
1. The default form in which most metadata goes in the mail header
and the message body starts with the patch description;
2. The snipsnip form in which a message starts with pertinent
discussion and ends with a patch after a "scissors" mark.
While at it, include a pointer to Documentation/SubmittingPatches
for MUA-specific hints.
Inspired-by: Jim Meyering <jim@xxxxxxxxxxxx>
Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx>
---
Documentation/git-format-patch.txt | 48 +++++++++++++++++++++++++++++++++++-
1 files changed, 47 insertions(+), 1 deletions(-)
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index a5525e9..5118fdb 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -274,9 +274,55 @@ as e-mailable patches:
$ git format-patch -3
------------
+DISCUSSION
+----------
+The patch produced by 'git format-patch' is in UNIX mailbox format,
+like so:
+
+------------
+From f97e66080296c741200eacf1eaeb73f05b19e140 Mon Sep 17 00:00:00 2001
+From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= <avarab@xxxxxxxxx>
+Date: Sun, 10 Apr 2011 19:37:01 +0000
+Subject: [PATCH] Makefile: extract Q_() source strings as ngettext()
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+The patch adding the Q_() wrapper function around ngettext[1] didn't
+contain a corresponding update to the "pot" target in the Makefile. As
+...
+------------
+
+Typically it will be placed in a MUA's drafts folder, edited to add
+timely commentary that should not go in the changelog after the three
+dashes, and then sent as a message whose body starts with "The patch
+adding the Q_() wrapper function ...". On the receiving end, readers
+can save interesting patches in a UNIX mailbox and apply them with
+linkgit:git-am[1].
+
+'git am --scissors' accepts an alternative format with the patch
+inline in the message:
+
+------------
+...
+> So we should do such-and-such.
+
+Makes sense to me. How about this patch?
+
+-- 8< --
+From: Ãvar ArnfjÃrà Bjarmason <avarab@xxxxxxxxx>
+Subject: Makefile: extract Q_() source strings as ngettext()
+
+The patch adding the Q_() wrapper function around ngettext[1] didn't
+....
+------------
+
+See linkgit:git-am[1] for details.
+
SEE ALSO
--------
-linkgit:git-am[1], linkgit:git-send-email[1]
+linkgit:git-am[1], linkgit:git-send-email[1], linkgit:git-imap-send[1],
+Documentation/SubmittingPatches
GIT
---
--
1.7.5.rc0
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html