NOTE: Gitlab merge requests are now the strongly preferred method for submitting patches. Instructions on creating a merge request can be found in the Gitlab documentation.

How to Use git send-email

Installing 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 "myemail@example.com"

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 tanuk@fastmail.fm
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 pulseaudio-discuss@lists.freedesktop.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: pulseaudio-discuss@lists.freedesktop.org
Message-ID to be used as In-Reply-To for the first email?
- This should usually be left empty. Don't send patches as replies to regular discussion, that makes it harder to keep track of the patches.
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 -v option. Here's an example (you may want to add --annotate to add notes to the patch about what changed in the new version):

git send-email -v2 -1

Changing or amending the [PATCH] tag in the subject

The default "[PATCH]" tag can be changed with --subject-prefix. This is useful especially when sending pavucontrol or paprefs patches, because the subject should note when the patch is meant for some other git repository than the main pulseaudio repository. For example:

# Using "[PATCH pavucontrol]" as the tag is a good way to indicate
# that the patch is meant for pavucontrol.
git send-email -1 --subject-prefix="PATCH pavucontrol"

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.

Formatting and sending in two steps

Instead of using the --annotate option, one can first run "git format-patch" to create text file(s) (with the -o option to select a directory where the text files are stored). These files can be inspected and edited, and when that is done, one can then use "git send-email" (without the -1 option) to send them.