Checkpoint Lab — Stash, Worktrees, Temporary Work, and Parallel Development Contexts

1. Checkpoint scenario — feature work is interrupted by an urgent hotfix

You are developing feature/metrics. The work is incomplete, includes an untracked design note, and is not ready for review. An urgent configuration hotfix arrives. You will apply a decision rule, park the feature safely, create a second worktree for the hotfix, integrate it into trunk, restore the feature, then prove there is no hidden stash or stale worktree state.

2. Decision rule before touching Git state

3. Setup and preflight

Git Bash, Bash, or zsh

mkdir git-context-checkpoint
cd git-context-checkpoint
git init -b trunk main
cd main
git config user.name "Context Checkpoint"
git config user.email "context-checkpoint@example.invalid"

printf "metrics=false\n" > service.conf
printf "timeout=5\n" > timeout.conf
printf "# Context Checkpoint\n" > README.md
git add service.conf timeout.conf README.md
git commit -m "Create checkpoint baseline"

git rev-parse --show-toplevel
git status --short --branch
git stash list
git worktree list --porcelain

PowerShell setup alternative

New-Item -ItemType Directory git-context-checkpoint | Out-Null
Set-Location git-context-checkpoint
git init -b trunk main
Set-Location main
git config user.name "Context Checkpoint"
git config user.email "context-checkpoint@example.invalid"

Set-Content service.conf 'metrics=false'
Set-Content timeout.conf 'timeout=5'
Set-Content README.md '# Context Checkpoint'
git add service.conf timeout.conf README.md
git commit -m "Create checkpoint baseline"

git rev-parse --show-toplevel
git status --short --branch
git stash list
git worktree list --porcelain

4. Start unfinished feature work

git switch -c feature/metrics

# Change metrics=false to metrics=true in service.conf.
printf "metrics design: add labels after prototype\n" > feature-notes.txt

git status --short
git diff -- service.conf
FEATURE_BASE=$(git rev-parse HEAD)

The feature has one tracked edit and one untracked note. Neither is ready for a durable team commit yet.

5. Prediction 1 — what should the stash change?

Before running the command, predict:

• feature/metrics branch OID should not move.
• The tracked edit and untracked note should become clean/absent from the working directory because -u includes the note.
• refs/stash should appear and name a new stash commit.

git stash push -u -m "feature/metrics | urgent timeout hotfix interruption"
FEATURE_STASH=$(git rev-parse stash@{0})

git rev-parse feature/metrics
git status --short
git stash list
git stash show -u --stat stash@{0}

Verify that feature/metrics still equals FEATURE_BASE while the temporary changes are represented by FEATURE_STASH.

6. Switch main to trunk and add an urgent hotfix worktree

git switch trunk
git worktree add -b hotfix/timeout ../hotfix-wt trunk

git worktree list --porcelain
git branch -vv
git -C ../hotfix-wt status --short --branch

The main directory owns trunk; the linked directory owns hotfix/timeout. Both start from the same baseline commit, but their indexes and working directories are separate.

7. Implement and verify the hotfix in the linked worktree

git -C ../hotfix-wt config user.name "Hotfix Engineer"
git -C ../hotfix-wt config user.email "hotfix@example.invalid"

# In ../hotfix-wt/timeout.conf, change timeout=5 to timeout=10.
git -C ../hotfix-wt status --short
git -C ../hotfix-wt diff -- timeout.conf
git -C ../hotfix-wt add timeout.conf
git -C ../hotfix-wt diff --staged -- timeout.conf
git -C ../hotfix-wt commit -m "Increase timeout for slow requests"
HOTFIX_OID=$(git -C ../hotfix-wt rev-parse HEAD)

git show --stat --oneline "$HOTFIX_OID"

8. Prediction 2 — integrate without checking out the hotfix branch in main

Because trunk has not moved since hotfix/timeout branched, predict that git merge --ff-only hotfix/timeout will fast-forward trunk to HOTFIX_OID and create no merge commit.

git status --short --branch
git merge-base --is-ancestor trunk hotfix/timeout
git merge --ff-only hotfix/timeout

TRUNK_AFTER_HOTFIX=$(git rev-parse trunk)
git rev-parse hotfix/timeout
git log --graph --decorate --oneline --all --max-count=10

Verify that TRUNK_AFTER_HOTFIX equals HOTFIX_OID.

9. Remove the completed hotfix worktree and merged branch

git -C ../hotfix-wt status --short
git worktree remove ../hotfix-wt
git worktree list --porcelain

git branch -d hotfix/timeout
git branch -vv

The worktree is clean, so normal removal succeeds. The branch is fully merged into trunk, so safe -d deletion succeeds without force.

10. Return to the feature and inspect before popping

git switch feature/metrics

git status --short --branch
git stash list
git rev-parse stash@{0}
git stash show -u -p stash@{0}

Do not pop by reflex. Confirm that the message/OID matches the feature interruption and that the paths are the ones you expect.

git stash pop stash@{0}
git status --short
git diff -- service.conf
cat feature-notes.txt
git stash list

Because the feature branch itself did not move, the stash should apply cleanly and be removed from the normal stash list.

11. Promote restored feature work to durable history

The interruption is over, so finish the feature to a coherent checkpoint rather than immediately creating another long-lived stash:

git add service.conf feature-notes.txt
git diff --staged
git commit -m "Prototype metrics collection"
FEATURE_OID=$(git rev-parse HEAD)

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

12. Preserve a compact context-switch evidence report

printf "feature_base=%s\n" "$FEATURE_BASE"
printf "feature_stash=%s\n" "$FEATURE_STASH"
printf "hotfix_commit=%s\n" "$HOTFIX_OID"
printf "trunk_after_hotfix=%s\n" "$TRUNK_AFTER_HOTFIX"
printf "feature_final=%s\n" "$FEATURE_OID"

git show --no-patch --format='%H %P %s' "$HOTFIX_OID"
git show --no-patch --format='%H %P %s' "$FEATURE_OID"

13. Prove no work is hidden

git status --short --branch
git stash list
git worktree list --porcelain
git branch -vv
git worktree prune --dry-run

The target final state is: feature work committed and clean, stash list empty, only the main worktree registered, no stale worktree metadata, and hotfix content preserved in trunk history.

14. Verification checklist

• The feature branch OID did not move when the stash was created.
• The named stash included both tracked feature work and the untracked design note.
• The hotfix worktree had its own branch, index, and working directory while sharing repository history.
• The hotfix commit was inspected before integration.
• Trunk fast-forwarded to the hotfix OID with no extra merge commit.
• The clean hotfix worktree was removed with git worktree remove, not manual deletion.
• The merged hotfix branch was deleted safely with -d.
• The correct stash was inspected before pop and disappeared only after successful application.
• Restored feature work was promoted to a durable commit.
• Final stash list and prune dry-run report no hidden/stale work.

15. Cleanup

Git Bash / Bash / zsh

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

PowerShell

Set-Location ../..
Get-Location
Remove-Item -Recurse -Force git-context-checkpoint

16. Knowledge check

17. What Chapter 12 adds to a production Git operating model

You can now interrupt work without panic-driven branch switching: short-lived private state can be stashed deliberately; parallel feature/review/hotfix work can use linked worktrees; durable work is promoted to commits; and operational tooling can verify the exact path/branch/OID before acting.

18. Chapter checkpoint summary

The discipline is simple: temporary state should be named and short-lived, parallel contexts should be discoverable, and anything important should end up in durable history. A clean stash list and accurate worktree list are part of finishing the task.

Authoritative references

• git-stash
• git-worktree
• git-merge