summaryrefslogtreecommitdiff
path: root/Documentation/git-format-patch.txt
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2011-05-04 22:51:31 (GMT)
committerJunio C Hamano <gitster@pobox.com>2011-05-04 22:51:31 (GMT)
commit0cb09a7e0c91725c9ac926f1b6767dce597d19dd (patch)
tree52e108f4eaa89343df60ccde8bc4d4fcbe9aad5a /Documentation/git-format-patch.txt
parent5ead6a6fdb5f613cbe252e264e18db709994cfe4 (diff)
parente0d48279d5a96bc02edac72c1d28fc38aed37c15 (diff)
downloadgit-0cb09a7e0c91725c9ac926f1b6767dce597d19dd.zip
git-0cb09a7e0c91725c9ac926f1b6767dce597d19dd.tar.gz
git-0cb09a7e0c91725c9ac926f1b6767dce597d19dd.tar.bz2
Merge branch 'jn/maint-format-patch-doc'
* jn/maint-format-patch-doc: Documentation: describe the format of messages with inline patches
Diffstat (limited to 'Documentation/git-format-patch.txt')
-rw-r--r--Documentation/git-format-patch.txt58
1 files changed, 58 insertions, 0 deletions
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index f4e959d..66aba8a 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -232,6 +232,64 @@ attachments, and sign off patches with configuration variables.
------------
+DISCUSSION
+----------
+
+The patch produced by 'git format-patch' is in UNIX mailbox format,
+with a fixed "magic" time stamp to indicate that the file is output
+from format-patch rather than a real mailbox, 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, in our example, 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].
+
+When a patch is part of an ongoing discussion, the patch generated by
+'git format-patch' can be tweaked to take advantage of the 'git am
+--scissors' feature. After your response to the discussion comes a
+line that consists solely of "`-- >8 --`" (scissors and perforation),
+followed by the patch with unnecessary header fields removed:
+
+------------
+...
+> 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
+...
+------------
+
+When sending a patch this way, most often you are sending your own
+patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you
+should omit `From:` and `Date:` lines from the patch file. The patch
+title is likely to be different from the subject of the discussion the
+patch is in response to, so it is likely that you would want to keep
+the Subject: line, like the example above.
+
+
EXAMPLES
--------