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

By Daniel Zoghalchali·Latchkey

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

Frequently asked questions

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