git-format-patch
Create patch files from Git commits
TLDR
Create an auto-named .patch file for all the unpushed commits
Write a .patch file for all the commits between 2 revisions to stdout
Write a .patch file for the n latest commits
SYNOPSIS
git format-patch [options] [revision-range] [--] [path…]
PARAMETERS
-p
Generate plain patches without cover letter (default)
--stdout
Output all patches to stdout instead of files
-o
Place patches in specified directory
--cover-letter
Generate a cover letter file (0000-*) summarizing series
-n, --numbered
Name patches with numbers and/or dates
--no-numbered
Name patches simply as 0001, 0002, etc.
-k, --keep-subject
Do not strip [PATCH] from subject lines
--subject-prefix=
Override default [PATCH] prefix
-s, --signature=
Add custom signature string to patches
--signature-file=
Read signature from file
--thread[=style]
Enable threading (shallow, deep, or auto)
--no-thread
Disable threading
-v
Version patches as v
--in-reply-to=
Make first patch reply to specified Message-ID
--notes[=( |
Include Git notes in patches
--base=
Record base commit for quilt/devilspie compatibility
-M[n] | -C[n]
Detect renames/copies with similarity index n
--attach
Attach patch as application/octet-stream
--inline
Inline patch in email body (default)
DESCRIPTION
git format-patch creates a series of patch files in mbox format, each representing a single commit as an email message. It is essential for preparing patches to send via email to mailing lists, project maintainers, or collaborators in the Git ecosystem.
The command scans a specified range of commits (e.g., from a branch or since a tag) and generates one file per commit, complete with standard email headers like Subject, From, Date, Message-ID, and the diff in the body. Patches include commit messages, authorship details, and changes.
Key features include support for cover letters (summarizing the series), threading for email replies, custom signatures, subject prefixes (e.g., [PATCH]), and options to handle renames, notes, or base commits for clean application on divergent branches. Output can be directed to stdout or a directory.
Common workflow: git format-patch -M origin/master produces patches since the last fetch from master. These can then be reviewed, sent with git send-email, or applied elsewhere via git am.
It respects Git's log formatting and diff options, ensuring patches are self-contained and reproducible.
CAVEATS
Patches may not apply cleanly on divergent branches; use --base for complex histories. Large ranges can produce many files. Does not handle binary files well in emails.
COMMON USAGE
git format-patch -3 — last 3 commits.
git format-patch origin/main --stdout | git send-email — pipe to send.
FILE NAMING
Patches named NNNN-description.patch or with dates for numbered series; cover letter as 0000-cover-letter.patch.
HISTORY
Introduced in Git 1.5.0 (2007) as part of email patch workflow. Evolved with Git to support threading, cover letters (1.6.1), notes (1.7.0), and base commits (1.8.0). Central to Linux kernel and open-source contribution processes.
SEE ALSO
git-send-email(1), git-am(1), git-log(1), git-diff(1), git-cherry-pick(1)
