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.
Use an example requiring QP encoding in the "Subject:" field intended
for the mailer, to give the reader a chance to reflect on that (rather
than being startled later). By contrast, in-body "From:" and
"Subject:" lines should be human-readable and not QP encoded.
A patch following "How about this patch?" is most likely to be written
by the same person as the message is coming from, so you would rarely
need a "From:" after the scissors. On the other hand, such a message
typically presents a potential solution to a problem raised in
discussion and the original subject is likely to be a description of
the problem or a request for help while the patch title is about the
solution, so it is very likely that you would want a "Subject:" line
after the scissors. It would be nice to clarify use of the "From:",
"Date:", and "Subject:" fields after the scissors in general, but this
patch avoids the topic in hope of leading the reader to look to
git-am(1) for a detailed discussion.
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>
Improved-by: Junio C Hamano <gitster@xxxxxxxxx>
---
Junio C Hamano wrote:
> It still is preferred to remove the magic "From xxxx Mon Sep 17 00:00:00
> 2001" we placed to help somebody who is inclined to write an /etc/magic
> entry to detect files of format-patch output type if you use the scissors
> format.
[and many useful suggestions]
Thanks. Changes since v1:
- no more inline "From:" field
- different patch to demonstrate qp-encoding in "Subject:" instead
- use right-handed scissors
I didn't find a way to sneak in a comment about "file" magic; that can
come another day.
Documentation/git-format-patch.txt | 50 +++++++++++++++++++++++++++++++++++-
1 files changed, 49 insertions(+), 1 deletions(-)
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index a5525e9..875ea9b 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -274,9 +274,57 @@ as e-mailable patches:
$ git format-patch -3
------------
+DISCUSSION
+----------
+The patch produced by 'git format-patch' is in UNIX mailbox format,
+like so:
+
+------------
+From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
+From: Tony Luck <tony.luck@xxxxxxxxx>
+Date: Tue, 13 Jul 2010 11:42:54 -0700
+Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
+ =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+arch/arm config files were slimmed down using a python script
+(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
+
+Do the same for ia64 so we can have sleek & trim looking
+...
+------------
+
+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 "arch/arm
+config files were". 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 --
+Subject: [IA64] Put ia64 config files on the Uwe Kleine-KÃnig diet
+
+arch/arm config files were slimmed down using a python script
+...
+------------
+
+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