git format-patch

The kernel mailing-list workflow in one command.

🎯 What & why

Turn one or more commits into mailbox-format patch files (one per commit) suitable for git am or git send-email. The kernel mailing-list workflow.

🧠 Mental model

For each commit in the range, format-patch writes an mbox-style file: From <sha> line, headers (Subject, From, Date), the message, then the diff. The receiver replays it with git am to recreate equivalent commits — same author, same message, new SHA.

🛠️ Synopsis

git format-patch [-k] [(-o | --output-directory) <dir> | --stdout] [--no-thread | --thread[=<style>]]
                 [(--attach | --inline)[=<boundary>] | --no-attach]
                 [-s | --signoff] [--signature=<sig> | --no-signature] [--signature-file=<file>]
                 [-n | --numbered | -N | --no-numbered] [--start-number <n>]
                 [--numbered-files] [--in-reply-to=<msgid>] [--suffix=.<sfx>]
                 [--ignore-if-in-upstream] [--always]
                 [--cover-from-description=<mode>] [--rfc[=<rfc>]] [--subject-prefix=<subject prefix>]
                 [(--reroll-count | -v) <n>] [--to=<email>] [--cc=<email>]
                 [--[no-]cover-letter] [--quiet] [--[no-]encode-email-headers]
                 [--no-notes | --notes[=<ref>]] [--interdiff=<previous>] [--range-diff=<previous> [--creation-factor=<percent>]]
                 [--progress] [<common diff options>]
                 [<since> | <revision range>]

🎚️ Switches & options

Flag	What it does
`-N`	Don't number the patches.
`-o <dir>`	Output directory.
`--cover-letter`	Add a cover letter for the series.
`--subject-prefix=PATCH`	Customize the subject prefix.
`-v <n>`	Reroll: tag as v<n>.

💡 Use cases

Linux kernel-style contribution flow.
Sharing changes via email when no Git remote is shared.
Snapshotting a series for archive.

🧪 Examples

Last 5 commits as patches.

$ git format-patch -5 -o /tmp/patches

Whole branch since main, with cover letter.

$ git format-patch --cover-letter -o /tmp/patches main..feature

Reroll v2.

$ git format-patch -v 2 main..feature

🎓 Recommendations

Pair with git send-email for the full kernel workflow.
Use --cover-letter for series of more than one patch.

🪤 Common pitfalls

Each patch becomes a separate file. With long histories, that's a lot.
Patches don't carry merge commits — format-patch refuses by default. Cherry-pick or split first.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.