git format-patch

Patching & Rewriting

Turn commits into email-ready patch files


The 'git format-patch' command writes each commit of a range into its own numbered .patch file: the author, the date, the commit message as the email subject and body, a change summary, and the diff. Projects that review by mailing list (like Git itself and the Linux kernel) receive contributions this way, and git am turns the files back into commits.

Synopsis

git format-patch [-o <dir>] [--stdout] [-<n>] [<since> | <revision-range>]
[ ] optional| or<arg> placeholder... repeatable--flag option

Options

Click any option to expand

Beginner (2)

Write the patch files into this folder.

RecommendedKeep patch files out of your project root

Example

git format-patch -1 -o patches

Print all patches to the terminal instead of writing files.

When neededSend the patches to another program or one file

Example

git format-patch --stdout main > series.mbox

Intermediate (1)

Also write 0000-cover-letter.patch, an introduction email for the series.

When neededIntroduce a multi-patch series

Example

git format-patch --cover-letter main

Choosing the Right Option

Ways to hand over commits

Keeping author and message

CommandKeeps authorship
git diff > change.diffNo
git format-patch + git amYes
git bundleYes (whole commits and branches)

Examples

Commits since main

git format-patch main

One file per commit not on main.


The last commit

git format-patch -1

Just the newest commit.


Into a folder

git format-patch main -o patches

Write the files into patches/.


With a cover letter

git format-patch --cover-letter main

Add a 0000 introduction email.

Workflow Examples

1
git format-patch main -o outgoing

One file per commit

2
git send-email outgoing/*.patch

Mail them to the list

Troubleshooting

No patch files created

Cause: The range is empty (e.g. your branch has no commits beyond main)

Check with git log --oneline main..HEAD

Tips & Pitfalls

Best Practices

  • ✓Rebase on the latest main before making patches.
  • ✓Keep one logical change per commit — each becomes one email.

Common Mistakes

  • ✗Sending a git diff instead of format-patch — a diff loses the author, date and message.
  • ✗Forgetting the range and getting nothing: format-patch needs a starting point (main, -1…).

FAQ

A:

Yes, but git apply only changes files; git am also creates the commit with the original author and message.