# git format-patch: Usage, Options & Common CI Errors

> git format-patch turns commits into mailbox patch files for review or git am. Reference for -N, --stdout, --cover-letter, and range errors in CI.

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

git format-patch exports commits as .patch files (one per commit) ready to email or replay with git am.

format-patch is half of the email-patch workflow. It produces mbox-formatted patches that git am consumes.

## What it does

git format-patch creates one mailbox-format patch file per commit in a range, preserving author, message, and diff so the series can be reviewed or reapplied.

## Common usage

```Terminal
git format-patch -1 HEAD           # the last commit
git format-patch main..feature     # a range
git format-patch -3 --stdout > series.mbox
git format-patch origin/main --cover-letter
```

## Options

| Flag | What it does |
| --- | --- |
| -<n> / -N | Last n commits |
| --stdout | Write the series to stdout |
| --cover-letter | Add a summary cover letter |
| -o <dir> | Output directory for patch files |
| <since>..<until> | Commit range to export |

## Common errors in CI

An empty or wrong range produces no patches silently. fatal: ambiguous argument means the base ref is missing (often a shallow clone) - fetch the base branch first, or use an explicit -<n> count instead of a symbolic range.

## 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 format-patch: Usage, Options & Common CI Errors?

format-patch is half of the email-patch workflow. It produces mbox-formatted patches that git am consumes.

### What it does?

git format-patch creates one mailbox-format patch file per commit in a range, preserving author, message, and diff so the series can be reviewed or reapplied.

### Common errors in CI?

An empty or wrong range produces no patches silently. fatal: ambiguous argument means the base ref is missing (often a shallow clone) - fetch the base branch first, or use an explicit -<n> count instead of a symbolic range.

---

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