Checkpoint Lab — Patch-Based and Email Workflows: format-patch, am, apply, and Maintainer Flows

1. Checkpoint scenario — contributor sends v1, maintainer integrates it, contributor rerolls v2

You will create a local bare “project server,” a contributor clone, and a maintainer clone. The contributor prepares a two-patch v1 series. The maintainer has an independent policy change, so patch 1 conflicts during git am --3way; you will resolve it, continue the series, and validate metadata. Then the contributor creates a v2 series and both sides compare v1→v2 with range-diff. No email is sent.

2. Predict four state transitions

1. When git am --3way stops on patch 1, should the maintainer branch tip move to a newly created patch commit yet?
2. What should ORIG_HEAD name during that am session?
3. After resolving/staging patch 1 and running git am --continue, whose identity should be the author and whose should be the committer?
4. Does generating v2 patch files change the contributor's topic-v2 ref or commit IDs?

3. Create the local server and seed trunk

Git Bash / Bash / zsh

mkdir git-patch-checkpoint
cd git-patch-checkpoint
git init --bare project.git
git init -b trunk seed
cd seed
git config user.name "Project Seeder"
git config user.email "seeder@example.invalid"

printf "mode=baseline\nretries=2\n" > policy.conf
printf "# Maintainer Patch Project\n" > README.md
git add .
git commit -m "base: establish project policy"
git remote add origin ../project.git
git push -u origin trunk
BASE=$(git rev-parse HEAD)
cd ..

git clone --branch trunk project.git contributor
git clone --branch trunk project.git maintainer

PowerShell equivalent for file creation

"mode=baseline`nretries=2" | Set-Content policy.conf
"# Maintainer Patch Project" | Set-Content README.md

4. Contributor creates a two-commit v1

cd contributor
git config user.name "Contributor Example"
git config user.email "contributor@example.invalid"
git switch -c topic-v1

printf "mode=contributor\nretries=2\n" > policy.conf
git add policy.conf
git commit -m "policy: request contributor mode"

mkdir checks
cat > checks/check-policy.sh <<'EOF'
#!/bin/sh
set -eu
grep -Eq '^mode=(baseline|contributor|integrated)$' policy.conf
grep -Eq '^retries=[0-9]+$' policy.conf
EOF
git add checks/check-policy.sh
git commit -m "checks: add policy validation"
V1=$(git rev-parse HEAD)
git branch series-v1 "$V1"

git status --short --branch
git log --oneline trunk..topic-v1
git diff --check trunk..topic-v1

5. Export/review v1 without SMTP

mkdir -p ../series-v1
git format-patch --reroll-count=1 --cover-letter --thread=shallow \
  --signoff -o ../series-v1 trunk..topic-v1

ls ../series-v1
sed -n '1,80p' ../series-v1/v1-0000-cover-letter.patch
sed -n '1,55p' ../series-v1/v1-0001-policy-request-contributor-mode.patch

Before transport, the contributor should fill meaningful cover-letter prose in a real workflow. Here the files remain local so you can focus on structure and application.

6. Maintainer creates a legitimate conflicting policy commit

cd ../maintainer
git config user.name "Maintainer Example"
git config user.email "maintainer@example.invalid"

printf "mode=maintainer\nretries=2\n" > policy.conf
git add policy.conf
git commit -m "operations: select maintainer mode"
PRE_AM=$(git rev-parse HEAD)

git status --short --branch
git log --graph --decorate --oneline --all --max-count=10

This is not artificial dirty state; it is a committed competing decision, so three-way application should surface an integration conflict.

7. Start the two-patch am session and verify predictions 1–2

git am --3way \
  ../series-v1/v1-0001-policy-request-contributor-mode.patch \
  ../series-v1/v1-0002-checks-add-policy-validation.patch || true

git status --short --branch
git ls-files -u -- policy.conf
git am --show-current-patch=diff

test "$(git rev-parse HEAD)" = "$PRE_AM"
test "$(git rev-parse ORIG_HEAD)" = "$PRE_AM"

Expected: patch 1 is stopped, policy.conf has unmerged stages, and the branch still points to the maintainer's operations commit. ORIG_HEAD names that pre-am tip.

8. Resolve from documented policy and continue

The checkpoint decision is to integrate both intentions as mode=integrated:

printf "mode=integrated\nretries=2\n" > policy.conf
git add policy.conf

git ls-files -u -- policy.conf
git diff --cached -- policy.conf
git am --continue

After patch 1 is committed, am automatically proceeds to patch 2. The validation script should now exist.

sh checks/check-policy.sh
git status --short --branch
git log -3 --format='%h%n  author: %an <%ae>%n  committer: %cn <%ce>%n  subject: %s%n'

Prediction 3: the reconstructed patch commits list Contributor Example as author and Maintainer Example as committer.

9. Verify that the two patch commits remained two commits

test "$(git rev-list --count "$PRE_AM"..HEAD)" -eq 2
git log --reverse --format='%s' "$PRE_AM"..HEAD
git log -2 --format='%B%n---'

The series boundaries, subjects, and exported signoff trailers survived the mailbox path even though patch 1 required a maintainer resolution.

10. Contributor creates v2 from the same base

cd ../contributor
git switch -c topic-v2 trunk

printf "mode=contributor-v2\nretries=3\n" > policy.conf
git add policy.conf
git commit -m "policy: request contributor mode v2"

mkdir -p checks
cat > checks/check-policy.sh <<'EOF'
#!/bin/sh
set -eu
mode=$(sed -n 's/^mode=//p' policy.conf)
retries=$(sed -n 's/^retries=//p' policy.conf)
test -n "$mode"
test "$retries" -ge 1
test "$retries" -le 5
EOF
git add checks/check-policy.sh
git commit -m "checks: strengthen policy validation"
V2=$(git rev-parse HEAD)

v2 changes both logical patches after review: policy values and validation behavior. It remains based on the same trunk commit, so correspondence is easy to reason about.

11. Compare v1 and v2 before generating mail files

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

A reviewer should see each old patch paired with its v2 counterpart and the patch/message differences. The commit IDs differ because these are different commits; range-diff exists precisely to review that evolution.

12. Generate v2 with explicit reroll/range-diff metadata

mkdir -p ../series-v2
git format-patch --reroll-count=2 --cover-letter --thread=shallow \
  --range-diff=series-v1 --signoff -o ../series-v2 trunk..topic-v2

ls ../series-v2
sed -n '1,150p' ../series-v2/v2-0000-cover-letter.patch

Prediction 4: format-patch writes files only. Verify git rev-parse topic-v2 still equals $V2 and the working tree is clean.

13. Maintainer reviews v2 as a new submission—not an in-place mutation of v1

cd ../maintainer
git status --short --branch

git -C ../contributor range-diff trunk..series-v1 trunk..topic-v2

git -C explicitly asks Git to resolve those revision names inside the contributor repository. In a real handoff the maintainer may not have that repository or its private refs, so this local checkpoint also verifies the range-diff embedded in the v2 cover letter.

Portable review choices are: inspect the range-diff embedded in the v2 cover letter; fetch explicit contributor refs from an approved repository; or create local refs from supplied bundle/commit objects. For this no-network lab, also read the cover letter:

sed -n '1,180p' ../series-v2/v2-0000-cover-letter.patch

14. Write a maintainer patch-series checklist

Incoming patch-series checklist

1. Identify series version and expected base.
2. Preserve the original mailbox files unchanged.
3. Review cover letter, subjects, authors, trailers, diffstat, and sensitive content.
4. Compare vN against vN-1 using provided/fetched range-diff evidence.
5. Apply on a dedicated integration branch with git am --3way when appropriate.
6. On conflict: inspect current patch + index stages; resolve/test/add; continue, or abort.
7. Verify author/committer/message/trailers and run project tests.
8. Detect equivalent/duplicate patches before reapplication.
9. Keep SMTP credentials and private data out of patch artifacts/config/logs.
10. Integrate/publish only through the project's authorized server-side policy.

15. Verification checklist

• Contributor v1 has two commits beyond trunk and exports three files including cover letter.
• Maintainer has one independent conflicting commit before am.
• Patch 1 stops under am --3way; HEAD and ORIG_HEAD equal the pre-am maintainer tip.
• Resolved result is explicitly mode=integrated, staged, and validated.
• am --continue completes both patch commits.
• Reconstructed patch commits preserve contributor authorship and use maintainer committer identity.
• v2 is a separate two-commit series from the same base.
• Standalone range-diff and the v2 cover-letter review material expose v1→v2 changes.
• Generating patch files does not mutate the contributor branch tip.
• No hosted account or SMTP service is required.

16. Cleanup

cd ../..
pwd
rm -rf git-patch-checkpoint

PowerShell equivalent: Set-Location ../..; Remove-Item -Recurse -Force git-patch-checkpoint.

17. Knowledge check

18. What Chapter 23 adds to a production Git operating model

You can now move reviewable changes independently of a hosted PR system: export coherent commit series, preserve/inspect metadata, distinguish raw file application from commit reconstruction, handle stateful am conflicts safely, compare rerolls, detect duplicates, apply project trailers correctly, and keep transport credentials/security separate from Git history.

19. Chapter checkpoint summary

Patch workflows are not legacy trivia. They expose Git's collaboration mechanics in a portable form: a reviewer can inspect the exact artifact, a maintainer can recreate commits with controlled integration decisions, and rerolls can be compared without depending on a proprietary review database.

Authoritative references

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