# git send-email: Usage, Options & Common CI Errors

> git send-email mails patch files to reviewers over SMTP. Reference for --to, --cc, --smtp-server, and the auth and missing-Perl errors common in CI.

Source: https://latchkey.dev/learn/command-reference/git-send-email  
Updated: 2026-06-25

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

```Terminal
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-*.patch
```

## Options

| 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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git send-email: Usage, Options & Common CI Errors?

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt