development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-07-16 10:38:05 +00:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

Documentation: describe the format of messages with inline patches

Browse source 
Add a DISCUSSION section to the "git format-patch" manual 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.

The example requires QP encoding in the "Subject:" header intended for
the mailer to give the reader a chance to reflect on that, rather than
being startled by it later.  By contrast, in-body "From:" and
"Subject:" lines should be human-readable and not QP encoded.

Inspired-by: Jim Meyering <jim@meyering.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
Improved-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jonathan Nieder 2011-04-14 21:22:02 -05:00 committed by Junio C Hamano
parent 810cae53e0
commit e0d48279d5
1 changed files with 58 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
Documentation/git-format-patch.txt
View file

@ -229,6 +229,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
--------