Patch-Based and Email Workflows: format-patch, am, apply, and Maintainer Flows: Configuration, Design Choices, and Tradeoffs

1. Patch policy should make the receiver's job predictable

A useful patch policy answers: what base should contributors use, how should a multi-commit series be organized, which metadata is required, how should rerolls be labeled, how strictly should whitespace/path rules be enforced, and where should maintainers apply/test a series before integrating it. Configuration can encode convenience, but project policy must explain intent.

2. Inspect effective configuration and its scope

git config --list --show-origin --show-scope
git config --show-origin --get format.outputDirectory
git config --show-origin --get format.subjectPrefix
git config --show-origin --get format.thread
git config --show-origin --get format.coverLetter
git config --show-origin --get sendemail.from
git config --show-origin --get sendemail.smtpUser
git config --show-origin --get am.threeWay
git config --show-origin --get apply.whitespace

A repository-local format policy can be useful for one project; global SMTP/mail identity settings may span projects. Never assume a command line shown in a review exactly describes effective behavior if configuration can supply options implicitly.

3. Useful format.* settings are presentation defaults, not commit-graph rules

git config --local format.outputDirectory ../outgoing-patches
git config --local format.subjectPrefix "PATCH demo-project"
git config --local format.thread shallow
git config --local format.coverLetter auto

These values control where files are written and how review mail is labeled/threaded. A team may prefer command-line options in automation because they make each generated artifact self-describing. Local config is useful for contributor convenience when the convention is stable.

4. Cover-letter policy should state purpose, base, testing, and changes since previous version

For a multi-patch series, reviewers need more than a title. A practical cover letter identifies the problem, expected base, overall design, validation performed, known limitations, and—on rerolls—what changed since v1. Current format-patch can include range-diff/interdiff reviewer aids, but prose should still explain why those changes were made.

5. sendemail.* is optional transport configuration

The course requires no SMTP account. If a real project uses git send-email, configuration may include sender/recipient defaults, SMTP host, encryption, username, and threading behavior. These are transport settings layered around the patch files; the files can be reviewed and applied locally without them.

git config --global sendemail.from "Contributor Example <contributor@example.invalid>"
git config --global sendemail.smtpServer smtp.example.invalid
git config --global sendemail.smtpUser contributor-example

6. Signoff is project policy; do not manufacture it by default

Git deliberately does not provide a global “always sign off every commit” configuration knob. The meaning depends on the receiving project. Contributors should add a signoff only after understanding the project's representation/licensing policy.

git commit --signoff -m "feature: example"
git format-patch --signoff trunk..topic
git am --signoff incoming.patch

These three places can add a trailer at different stages. In particular, git am --signoff adds the maintainer/committer's signoff; it does not retroactively prove the sender agreed to anything.

7. Trailers are structured message conventions, not magic authorization fields

git interpret-trailers --parse <<'EOF'
Subject line

Body.

Signed-off-by: Contributor Example <contributor@example.invalid>
Reviewed-by: Reviewer Example <reviewer@example.invalid>
EOF

Projects may use Reviewed-by, Tested-by, issue references, or other trailers. Their semantics come from the project's documented process. Automated checks can validate syntax/presence, but cannot infer whether a human actually performed the claimed review unless integrated with trusted process evidence.

8. Mailmap normalizes identity display; it does not rewrite historical commits

A contributor may have changed email addresses. .mailmap lets reporting commands show a canonical identity without replacing existing commit objects. That is useful when preparing reviewer statistics or searching history, but do not silently assume it changes the author encoded in a mailbox patch.

git shortlog -sne --all
git log --use-mailmap --format='%h %an <%ae>' -5

9. Whitespace application policy should fail visibly

git apply --check --whitespace=error incoming.diff

Current Git can warn, reject, or fix defined whitespace errors. A maintainer workflow often prefers “reject and ask for a reroll” for source patches because automatic fixing changes what was submitted. --whitespace=fix can be useful in controlled imports but must be documented because the applied diff no longer exactly matches the sender's bytes.

10. Line endings and patch mail transport are separate normalization boundaries

Repository .gitattributes/core.autocrlf policy can change worktree line endings, while email/message parsing has its own CRLF/encoding concerns. git am exposes options/configuration such as am.keepcr and passes message handling to mailinfo. Prefer a stable repository text policy and avoid using whitespace-ignore options merely to force an uncertain patch through.

11. am.threeWay can improve application—but only when the original blobs are available

git config --local am.threeWay true

If a patch fails textually and records the original blob IDs, git am --3way can use available base blobs to perform a three-way merge. This can expose a normal conflict that a maintainer resolves and validates. It is not a promise that an arbitrary patch can be merged on any unrelated base.

12. Apply incoming series on a dedicated maintainer branch

git switch -c incoming/widget-v2 expected-base
git am --3way ../incoming/v2-0001-*.patch ../incoming/v2-0002-*.patch
run-project-tests

A dedicated integration branch makes it clear which ref moved and makes abort/review easy. The final merge/fast-forward/rebase policy is project-specific. Hosted branch protection is a server feature; core Git patch application itself does not enforce review or CI.

13. Detect already-integrated patches before application

Commit IDs can differ even when patches are equivalent. A maintainer can compare patch IDs or use history-aware tools such as git cherry; a contributor can use format-patch --ignore-if-in-upstream in appropriate ranges to avoid exporting a patch already represented upstream.

git show existing-commit | git patch-id --stable
git patch-id --stable < incoming.patch
git format-patch --ignore-if-in-upstream upstream..topic

A patch-ID match is evidence of equivalent patch content under that algorithm, not proof that commit metadata/policy trailers are identical.

14. Email transport is optional; maintainer-flow semantics are not

The mandatory workflow can export patch files to a directory, copy them to another machine, inspect them, apply them, and compare rerolls with no mail transport. SMTP adds delivery/threading/community conventions. The core review artifact remains a file that can be archived and reproduced.

15. Decision table — choose the artifact and policy intentionally

16. Knowledge check

17. Summary

Patch policy spans presentation defaults, project-defined trailers, optional transport, text normalization, three-way fallback, duplicate detection, and integration-branch discipline. Configuration can reduce repetitive typing; it cannot replace documented contributor/maintainer policy or server-side authorization.

Authoritative references

• git-format-patch
• git-send-email
• git-am
• git-apply
• git-interpret-trailers