Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Objects, Refs and Internals

Email patch format

Reference for the mbox-style patch files made by git format-patch and read by git am: the From line, mail headers, subject prefix, --- separator, diffstat and signature.

git format-patch turns each commit into a small text file shaped like an email: headers, a body with the commit message, a diffstat, the diff and a signature. git am reads those files (or a whole mailbox) and recreates the commits with the original author, date and message. git send-email sends the same files over SMTP. This is the format used by projects that review patches on mailing lists, such as the Linux kernel and Git itself.

Because the format is just text, it works without any server: attach the files to a mail, drop them on a shared drive, or pipe them between machines.

Terminal
git format-patch -3                 # one file per commit, last three
git format-patch --stdout main..    # a single mbox stream
git am 0001-*.patch                 # apply and commit

Try it

Bash Create a patch file and read its parts

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Round trip: format-patch on one clone, am on another

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Layout

A patch file made by format-patch looks like this:

TEXT
From <commit-id> Mon Sep 17 00:00:00 2001
From: Author Name <[email protected]>
Date: Thu, 1 Jan 2026 12:00:00 +0000
Subject: [PATCH 2/3] Subject line of the commit

Body of the commit message.
---
 f.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/f.txt b/f.txt
...
-- 
2.56.0
Part Description
From <id> Mon Sep 17 00:00:00 2001 The mbox "From " separator line. The ID is the commit ID, and the fixed date is a magic value that lets tools such as file recognize a Git patch.
From: The commit author. If the committer differs, am keeps the author from here and takes the committer from the person running am.
Date: The author date in RFC 2822 form.
Subject: The first line of the message prefixed by [PATCH]. In a series it is [PATCH n/m], and with -v2 it is [PATCH v2 n/m]. Long subjects are folded with continuation lines.
Body The rest of the commit message. Trailers such as Signed-off-by: stay at its end.
--- Separates the message from what follows. Anything between the body and the diff (diffstat, your own notes for reviewers) is dropped by git am.
Diffstat Summary of changed files.
Diff A unified diff in the format of Unified diff format.
-- and version A signature line (dash, dash, space) and the Git version that made the patch. --signature changes it.

Non-ASCII text in headers is encoded as RFC 2047 words (=?UTF-8?q?...?=), and the body gets a Content-Type header with charset=UTF-8 plus a transfer encoding when needed.

A cover letter and series

git format-patch --cover-letter adds 0000-cover-letter.patch with a subject like [PATCH 0/3] *** SUBJECT HERE ***, a body to fill in, and the shortlog and diffstat of the whole series. --range-diff=<previous> appends a comparison with the earlier version, and --base=<commit> adds a base-commit: line so reviewers know what the series applies to.

Usage notes

  • File names are NNNN-subject-in-kebab-case.patch, limited in length by --filename-max-length; -o <dir> chooses the folder and --stdout sends all patches to one stream.
  • Which commits. -N means the last N commits, <since>.. everything after a commit, and --root includes the first commit. Merges are skipped.
  • Applying. git am creates one commit per patch. If a patch fails, it stops: fix and use --continue, skip with --skip or use --abort. --3way uses blob IDs on the index lines to attempt a merge, -s adds a sign-off, and --keep-non-patch keeps non-[PATCH] bracket text in the subject.
  • Committer after am. The committer is whoever ran am, as the second example shows, while the author comes from the patch.
  • Subject prefixes. --subject-prefix="RFC PATCH" and -v <n> change the bracket text; --rfc is a shortcut.
  • Whitespace trouble. Mail clients that wrap lines or convert tabs corrupt patches. Send with git send-email or attach the file as plain text.
  • Not for binary changes unless you add --binary, which embeds a base85 patch.