How to Use git send-email
The preferred way to send patches is by email, using git send-email (more information about sending patches can be found on the Community page). This page explains how to use git send-email.
You probably already have git already installed, but that's not necessarily enough to have also the send-email command available. You can check if send-email is available by running "git send-email --help". If it shows the man page for send-email, then send-email is available. Otherwise, you need to install the send-email command. Your distribution probably has a package for it; on Debian the package name is "git-email".
Configuring Your Name and Email Address
You should tell git your name and email address. You have probably done this already, but if not, run these commands:
git config --global user.name "My Name" git config --global user.email "firstname.lastname@example.org"
Configuring the Mail Sending Options
git send-email sends the emails through your SMTP server, so you need to configure the server parameters. Refer to your email provider documentation to find the right parameters. This is how I would configure my mail settings:
git config --global sendemail.smtpencryption tls git config --global sendemail.smtpserver mail.messagingengine.com git config --global sendemail.smtpuser email@example.com git config --global sendemail.smtpserverport 587 git config --global sendemail.smtppass hackme
Storing the password in the git configuration file is obviously a security risk. It's not mandatory to configure the password. If it's not configured, git send-email will ask it every time the command is used.
Configuring the Default Destination Address
For PulseAudio, the patches should be sent to our mailing list. In order to avoid having to remember it and retyping it all the time, you can configure the address to be used by default by git send-email. As you may contribute to many projects using git, it does not make sense to set this option globally so instead we'll only set it in our clone of the PulseAudio code.
git config sendemail.to firstname.lastname@example.org
Avoiding sending mail to yourself
By default, git send-email will add the author of the patch to the Cc: field. When you send patches that you have written yourself, this means that a copy of each patch will be sent to your email address. If you don't like this, you can avoid this by setting this configuration option (see "git send-email --help" for the full list of possible values):
git config --global sendemail.suppresscc self
Using the send-email Command
See "git send-email --help" for the full reference. I'll go through only the basic usage here.
git send-email will ask a few questions before the patches are sent (update: newer git versions ask fewer questions, sometimes no questions at all). Most of the questions have a sensible default value shown in square brackets. Just press enter to use the default value. Type the answer to the question if you don't want to use the default answer. The questions are:
- Who should the emails appear to be from?
- This will be used as the "From" header. You should have configured your name and email address earlier, so the default is usually correct.
- Who should the emails be sent to?
- As noted above, patches should be sent to our mailing list: email@example.com
- Message-ID to be used as In-Reply-To for the first email?
- This can usually be left empty, in which case the patch or patches will appear as a new thread. When sending updated patches, in my opinion it's nice to set this to the "Message-Id" header of the previous version of the patch (for multi-patch series, use the cover letter's Message-Id), so that the full patch history can be easily accessed. This is the only valid use case for setting the "In-Reply-To" header (again, in my opinion). In other words, please do NOT send patches as replies to regular discussion.
- Send this email?
- The mail headers are visible above the question, so that you can check that everything looks OK.
Sending a Single Patch
Sending the last commit in the current branch:
git send-email -1
Sending some other commit:
git send-email -1 <commit reference>
Sending Multiple Patches
Sending the last 10 commits in the current branch:
git send-email -10 --cover-letter --annotate
The --cover-letter option creates an extra mail that will be sent before the actual patch mails. You can add write some introduction to the patch set in the cover letter. If you need to explain the patches, be sure to include the explanations also in the commit messages, because the cover letter text won't be recorded in the git history. If you don't think any introduction or explanation is necessary, it's fine to only have the shortlog that is included in the cover letter by default, and only set the "Subject" header to something sensible.
The --annotate option causes an editor to be started for each of the mails, allowing you to edit the mails. The option is always necessary, so that you can edit the cover letter's "Subject" header.
Adding Patch Version Information
By default the patch mails will have "[PATCH]" in the subject (or "[PATCH n/m]", where n is the sequence number of the patch and m is the total number of patches in the patch set). When sending updated versions of patches, the version should be indicated: "[PATCH v2]" or "[PATCH v2 n/m]". To do this, use the --annotate option and edit the "Subject" header of the mails.
Adding Extra Notes to Patch Mails
Sometimes it's convenient to annotate patches with some notes that are not meant to be included in the commit message. For example, one might want to write "I'm not sure if this should be committed yet, because..." in a patch, but the text doesn't make sense in the commit message. Such messages can be written below the three dashes "---" that are in every patch after the commit message. Use the --annotate option with git send-email to be able to edit the mails before they are sent.