Synopsis
git format-patch [<options>] <range>
git format-patch -1 <commit>Description
The git format-patch command produces one mailbox-formatted patch file per commit in a range, ready to be applied with git am or sent with git send-email. Each patch includes the commit message, author, date, and the diff. Patches are numbered (0001-..., 0002-...) so they apply in order.
This is the format the Linux kernel and many open source projects use for code review on mailing lists. Even projects that use pull requests sometimes accept patches via email, and format-patch is the standard producer.
In day-to-day use, git format-patch integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git format-patch --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.
Understanding how git format-patch interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git format-patch's side effects helps avoid all three.
Common Options
| Option | Description |
|---|---|
-<n> | Generate patches for the last n commits. |
-o <dir> | Write patches to a directory. |
--cover-letter | Generate a 0000 cover letter for the series. |
-v <n>, --reroll-count=<n> | Mark patches as the n-th iteration. |
--subject-prefix=<prefix> | Custom subject prefix (default PATCH). |
--to=<addr> / --cc=<addr> | Add recipients in headers. |
--thread | Add In-Reply-To headers. |
Examples
git format-patch -3
# Patches for the last 3 commits, in CWD
git format-patch -o ../patches main..feature
# Patches from main to feature, into ../patches/
git format-patch --cover-letter -v2 origin/main
# Versioned series with a cover letter
git format-patch --subject-prefix="PATCH myproj" -1 HEAD
# Custom subject for a project-specific listCommon Mistakes
Generating patches against the wrong base produces apply failures for reviewers — pick the right upstream. Without --cover-letter, a multi-patch series has no introduction; reviewers appreciate one. Reroll without -v creates ambiguity about which version is being reviewed.
Related Commands
git am, git send-email, git request-pull, git range-diff