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

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.

Related guides

git am: Usage, Options & Common CI Errorsgit am applies a mailbox of patches as commits, the receiving end of format-patch. Reference for --3way, --co… git apply: Usage, Options & Common CI Errorsgit apply applies a patch file to the working tree or index. Reference for --check, --3way, --index, -p, and… git diff: Usage, Options & Common CI Errorsgit diff shows changes between commits, the index, and the working tree. Reference for --staged, --name-only,… git log: Usage, Options & Common CI Errorsgit log shows commit history with flexible formatting. Reference for --oneline, --graph, --pretty, ranges, an…