Sending and Receiving Patches via Email

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. 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 linkgit: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. MUA-SPECIFIC HINTS ------------------ Here are some hints on how to successfully submit patches inline using various mailers. GMail ~~~~~ GMail does not have any way to turn off line wrapping in the web interface, so it will mangle any emails that you send. You can however use "git send-email" and send your patches through the GMail SMTP server, or use any IMAP email client to connect

When sending patches via email, it's essential to ensure that the mailer is configured correctly to avoid corrupting the patch, and the patch should be placed in a UNIX mailbox format, allowing the recipient to apply it using git-am; tips are provided for common mailers, such as GMail, to successfully submit patches inline.