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.
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
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.
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:
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--stdoutsends all patches to one stream. - Which commits.
-Nmeans the last N commits,<since>..everything after a commit, and--rootincludes the first commit. Merges are skipped. - Applying.
git amcreates one commit per patch. If a patch fails, it stops: fix and use--continue, skip with--skipor use--abort.--3wayuses blob IDs on theindexlines to attempt a merge,-sadds a sign-off, and--keep-non-patchkeeps non-[PATCH]bracket text in the subject. - Committer after
am. The committer is whoever ranam, 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;--rfcis a shortcut. - Whitespace trouble. Mail clients that wrap lines or convert tabs corrupt patches. Send with
git send-emailor attach the file as plain text. - Not for binary changes unless you add
--binary, which embeds a base85 patch.