Learn to Use Email with Git

Reviewing patches you've received via email

Now you know the contributor workflow. Ready to learn about the other side?

Check out our next tutorial: Reviewing git contributions via email on git-am.io

Sending several patches at once

Use this to send the last 3 commits:

git send-email HEAD~3

Or all commits since a particular one:

git send-email 209210d

Or just the second-to-last commit:

git send-email -1 HEAD^^

See Revision Selection for more.

Sending patches with a cover letter

Not all changes are straightforward and self-contained. When a change requires several commits, a cover letter can be added as the starting point of the email thread.

git send-email --cover-letter origin/master

The --cover-letter option belongs to the git format-patch command and is not documented in the git-send-email(1) manual.

This will generate an extra email template with placeholders for the subject and main body:

Subject: [PATCH 0/3] *** SUBJECT HERE *** *** BLURB HERE *** your-name (3): core: Move reusable foo logic to a new function core: Add new flag to the aforementioned foo() cmd: New foo subcommand similar to bar core.c | 38 ++++++++------ cmd.c | 13 ++++ 2 files changed, 34 insertions(+), 17 deletions(-) --

In the example above, the subject could become:

Subject: [PATCH 0/3] Derive a foo subcommand from bar

The cover letter could then explain why a new subcommand is needed, and why it cannot or should not be implemented as an option to the existing subcommand that shares some aspects. A cover letter offers a convenient place to provide the rationale behind a change.

Since the default template includes a short log, it can also be useful to add a summary of the structure of a patch series. It could for example start with refactoring commits to prepare the actual change, and that change could also span multiple commits. A complicated change is likely easier to implement and review when decomposed into smaller logical chunks with a clear progression.

Other relevant information that does not necessarily belong in a commit log can be added to a cover letter, such as benchmark results, links to discussions on other forums or literature on the topic. As such, even a single patch submission may benefit from a cover letter.

Specifying a sub-project

Some projects use a single mailing list for several git repositories. Try this to clarify that you're working on the "foobar" project:

git config format.subjectPrefix "PATCH foobar"

Using --annotate every time

git config --global sendemail.annotate yes

"Signing off" on your commits

Some projects, such as the Linux kernel, will ask you to "sign off" on your commits. To do this, add --signoff (or -s) to git send-email. To set it as the default for that git repository:

git config format.signOff yes

The meaning of a signoff depends on the project to which you’re committing. For example, it may certify that the committer has the rights to submit the work under the project’s license or agrees to a Developer Certificate of Origin (DCO). Consult the documentation or leadership of the project to which you’re contributing to understand how the signoffs are used in that project.

More approaches to authentication

Some of the setups in this tutorial cause send-email to prompt for your password, which you may find annoying. There are other ways to authenticate - the simplest of which is:

git config --global sendemail.smtpPass 'your password'

You can also have your password cached in memory for a certain period of time. To cache it for one hour, use:

git config --global credential.helper 'cache --timeout 3600'

For more sophisticated solutions, such as integration with your keyring, see the git-credential man page.