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 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.
Checking for patch corruption
Many mailers if not set up properly will corrupt whitespace. Here
are two common types of corruption:
• Empty context lines that do not have any whitespace.
• Non-empty context lines that have one extra whitespace at the
beginning.
One way to test if your MUA is set up correctly is:
• Send the patch to yourself, exactly the way you would, except
with To: and Cc: lines that do not contain the list and
maintainer address.
• Save that patch to a file in UNIX mailbox format. Call it
a.patch, say.
• Apply it:
$ git fetch <project> master:test-apply
$ git switch test-apply
$ git restore --source=HEAD --staged --worktree :/
$ git am a.patch
If it does not apply correctly, there can be various reasons.
• The patch itself does not apply cleanly. That is bad but does
not have much to do with your MUA. You might want to rebase
the patch with git-rebase(1) before regenerating it in this
case.
• The MUA corrupted your patch; "am" would complain that the
patch does not apply. Look in the .git/rebase-apply/
subdirectory and see what patch file contains and check for
the common corruption patterns mentioned above.
• While at it, check the info and final-commit files as well.
If what is in final-commit is not exactly what you would want
to see in the commit log message, it is very likely that the
receiver would end up hand editing the log message when
applying your patch. Things like "Hi, this is my first
patch.\n" in the patch e-mail should come after the
three-dash line that signals the end of the commit message.
