Patch-Based and Email Workflows: format-patch, am, apply, and Maintainer Flows: Concepts, Architecture, and Mental Model

1. Patch workflows solve collaboration without requiring a hosted review object

Earlier chapters treated commits as immutable snapshots connected by parent links, refs as names, and mail-independent tools such as cherry-pick and merge as ways to move changes between histories. A patch workflow adds another transport: serialize a change—or a sequence of commits—into reviewable files that can be copied, attached to mail, archived, or handed to a maintainer without requiring GitHub, GitLab, or any other hosting service.

The key distinction is whether the artifact represents only a diff or represents a commit as a mailbox-style message with author/date/subject/body metadata plus its diff. That distinction determines whether the receiver gets changed files only or can reconstruct a commit series.

2. Read repository state before exporting anything

git --version
git status --short --branch
git log --graph --decorate --oneline --all --max-count=30
git rev-parse HEAD
git diff --check
git config --show-origin --get-regexp '^(format\.|sendemail\.|am\.|apply\.|mailinfo\.)'

status and diff --check answer whether accidental working-tree edits or whitespace errors are about to leak into an artifact. The log and exact tip OID establish which committed series you intend to export. Configuration inspection matters because subject prefixes, threading, output directories, whitespace rules, and mail behavior can be supplied implicitly.

3. A raw working-tree patch describes file changes, not a commit

git diff trunk..topic > topic.diff
git apply --check topic.diff
git apply topic.diff

git diff serializes changes between two states. git apply can check or apply those changes to files and, with options, the index. It does not create a commit. The receiving repository therefore does not automatically inherit the original author, author date, commit message, or series boundaries.

4. format-patch serializes commits as mailbox-style messages

For every selected non-merge commit, git format-patch writes one message that contains commit-oriented metadata, the commit message, and the patch against its parent. That is why the receiver can use git am to reconstruct a straight commit series.

git format-patch -o patches trunk..topic

flowchart TD
B[Base commit B] --> C1[Contributor commit C1]
C1 --> C2[Contributor commit C2]
C1 --> P1[0001 mailbox patch]
C2 --> P2[0002 mailbox patch]
P1 --> A1[Maintainer reconstructed commit A1]
P2 --> A2[Maintainer reconstructed commit A2]
A1 --> A2

The first two arrows are source history. The middle arrows represent serialization. The final arrows are a new history constructed by the maintainer: author/message can be preserved from the mailbox, but commit IDs usually differ because parent/committer/date/signature context can differ.

5. git am is the commit-producing counterpart to mailbox patches

git am patches/0001-example.patch patches/0002-example.patch

git am separates each message into authorship, commit-message, and patch portions, applies the patch to the current branch, and creates commits. Before it starts, it records the original tip in ORIG_HEAD, which provides important evidence if the series was applied to the wrong base or needs to be aborted.

6. git mailinfo exposes the parsing layer beneath git am

git mailinfo reads one email message from standard input, extracts the commit-log body into one file and the patch into another, and reports author/email/subject information. Most users should let git am call it indirectly, but seeing the split once clarifies why mailbox metadata is different from raw diff text.

git mailinfo message.txt patch.diff < 0001-example.patch

7. A patch series is ordered because commits are ordered

If a feature is intentionally reviewed as two commits—first refactor, then behavior change—the generated files are numbered so reviewers and maintainers can preserve the dependency order. Reordering patches can make later patches fail or change their meaning because each patch is normally expressed relative to its parent.

A good series therefore has a coherent base, self-contained commit messages, and an order that can be understood and tested incrementally.

8. A cover letter explains the series without becoming one of its commits

git format-patch --cover-letter -o patches trunk..topic

A generated cover letter contains an overall description area, commit list, and diffstat. It is review correspondence, not a source commit. If you pass a cover-letter file directly to git am, its lack of a patch must be handled deliberately (for example with an appropriate empty-message policy); the safer beginner workflow is to review the cover letter and apply only the numbered commit patches.

9. Threading is email-conversation metadata, not Git history

format-patch --thread=shallow can generate Message-ID, In-Reply-To, and References headers so a series appears as one mail thread. Shallow threading makes patches reply to the series head; deep threading makes each patch reply to the previous patch. None of these headers changes the commit graph.

If a team later uses git send-email, it must coordinate who owns threading because send-email can thread messages too. The mandatory course path never requires SMTP.

10. A reroll is a new review iteration, not an amendment to the already-sent files

Reviewers often request changes after v1. The contributor creates v2 and labels it explicitly:

git format-patch --reroll-count=2 --cover-letter \
  --range-diff=topic-v1 -o series-v2 trunk..topic-v2

The reroll count appears in filenames and subjects, while the range-diff in the cover letter helps reviewers see how the logical patches changed from the previous iteration.

11. range-diff compares series as patches, not merely commit IDs

git range-diff trunk..topic-v1 trunk..topic-v2

Because rerolled commits naturally have new OIDs, comparing only hashes says little. range-diff matches corresponding commits by similarity of author/message/diff and shows how each patch changed. Its output is intentionally human-oriented and may change across Git versions; do not build automation that parses its pretty text as a stable protocol.

12. Signed-off-by is a trailer whose meaning comes from project policy

git format-patch --signoff -o patches trunk..topic

A Signed-off-by: Name <email> line is plain commit-message metadata. Git's documentation explicitly says its meaning depends on the project—for example, a contributor representation or Developer Certificate of Origin process. It is not cryptographic proof that the named person produced the patch.

13. Cryptographic signatures answer a different question

A cryptographically signed commit/tag contains verifiable signature material as taught in Chapter 21. Signed-off-by does not. Similarly, the textual signature footer that format-patch --signature can place in an email message is not the same mechanism as Git commit signing. Keep policy/trailer, commit-signature, and email-transport authenticity separate.

14. A maintainer flow makes application an integration decision

A maintainer does not need a pull-request object to review a series. A portable flow is:

1. identify the expected base and inspect the files;
2. review cover letter, commit messages, trailers, and diffs;
3. run git apply --check or an isolated git am trial;
4. apply to a dedicated integration branch;
5. resolve only with documented intent;
6. run project tests and policy checks;
7. publish/integrate according to the project's server-side rules.

Mailing-list conventions are community policy layered over core Git; they are not requirements of Git itself.

15. DevOps connection — patches are portable review and change-control artifacts

Infrastructure, kernel, embedded, restricted-network, and vendor workflows often need review artifacts that survive outside one SaaS platform. A patch series can be stored with an incident/change record, moved through an offline boundary, or reviewed before a maintainer has network access. The portability is valuable only if the base, ordering, authorship, policy trailers, and validation evidence are all explicit.

16. Knowledge check

17. Summary

Raw diffs transport changes; mailbox patches transport commit-oriented review metadata plus diffs. git apply changes files, git am reconstructs commits, mailinfo exposes email parsing, and cover letters/threading/reroll counts organize review rather than history. Signoff, cryptographic signatures, and email identity remain separate trust concepts.

Authoritative references

• git-format-patch
• git-am
• git-apply
• git-range-diff
• git-mailinfo