git send-email: Usage, Options & Common CI Errors
git send-email sends format-patch output to reviewers as properly threaded emails.
For projects that review patches by email, send-email turns a series of .patch files into a clean, threaded submission over SMTP - the last step of the format-patch workflow.
What it does
git send-email takes patch files (from git format-patch) and emails them over a configured SMTP server, threading the series under the cover letter and honoring To/Cc trailers.
Common usage
git send-email --to=maintainer@example.com *.patch
git format-patch -3 -o out/ && git send-email out/
git send-email --smtp-server=smtp.example.com --smtp-encryption=tls *.patch
git send-email --cc=list@example.com --to=maintainer@example.com 0001-*.patchOptions
| Flag | What it does |
|---|---|
| --to / --cc / --bcc | Recipients |
| --smtp-server <host> | SMTP host (or a sendmail path) |
| --smtp-encryption=tls|ssl | Transport security |
| --annotate | Edit each patch before sending |
| --dry-run | Show what would be sent |
Common errors in CI
git: ‘send-email’ is not a git command - the subcommand ships separately (the git-email package) and needs Perl plus Net::SMTP; install it on the runner. SMTP auth failures ("5.7.x authentication required") mean missing --smtp-user/--smtp-pass or an app password; use --dry-run to validate first.
Using this in CI
CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.
- uses: actions/checkout@v4
with:
fetch-depth: 0 # history, tags, and git describe all need this
- run: |
git rev-parse --is-shallow-repository # expect false
git rev-parse --abbrev-ref HEAD # prints HEAD when detached