Checkpoint Lab — Merge Algorithms, Conflict Engineering, rerere, and Custom Merge Drivers

1. Checkpoint scenario — integrate text, path, and semantic changes with explicit evidence

The checkpoint uses separate disposable repositories for three integration questions: a text timeout conflict, a rename/delete migration, and a clean-but-invalid capacity merge. It then repeats the text conflict with rerere and optionally demonstrates a narrow generated-file driver.

2. Predict before running commands

1. During an unresolved text merge, should HEAD move before a merge commit exists?
2. Which index stages should exist for the conflicted text file?
3. With rerere autoupdate disabled, does a remembered working-tree result mean the index is resolved?
4. Can a clean Git merge still violate a cross-field invariant?

3. Build and inspect the text conflict

mkdir git-merge-checkpoint
cd git-merge-checkpoint
git init -b trunk service
cd service
git config user.name "Merge Checkpoint"
git config user.email "merge-checkpoint@example.invalid"
git config merge.conflictStyle diff3
git config rerere.enabled true
git config rerere.autoUpdate false

printf "timeout_ms=100\nretries=2\n" > service.conf
git add service.conf
git commit -m "base"
BASE=$(git rev-parse HEAD)

git switch -c feature
printf "timeout_ms=900\nretries=2\n" > service.conf
git commit -am "feature timeout"

git switch trunk
printf "timeout_ms=250\nretries=2\n" > service.conf
git commit -am "operations timeout"
BEFORE=$(git rev-parse HEAD)

git merge-base trunk feature
git merge-tree --write-tree trunk feature
echo "preview exit=$?"

git merge --no-ff feature
echo "merge exit=$?"
test "$(git rev-parse HEAD)" = "$BEFORE"
git ls-files -u -- service.conf
git show :1:service.conf
git show :2:service.conf
git show :3:service.conf

4. Resolve from policy intent and validate

printf "timeout_ms=400\nretries=2\n" > service.conf
test "$(sed -n 's/^timeout_ms=//p' service.conf)" -le 500

git add service.conf
git ls-files -u -- service.conf
git rerere
git commit -m "merge feature: bounded timeout"
git show -s --format='%H %P %s' HEAD

The empty unmerged-stage output plus the explicit timeout test are both required evidence.

5. Reproduce the same conflict and verify rerere reuse

git switch -c repeat-trunk "$BASE"
printf "timeout_ms=250\nretries=2\n" > service.conf
git commit -am "repeat trunk"

git switch -c repeat-feature "$BASE"
printf "timeout_ms=900\nretries=2\n" > service.conf
git commit -am "repeat feature"

git switch repeat-trunk
git merge --no-ff repeat-feature || true

cat service.conf
git ls-files -u -- service.conf
grep -qx 'timeout_ms=400' <(head -n 1 service.conf)
test "$(sed -n 's/^timeout_ms=//p' service.conf)" -le 500

git add service.conf
git ls-files -u -- service.conf
git commit -m "merge repeat feature: validated rerere"

If your shell does not support process substitution (<(...)), use an ordinary grep or PowerShell string check instead. The key observation is that rerere can fill the remembered result while the index still reports conflict stages until you stage it.

6. Create and resolve a rename/delete migration

cd ..
git init -b trunk migration
cd migration
git config user.name "Merge Checkpoint"
git config user.email "merge-checkpoint@example.invalid"

printf "endpoint=v1\nprotocol=https\nregion=lab\nowner_team=platform\n" > legacy.env
git add legacy.env
git commit -m "base"

git switch -c migrate
git mv legacy.env current.env
printf "owner=platform\n" >> current.env
git add current.env
git commit -m "rename endpoint"

git switch trunk
git rm legacy.env
git commit -m "retire legacy endpoint"

git merge-tree --write-tree trunk migrate
echo "preview exit=$?"
git merge --no-ff migrate
echo "merge exit=$?"
git status --short
git ls-files -u

# Checkpoint decision: migration survives.
git rm --ignore-unmatch legacy.env
test -f current.env
git add current.env
git ls-files -u
grep -q '^endpoint=v1$' current.env
grep -q '^owner=platform$' current.env
git commit -m "merge migrate: retain renamed endpoint"

The decision is documented as an ownership/migration choice, not as “pick whichever side has fewer edits.”

7. Demonstrate a clean semantic conflict

cd ..
git init -b trunk capacity
cd capacity
git config user.name "Merge Checkpoint"
git config user.email "merge-checkpoint@example.invalid"

cat > capacity.conf <<'EOF'
min_nodes=2
queue_depth=100
batch_size=10
backoff_ms=50
health_window=30
max_nodes=8
EOF

cat > validate.sh <<'EOF'
#!/bin/sh
min=$(sed -n 's/^min_nodes=//p' capacity.conf)
max=$(sed -n 's/^max_nodes=//p' capacity.conf)
test "$min" -le "$max"
EOF

git add .
git commit -m "base capacity"

git switch -c resilience
sed -i 's/min_nodes=2/min_nodes=10/' capacity.conf
git commit -am "require ten nodes"

git switch trunk
sed -i 's/max_nodes=8/max_nodes=6/' capacity.conf
git commit -am "cap at six nodes"

git merge --no-ff resilience -m "merge resilience"
echo "Git merge exit=$?"
sh validate.sh
echo "domain validation exit=$?"

Git should merge cleanly; the independent invariant test should fail. Repair and revalidate:

sed -i 's/max_nodes=6/max_nodes=12/' capacity.conf
sh validate.sh
git add capacity.conf
git commit -m "fix integration capacity invariant"

8. Design a narrow custom-driver use case and fallback

For a generated file with the formal contract “unordered unique set of component IDs,” a deterministic set-union driver can be defensible. The design must:

• parse/validate base, ours, and theirs;
• produce deterministic sorted unique output;
• write the result to %A;
• return non-zero for unsupported schemas or malformed input;
• run the authoritative validator/generator afterward;
• fail closed if the driver is missing—never silently substitute ours.

9. Optional harmless POSIX driver lab

cd ..
git init -b trunk generated-driver
cd generated-driver
git config user.name "Merge Checkpoint"
git config user.email "merge-checkpoint@example.invalid"

mkdir -p generated .merge-drivers
printf "components=core\n" > generated/components.lock

cat > .merge-drivers/components.sh <<'EOF'
#!/bin/sh
ours=$2
theirs=$3
extract() {
  sed -n 's/^components=//p' "$1" | tr ',' '\n' | sed '/^$/d'
}
{ extract "$ours"; extract "$theirs"; } |
  sort -u | paste -sd, - | sed 's/^/components=/' > "$ours.tmp" || exit 2
grep -Eq '^components=[A-Za-z0-9_,-]+$' "$ours.tmp" || exit 1
mv "$ours.tmp" "$ours"
exit 0
EOF
chmod +x .merge-drivers/components.sh

printf "generated/components.lock merge=generatedComponents\n" > .gitattributes
git config merge.generatedComponents.name "generated component set union"
git config merge.generatedComponents.driver \
  'sh .merge-drivers/components.sh %O %A %B'

git add .
git commit -m "base generated set"

git switch -c api
printf "components=core,api\n" > generated/components.lock
git commit -am "api set"

git switch trunk
printf "components=core,worker\n" > generated/components.lock
git commit -am "worker set"

git merge --no-ff api -m "merge generated sets"
cat generated/components.lock
grep -qx 'components=api,core,worker' generated/components.lock

10. Prove the portability boundary

git check-attr merge -- generated/components.lock
git config --show-origin --get merge.generatedComponents.driver

A fresh clone gets the attribute and tracked script but not necessarily the local driver configuration. CI bootstrap must provision the reviewed command. If provisioning fails, regenerate or require explicit resolution.

11. Integration evidence memo

Text conflict
- merge base / tips:
- stage 1/2/3:
- chosen resolution:
- test result:
- rerere reused and independently validated?

Rename/delete
- source and renamed path:
- deleting-side intent:
- final ownership decision:
- verification:

Semantic conflict
- mechanical Git result:
- domain invariant:
- failing test:
- repaired result:

Custom driver
- exact file semantics:
- trusted runtime/config:
- success/failure contract:
- fallback if unavailable:

12. Verification checklist

• Text merge base/tips inspected before mutation.
• Stage 1/2/3 proven and HEAD stayed unchanged until commit.
• 400ms result tested before commit.
• Rerere reuse independently tested and explicitly staged.
• Rename/delete resolved from migration intent with no higher stages left.
• Semantic merge completed mechanically but failed the domain test, then was repaired.
• Custom driver design is deterministic, fail-closed, and runtime-provisioned.
• No ours shortcut was used merely to avoid a conflict.

13. Cleanup

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

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

14. Knowledge check

15. What Chapter 20 adds to a production Git operating model

You can now inspect merge-base inputs, preserve index-stage evidence, diagnose structural and semantic conflict types, abort/retry controlled integrations, validate every resolution, reuse rerere safely, and treat custom drivers as explicit executable infrastructure with fail-closed fallback.

16. Chapter checkpoint summary

Git answers how snapshots can be combined; production validation answers whether the combined behavior is acceptable. Reliable merging therefore joins graph mechanics, index evidence, domain tests, and controlled automation.

Authoritative references

• git-merge
• git-merge-tree
• git-rerere
• gitattributes
• merge-strategies