Merge branch 'jn/maint-format-patch-doc'

* jn/maint-format-patch-doc:
  Documentation: describe the format of messages with inline patches
This commit is contained in:
Junio C Hamano 2011-05-04 15:51:31 -07:00
Родитель 5ead6a6fdb e0d48279d5
Коммит 0cb09a7e0c
1 изменённых файлов: 58 добавлений и 0 удалений

Просмотреть файл

@ -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
--------