[PATCH v2] Documentation: summarize how format-patch output is consumed

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Apr 14, 2011, 21:11 UTC
Message-ID: <20110414211125.GA15277@elie>
In-Reply-To: <7vzkntkc9d.fsf@alter.siamese.dyndns.org>

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@meyering.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
---
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@intel.com>
+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