Once you have generated a patch or a series of patches, the next logical step is to send them to another developer or to a development list for review, with an ultimate goal of having them picked up by a developer or upstream maintainer and applied to another repository.

The formatted patches are generally intended to be sent via email by directly importing them into your mail user agent (MUA) or by using Git’s git send-email command. You are not obliged to use git send-email; it is merely a convenience. As you will see in the next section, there are also other tools that use the patch file directly.

Assuming that you want to send a generated patch file to another developer, there are several ways to send the file: you can run git send-email; you can point your mailer directly to the patches; or you can include the patches in a piece of email.

Using git send-email is straightforward. In this example, the patch 0001-A.patch is sent to a mail list called [email protected]:

$ git send-email -to [email protected] 0001-A.patch
0001-A.patch
Who should the emails appear to be from? [Jon Loeliger <[email protected]>]
Emails will be sent from: Jon Loeliger <[email protected]>
Message-ID to be used as In-Reply-To for the first email?
(mbox) Adding cc: Jon Loeliger <[email protected]> from line 
'From: Jon Loeliger <[email protected]>'
OK. Log says:
Sendmail: /usr/sbin/sendmail -i [email protected] [email protected]
From: Jon Loeliger <[email protected]>
To: [email protected]
Cc: Jon Loeliger <[email protected]>
Subject: [PATCH] A
Date: Mon, 29 Dec 2008 16:43:46 -0600
Message-Id: <[email protected]>
X-Mailer: git-send-email 1.6.0.90.g436ed

Result: OK

There are many options to either utilize or work around a myriad of SMTP issues or features. What’s critical is ensuring that you know your SMTP server and port. Likely, it is the traditional sendmail program or a valid outbound SMTP host, such as smtp.my-isp.com.

The git send-email command has many configuration options, which are documented in its manual page.

You may find it convenient to record your special SMTP information in your global configuration file by setting, for example, the values sendemail.smtpserver and sendemail.smtpserverport using commands similar to this:

$ git config --global sendemail.smtpserver smtp.my-isp.com
$ git config --global sendemail.smtpserverport 465

Depending on your MUA, you may be able to directly import an entire file or directory of patches into a mail folder. If so, this can greatly simplify sending a large or complicated patch series.

Here is an example where a traditional mbox style mail folder is created using format-patch and then directly imported into mutt, where the message can be addressed and sent:

$ git format-patch --stdout master~2..master > mbox

$ mutt -f mbox

q:Quit  d:Del  u:Undel  s:Save  m:Mail  r:Reply  g:Group  ?:Help
   1 N   Dec 29 Jon Loeliger    (  15) [PATCH] X
   2 N   Dec 29 Jon Loeliger    (  16) [PATCH] Y
   3 N   Dec 29 Jon Loeliger    (  16) [PATCH] Z
   4 N   Dec 29 Jon Loeliger    (  15) [PATCH] F

The latter two mechanisms, using send-email and directly importing a mail folder, are the preferred techniques for sending email, since both are reliable and not prone to messing with the carefully formatted patch contents. You are less likely, for example, to hear a developer complain about a wrapped line if you use one of these techniques.

On the other hand, you may find that you need to directly include a generated patch file into a newly composed piece of email in a MUA such as thunderbird or evolution. In these cases, the risk of disturbing the patch is much greater. Care should be taken to turn off any form of HTML formatting and to send plain ASCII text that has not been allowed to flow or word wrap in any way.

Depending on your recipient’s ability to handle mail, or contingent on your development list policies, you may or may not want to use an attachment for the patch. In general, inlining is the simpler, more correct approach. It also facilitates an easier patch review. However, if the patch is inlined, some of the headers generated by git format-patch might need to be trimmed, leaving just the From: and Subject: headers in the email body.

Regardless of how the patch mail is sent, it should look essentially identical to the original patch file when received—albeit with more, different mail headers.

The similarity of the patch file format before and after transport through the mail system is not an accident. The key to this operating successfully is plain text and preventing any MUA from altering the patch format through such operations as line wrapping. If you can preclude such interdictions, a patch will remain usable irrespective of how many mail transfer agents (MTAs) carry the data.

There are a host of options and configuration settings to control the generation of email headers for patches. Your project probably has some conventions that you should follow.

If you have a series of patches, you might want to funnel them all to a common directory with the -o directory option to git format-patch and then use git send-email directory to send them all at once. In this case, use either git format-patch --cover-letter or git send-email --compose to write a guiding, introductory cover letter for the entire series.

There are also options to accommodate various social aspects of most development lists. For example, use --cc to add alternate recipients, adding or omitting each Signed-off-by: address as a Cc: recipient, or to select how a patch series should be threaded on a list.