<!doctype html>
<html>
<head>
<title>Learn to use email with git!</title>
<link rel="stylesheet" type="text/css" href="index.css" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8" />
</head>
<body>
<div class="container">
<h1>email + git = <3</h1>
<p>
<a target="_blank" rel="noopener" href="https://git-scm.com">Git</a>
ships with built-in tools for collaborating over email. With this
guide, you'll be contributing to email-driven projects like the Linux
kernel, PostgreSQL, or even git itself in no time.
</p>
<div id="step-2" class="step" style="background-image: url('/static/task2.png')">
<h2>
<small>Step two</small> Configuration
</h2>
<a class="prev" href="#step-1"></a>
<div class="content">
<p class="hardwrap">
You only need to complete this step once for each machine you
intend to send emails from.
</p>
<div class="alert">
Use <code>git config --global --edit</code> to open your <strong>global
configuration file</strong> in your default editor.
</div>
<div class="accordion">
<input type="radio" class="magic" name="mailer" id="mailer-gmail" />
<input type="radio" class="magic" name="mailer" id="mailer-protonmail" />
<input type="radio" class="magic" name="mailer" id="mailer-local" />
<input type="radio" class="magic" name="mailer" id="mailer-generic" checked />
<div class="item mailer-gmail">
<label for="mailer-gmail">Gmail</label>
<div class="content">
<p>
There are two possible ways of using Gmail with
<code>git send-email</code>:
</p>
<ol>
<li>
First, make sure that <a
href="https://support.google.com/accounts/answer/185839"
target="_blank"
>two-factor authentication</a> is enabled for your Google
account. Then, obtain an application-specific password
for git from the <a
href="https://security.google.com/settings/security/apppasswords"
target="_blank"
>app passwords</a> page. To store this password with git,
run this command:
<pre>git config --global sendemail.smtpPass 'your password'</pre>
Next step is to add these details to your global
configuration file:
<pre>[sendemail]
smtpserver = smtp.gmail.com
smtpuser = you@gmail.com
smtpencryption = tls
smtpserverport = 587</pre>
Be sure to fill in your own email address under
<code>smtpuser</code>.
</li>
<li>
It is still possible to use <code>git send-email</code>
without two-factor authentication and application-specific
password, but this requires installation and configuration
of <a
href="https://github.com/google/gmail-oauth2-tools/tree/master/go/sendgmail"
target="_blank"
>the special tool</a>, which mimics regular
<code>sendmail</code>.
</li>
</ol>
<p>
Also, if you haven't yet, run these
commands - again, making the appropriate changes:
</p>
<pre>git config --global user.email "you@gmail.com"
<!-- -->git config --global user.name "Your Name"</pre>
<a href="#step-3" class="button">Next</a>
</div>
</div>
<div class="item mailer-protonmail">
<label for="mailer-protonmail">Protonmail</label>
<div class="content">
<p>
Protonmail does not support the open, industry-standard
protocols necessary for git send-email to work
out-of-the-box. To solve this, Protonmail offers
<a href="https://protonmail.com/bridge/">Protonmail Bridge</a>.
Otherwise, you need to install & configure
<a href="https://github.com/emersion/hydroxide">Hydroxide</a>
to connect to Protonmail with SMTP. Once you have configured
Protonmail Bridge or Hydroxide, use its SMTP details along
with the generic instructions below.
</p>
<p>
<strong>Protonmail bridge users:</strong> the bridge uses SSL
authentication, but it self-signs the certificate used for
SSL, so you will need to disable SSL verification with the
daemon in your git config by setting an empty value for
sendemail.smtpsslcertpath.
</p>
<div class="alert">
Be advised that Protonmail is generally known to be a pretty
bad email host. They will munge up your outgoing emails and
your patches may fail to apply when received by the other end.
Not to mention their mistreatment of open source and false
promises of security! You should consider a different mail
provider.
</div>
<a href="#step-3" class="button">Next</a>
</div>
</div>
<div class="item mailer-local">
<label for="mailer-local">Local SMTP client (msmtp, nbSMTP, sendmail)</label>
<div class="content">
<p>
If you already have an SMTP client installed, you can configure
git send-email to use it by setting <code>sendemail.smtpserver</code>
to the path of its executable. For example, to use msmtp you
could add this to your global configuration file:
<pre>[sendemail]
smtpserver = /usr/bin/msmtp</pre>
</p>
<p>
If you have multiple accounts configured for your SMTP client and want to specify one, you can use the
<code>sendemail.smtpserveroption</code> setting. For example, to choose an account named
<code>work</code> configured for msmtp:
<pre>[sendemail]
smtpserver = /usr/bin/msmtp
smtpserveroption = -a
smtpserveroption = work</pre>
</p>
<a href="#step-3" class="button">Next</a>
</div>
</div>
<div class="item mailer-generic">
<label for="mailer-generic">Generic instructions</label>
<div class="content">
<p>
Your email provider should have instructions somewhere for
<strong>SMTP access</strong>. Look these details up, and then
add the following details from your mail provider:
</p>
<pre>[sendemail]
smtpserver = mail.example.org
smtpuser = you@example.org
smtpencryption = tls
smtpserverport = 587</pre>
<p>
Be sure to fill in the appropriate values for your email
provider - you will probably only have to fill in
<code>smtpserver</code> and <code>smtpuser</code>. Also, if
you haven't yet, run these commands - again, making the
appropriate changes:
</p>
<pre>git config --global user.email "you@example.org"
<!-- -->git config --global user.name "Your Name"</pre>
<a href="#step-3" class="button">Next</a>
</div>
</div>
</div>
</div>
<a class="next" href="#step-3"></a>
</div>
<div id="step-3" class="step" style="background-image: url('/static/task3.png')">
<h2>
<small>Step three</small> Give it a shot!
</h2>
<a class="prev" href="#step-2"></a>
<div class="content">
<p class="hardwrap">
It's time to take it for a spin - we're going to send a patch.
Ready?
</p>
<div class="content well">
<ol>
<li>
<strong>Clone the upstream repository</strong>. No need to make a
fork! We have prepared a repository for you to test with:
<pre>git clone <a
href="https://git.sr.ht/~sircmpwn/email-test-drive"
>https://git.sr.ht/~sircmpwn/email-test-drive</a>
<!-- -->cd email-test-drive</pre>
</li>
<li>
<strong>Make your changes</strong>. Let's add a file with your
progress so far:
<pre>echo "I'm about to try git send-email" >your-name</pre>
<div style="margin: 0.5rem 0">
Be sure to change <code>your-name</code> to your own!
</div>
</li>
<li>
<strong>Commit your changes</strong>. Check out the official
(and free) <a
href="https://git-scm.com/book/en/v2"
target="_blank"
rel="noopener"
>Pro Git</a> book if you don't know how to do this.
<pre>git add your-name
<!-- -->git commit -m "Demonstrate that I can use git send-email"</pre>
</li>
<li>
<strong>Send the patch</strong>! If you check out the
<code>README.md</code> file, you'll note that patches should be
sent to <a href="mailto:~sircmpwn/email-test-drive@lists.sr.ht">
~sircmpwn/email-test-drive@lists.sr.ht</a>.
<pre>git send-email --to="~sircmpwn/email-test-drive@lists.sr.ht" HEAD^</pre>
<div style="margin: 0.5rem 0">
If prompted for an <code>In-Reply-To</code>, you can ignore
it for now (just press enter). Follow the rest of the prompts
and you've done it! If you have any problems at this step,
feel free to
<a href="mailto:~sircmpwn/sr.ht-discuss@lists.sr.ht?subject=git-send-email%20help">
email us
</a> for help. If it worked, you should see your email appear
in the <a
target="_blank"
rel="noopener"
href="https://lists.sr.ht/~sircmpwn/email-test-drive"
>mailing list archives</a> momentarily!
</div>
</li>
<li>
<strong>Check your inbox</strong>... someone has some feedback
on your patch!
</li>
</ol>
<a href="#step-4" class="button">Next</a>
</div>
<div class="alert" style="margin-top: 1rem">
<strong>Warning!</strong> Some people think that they can get
away with sending patches through some means other than <code>
git send-email</code>, but you can't. Your patches will be broken
and a nuisance to the maintainers whose inbox they land in.
Follow the golden rule: <em>just use git send-email</em>.
</div>
</div>
<a class="next" href="#step-4"></a>
</div>
<div id="step-4" class="step" style="background-image: url('/static/task4.png')">
<h2>
<small>Step four</small> Dealing with feedback
</h2>
<a class="prev" href="#step-3"></a>
<div class="content">
<div class="content well">
<p style="margin-bottom: 0.5rem">
No one ever gets it right on the first try. Don't worry, it's all
part of the process! You may receive some feedback on your patch
from the maintainers of the software. This feedback will arrive in
the form of a reply to your email. If you have any questions,
just reply back - and remember to "reply all"! In the meantime,
let's fix the patch.
</p>
<div class="alert">
In this tutorial, the feedback was generated by a bot, but feel
free to reply to get the hang of it. You need to make sure your
email client is configured to write emails in <strong>plain
text</strong> before you do, and please try to avoid
<a href="/top-posting.html" target="_blank">top posting</a>.
We also have an
<a
target="_blank"
href="https://man.sr.ht/lists.sr.ht/etiquette.md"
>etiquette guide</a> that'll help you avoid any faux pas.
</div>
<ol>
<li>
<strong>Make the changes</strong>. Update the files to match the
changes requested by the maintainers. We'll leave this to you.
</li>
<li>
<strong>Amend your commit</strong>. Git is designed for you to
<em>edit</em> your commit history. It's not set in stone! The
maintainers reviewing your work don't want to merge a patch
which has mistakes, even if it's followed up by a fix, so
you'll have to <strong>amend</strong> your previous commit:
<pre>git commit -a --amend</pre>
<p>
First time amending a commit? Amending and rebasing commits
is an essential skill in this workflow. Check out our
<a
href="https://git-rebase.io"
target="_blank"
>comprehensive guide to git rebase</a> if you'd like to learn
more.
</p>
</li>
<li>
<strong>Set the default "to" address</strong>. Let's make this
easier on ourselves by setting the default email address for
this repo, so we needn't enter it every time:
<pre>git config sendemail.to "~sircmpwn/email-test-drive@lists.sr.ht"</pre>
</li>
<li>
<strong>Send the new patch</strong>! This time we'll use
<code>-v2</code> to indicate that this the second version of
this patch. If we do this again, we'll use <code>-v3</code>.
<pre>git send-email --annotate -v2 HEAD^</pre>
<p>
Note that we also specified the "--annotate" flag. This is
going to open the email in our editor before sending it out,
so we can make any changes. We're going to add some "timely
commentary". Look for the "---" and add a short summary of
the differences since the first patch on the next line. It
should look something like this:
</p>
<pre>Subject: [PATCH v2] Demonstrate that I can use git send-email
<!-- -->---
<!-- -->This fixes the issues raised from the first patch.
<!-- -->your-name | 1 +
<!-- -->1 file changed, 1 insertion(+)</pre>
<p>
This text gives the maintainers some extra context about your
patch, but doesn't make it into the final git log. Close your
editor, follow the prompts again, and that's it - you're done!
Congratulations!
</p>
<p>
If you want some more tips on using git send-email, check out
the next page.
</p>
</li>
</ol>
<a href="#step-5" class="button">Next</a>
</div>
</div>
<a class="next" href="#step-5"></a>
</div>
<div id="step-5" class="step" style="background-image: url('/static/task5.png')">
<!-- TODO: Move step 5 onto a separate page so each tip is linkable? -->
<h2>
Tips & tricks
</h2>
<a class="prev" href="#step-4"></a>
<div class="content wells">
<p class="hardwrap">
Miscellaneous tips and tricks which may serve you well as you use
git send-email.
</p>
<div class="well">
<h3>Sending several patches at once</h3>
<p>Use this to send the last 3 commits:</p>
<pre>git send-email HEAD~3</pre>
<p>Or all commits since a particular one:</p>
<pre>git send-email 209210d</pre>
<p>Or just the second-to-last commit:</p>
<pre>git send-email -1 HEAD^^</pre>
<p>
See <a
href="https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection"
target="_blank"
>Revision Selection</a> for more.
</p>
</div>
<div class="well">
<h3>Specifying a sub-project</h3>
<p>
Some projects use a single mailing list for several git
repositories. Try this to clarify that you're working on the
"foobar" project:
</p>
<pre>git config format.subjectPrefix "PATCH foobar"</pre>
</div>
<div class="well">
<h3>Using --annotate every time</h3>
<pre>git config --global sendemail.annotate yes</pre>
</div>
<div class="well">
<h3>"Signing off" on your commits</h3>
<p>
Some projects, such as the Linux kernel, will ask you to "sign
off" on your commits. To do this, add <code>--signoff</code> (or
<code>-s</code>) to <code>git send-email</code>. To set it as the
default for that git repository:
</p>
<pre>git config format.signOff yes</pre>
<p>
By doing this you acknowledge that you have read the
<a
href="https://developercertificate.org/"
target="_blank"
rel="noopener"
>Developer Certificate of Origin (DCO)</a>.
</p>
</div>
<div class="well">
<h3>More approaches to authentication</h3>
<p>
This tutorial configures git in a way that causes send-email to
prompt for your password, which you may find annoying. There are
other ways to authenticate - the simplest of which is:
</p>
<pre>git config --global sendemail.smtpPass 'your password'</pre>
<p>
You can also have your password cached in memory for a certain
period of time. To cache it for one hour, use:
</p>
<pre>git config --global credential.helper 'cache --timeout 3600'</pre>
<p>
For more sophisticated solutions, such as integration with your
keyring, see the <a
href="https://git-scm.com/docs/gitcredentials"
>git-credential</a> man page.
</p>
</div>
<a class="next" href="#step-1">Back to the start</a>
</div>
<a class="next" style="visibility: hidden"></a>
</div>
<div id="step-1" class="step" style="background-image: url('/static/task1.png')">
<h2>
<small>Step one</small> Installation
</h2>
<a class="prev" style="visibility: hidden"></a>
<div class="content">
<p class="hardwrap">
Let's start by installing the appropriate packages for your
operating system.
</p>
<div class="accordion">
<input type="radio" class="magic" name="os" id="os-arch" checked />
<input type="radio" class="magic" name="os" id="os-alpine" />
<input type="radio" class="magic" name="os" id="os-centos" />
<input type="radio" class="magic" name="os" id="os-debian" />
<input type="radio" class="magic" name="os" id="os-fedora" />
<input type="radio" class="magic" name="os" id="os-freebsd" />
<input type="radio" class="magic" name="os" id="os-gentoo" />
<input type="radio" class="magic" name="os" id="os-guix" />
<input type="radio" class="magic" name="os" id="os-macos" />
<input type="radio" class="magic" name="os" id="os-nixos" />
<input type="radio" class="magic" name="os" id="os-omnios" />
<input type="radio" class="magic" name="os" id="os-openbsd" />
<input type="radio" class="magic" name="os" id="os-opensuse" />
<input type="radio" class="magic" name="os" id="os-pkgsrc" />
<input type="radio" class="magic" name="os" id="os-solus" />
<input type="radio" class="magic" name="os" id="os-ubuntu" />
<input type="radio" class="magic" name="os" id="os-void" />
<input type="radio" class="magic" name="os" id="os-windows" />
<div class="item os-arch">
<label for="os-arch">
<img src="/static/arch.png" />
Arch Linux
</label>
<div class="content">
<p>
The <code>git</code> package includes the git email tools,
though you might need to install a few additional packages to
get it fully working.
Run this to install it:
</p>
<pre>sudo pacman -Syu --needed git perl-authen-sasl perl-net-smtp-ssl perl-mime-tools</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-alpine">
<label for="os-alpine">
<img src="/static/alpine.png" />
Alpine Linux
</label>
<div class="content">
<p>
The <code>git-email</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo apk add git git-email</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-centos">
<label for="os-centos">
<img src="/static/centos.png" />
CentOS
</label>
<div class="content">
<p>
The <code>git-email</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo yum install git git-email</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-debian">
<label for="os-debian">
<img src="/static/debian.png" />
Debian
</label>
<div class="content">
<p>
The <code>git-email</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo apt install git git-email</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-fedora">
<label for="os-fedora">
<img src="/static/fedora.png" />
Fedora
</label>
<div class="content">
<p>
The <code>git-email</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo dnf install git git-email</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-freebsd">
<label for="os-freebsd">
<img src="/static/freebsd.png" />
FreeBSD
</label>
<div class="content">
<p>
The <code>git</code> package includes the git email tools.
Run this to install it:
</p>
<pre>pkg install git</pre>
<p>
Or, to install from ports:
</p>
<pre>cd /usr/ports/devel/git && make install clean</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-gentoo">
<label for="os-gentoo">
<img src="/static/gentoo.png" />
Gentoo
</label>
<div class="content">
<p>
The <code>git</code> package includes the git email tools.
Run this to install it:
</p>
<pre>emerge dev-vcs/git</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-guix">
<label for="os-guix">
<img src="/static/guix.png" />
Guix
</label>
<div class="content">
<p>
The <code>git</code>
package's <code>send-email</code> output contains
the git email tools. Run this to install both git
and the email tools:
</p>
<pre>guix package -i git git:send-email</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-macos">
<label for="os-macos">
<img src="/static/apple.png" />
macOS
</label>
<div class="content">
<p>
All of the usual ways to install <code>git</code> on macOS
include the git email tools by default, including Apple's
developer tools as well as
<a href="https://brew.sh">Homebrew</a>,
<a href="https://www.macports.org/install.php">MacPorts</a>,
and the official git bundle from
<a href="https://git-scm.com/download/mac">git-scm.com</a>.
</p>
<p>
<br>
The easiest way is to just run:
</p>
<pre>git</pre>
<p>
If <code>git</code> is not installed already, you will be
prompted to install the Apple command line developer tools.
</p>
<p>
It may be necessary to install missing perl SSL modules by
hand:
<pre>sudo -H cpan Net::SMTP::SSL IO::Socket::SSL</pre>
</p>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-nixos">
<label for="os-nixos">
<img src="/static/nixos.png" />
Nixpkgs
</label>
<div class="content">
<p>
The <code>gitAndTools.gitFull</code> package from the NixOS
channel includes the git email tools. Run this to install it:
</p>
<pre>nix-env -iA nixos.gitAndTools.gitFull</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-omnios">
<label for="os-omnios">
<img src="/static/omnios.png" />
OmniOS
</label>
<div class="content">
<p>
The <code>git</code> package includes the git email tools.
Run this to install it:
</p>
<pre>pkg install git</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-openbsd">
<label for="os-openbsd">
<img src="/static/openbsd.png" />
OpenBSD
</label>
<div class="content">
<p>
The <code>git</code> package includes the git email tools.
Run this to install it:
</p>
<pre>pkg_add git p5-Authen-SASL p5-Net-SMTP-SSL</pre>
<p>
Or, to install from ports:
</p>
<pre>cd /usr/ports/devel/git && make install clean && cd ../../security/p5-Authen-SASL && make install clean && cd ../../net/p5-Net-SMTP-SSL && make install clean
</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-opensuse">
<label for="os-opensuse">
<img src="/static/suse.png" />
openSUSE
</label>
<div class="content">
<p>
The <code>git-email</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo zypper install git-email</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-pkgsrc">
<label for="os-pkgsrc">
<img src="/static/pkgsrc.png" />
pkgsrc
</label>
<div class="content">
<p>
The <code>devel/git</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo pkg_add git</pre>
<p>
Or, to build from source:
</p>
<pre>cd /usr/pkgsrc/devel/git && make install </pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-solus">
<label for="os-solus">
<img src="/static/solus.png" />
Solus
</label>
<div class="content">
<p>
The <code>git</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo eopkg install git</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-ubuntu">
<label for="os-ubuntu">
<img src="/static/ubuntu.png" />
Ubuntu
</label>
<div class="content">
<p>
The <code>git-email</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo apt install git git-email</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-void">
<label for="os-void">
<img src="/static/void.png" />
Void Linux
</label>
<div class="content">
<p>
The <code>git</code> package includes the git email
tools. Run this to install it:
</p>
<pre>sudo xbps-install -S git</pre>
<a href="#step-2" class="button">Next</a>
</div>
</div>
<div class="item os-windows">
<label for="os-windows">
<img src="/static/windows.png" />
Microsoft Windows
</label>
<div class="content">
<p>
The official git bundle from
<a href="https://git-scm.com/download/windows">git-scm.com</a>
includes the git email tools.
</p>
<a href="#step-2" class="button">Next</a>
</div>
</div>
</div>
<div class="alert" style="margin-top: 1rem">
Don't see your OS here? Consult your OS documentation for
installation, and once you finish this tutorial, send a patch
adding yours to our
<a
href="https://git.sr.ht/~sircmpwn/git-send-email.io"
target="_blank"
>git repository</a>.
</div>
</div>
<a class="next" href="#step-2"></a>
</div>
<footer>
This tutorial brought to you courtesy of
<a href="https://sourcehut.org">sourcehut</a>, the hacker's forge. 100%
open source Git & Mercurial hosting, continuous integration,
mailing lists, and <strong>no JavaScript</strong>!
<a href="https://meta.sr.ht/register">Try it today</a>!
</footer>
</div>
</body>
</html>