Git worktrees - Lesson 4 of 5
Clean up through Git, recover through Git
A worktree has filesystem state and Git metadata. Let Git remove and move it when possible; when a path has already changed, diagnose whether you need prune, repair, or a lock.
The normal closeout
cd ../repo-readme-refresh
git status --short
git log --oneline main..HEAD
cd ../repo
git worktree remove ../repo-readme-refresh
git branch -d docs/readme-refresh
git worktree list --verboseRemoval should be boring: no uncommitted work and no unintegrated commits you intend to keep. Git refuses to remove an unclean worktree by default. Treat that refusal as evidence to inspect, not as an invitation to add --force.
Match the problem to the repair
| Situation | First command | Purpose |
|---|---|---|
| Path was moved intentionally | git worktree move <old> <new> | Move directory and metadata together. |
| Path was moved by hand | git worktree repair <new-path> | Reconnect Git metadata to its actual location. |
| Path was deleted by hand | git worktree prune --dry-run | Preview stale metadata removal. |
| Path lives on removable storage | git worktree lock --reason "external disk" <path> | Prevent automatic pruning while unavailable. |
| Per-worktree tool settings are needed | git config --worktree ... | Use after enabling worktree-specific configuration. |
Recovery sequence
Stopdo not force yetListread verbose stateLocatepath moved or missingRepairreconnect a moved treePreviewdry-run stale cleanupPruneonly after review
git worktree list --verbose
git worktree repair ../repo-moved
git worktree prune --dry-run
git worktree prunerepair reconnects a worktree that still exists at a new path. prune removes stale records for a path that is missing. Those are different problems.
Retrieval check
Primary reading
- git-worktree - read
move,prune,remove,repair,lock, and Configuration.
Ask follow-up questions: If a worktree has disappeared or reports as prunable, share the output of
git worktree list --verbose before doing cleanup.