Git Worktree Clean
Developmentgit-worktree-cleanGit Worktree Clean is an Agent Skill for development published in the FlorianBruniaux/claude-code-ultimate-guide repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Clean up stale git worktrees with merged branch detection and disk usage report
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/HEAD/examples/skills/git-worktree-clean/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/git-worktree-clean, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Git Worktree Clean
Batch cleanup of stale git worktrees. Safely removes merged branches, reports disk usage, and handles unmerged branches interactively.
Core principle: Auto-clean merged worktrees, interactive review for unmerged, always report what was reclaimed.
Part of: Worktree Lifecycle Suite | /git-worktree | /git-worktree-status | /git-worktree-remove
Process
- List All Worktrees:
git worktree list - Classify Each: merged vs unmerged vs protected
- Calculate Disk Usage: Per-worktree size
- Auto Mode: Remove all merged worktrees (safe)
- Interactive Mode: Review unmerged worktrees one by one
- Database Cleanup Reminder: List DB branches to clean
- Report: Summary of actions taken and space reclaimed
Flags
| Flag | Effect |
|---|---|
--dry-run | Preview what would be cleaned, no changes |
--all | Include unmerged worktrees (interactive confirmation each) |
--force | Remove all worktrees without confirmation (dangerous) |
Worktree Discovery
# Get main branch name
MAIN_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
MAIN_BRANCH=${MAIN_BRANCH:-main}
# Protected branches (never auto-clean)
PROTECTED="main master develop staging production"
# List all worktrees (skip main working tree)
git worktree list --porcelain | while read line; do
# Parse worktree path and branch
# Skip the main worktree (first entry)
done
Classification
for WORKTREE in $WORKTREES; do
BRANCH=$(git -C "$WORKTREE" rev-parse --abbrev-ref HEAD)
# Skip protected
if echo "$PROTECTED" | grep -qw "$BRANCH"; then
echo "PROTECTED: $BRANCH (skipped)"
continue
fi
# Check merge status
if git merge-base --is-ancestor "$BRANCH" "$MAIN_BRANCH" 2>/dev/null; then
echo "MERGED: $BRANCH → safe to remove"
MERGED_LIST="$MERGED_LIST $WORKTREE"
else
echo "UNMERGED: $BRANCH → requires review"
UNMERGED_LIST="$UNMERGED_LIST $WORKTREE"
fi
done
Disk Usage Calculation
for WORKTREE in $ALL_WORKTREES; do
# Calculate size excluding symlinked node_modules
SIZE=$(du -sh --exclude='node_modules' "$WORKTREE" 2>/dev/null | cut -f1)
# Or on macOS:
SIZE=$(du -sh -I 'node_modules' "$WORKTREE" 2>/dev/null | cut -f1)
echo " $WORKTREE: $SIZE"
done
Dry Run Mode
# --dry-run: show what would happen without making changes
echo "=== Dry Run ==="
echo ""
echo "Would remove (merged):"
for WT in $MERGED_LIST; do
echo " $WT ($BRANCH) - $SIZE"
done
echo ""
echo "Would ask about (unmerged):"
for WT in $UNMERGED_LIST; do
echo " $WT ($BRANCH) - $SIZE - last commit: $(git log -1 --format='%s' $BRANCH)"
done
echo ""
echo "Total space to reclaim: $TOTAL_SIZE"
echo ""
echo "Run without --dry-run to execute."
Auto Mode (Default)
Only removes merged worktrees. Safe by default.
echo "Cleaning merged worktrees..."
for WORKTREE in $MERGED_LIST; do
BRANCH=$(git -C "$WORKTREE" rev-parse --abbrev-ref HEAD)
# Remove worktree
git worktree remove "$WORKTREE"
# Delete local branch
git branch -d "$BRANCH" 2>/dev/null
# Delete remote branch
git push origin --delete "$BRANCH" 2>/dev/null
echo " Removed: $WORKTREE ($BRANCH)"
done
# Report unmerged (not touched)
if [ -n "$UNMERGED_LIST" ]; then
echo ""
echo "Unmerged worktrees (kept):"
for WT in $UNMERGED_LIST; do
echo " $WT - use /git-worktree-remove or --all to review"
done
fi
Interactive Mode (--all)
Reviews unmerged worktrees one by one:
for WORKTREE in $UNMERGED_LIST; do
BRANCH=$(git -C "$WORKTREE" rev-parse --abbrev-ref HEAD)
LAST_COMMIT=$(git log -1 --format='%h %s (%cr)' "$BRANCH")
AHEAD=$(git rev-list --count "$MAIN_BRANCH".."$BRANCH")
echo ""
echo "Unmerged: $WORKTREE"
echo " Branch: $BRANCH ($AHEAD commits ahead of $MAIN_BRANCH)"
echo " Last commit: $LAST_COMMIT"
echo " Size: $SIZE"
echo ""
echo " [r]emove [k]eep [s]kip remaining"
# Wait for user decision per worktree
done
Report Format
After cleanup:
=== Worktree Cleanup Report ===
Removed (merged):
.worktrees/feat/auth (feat/auth) - 2.3 MB
.worktrees/fix/login-bug (fix/login-bug) - 1.1 MB
.worktrees/chore/deps-update (chore/deps-update) - 0.8 MB
Kept (unmerged):
.worktrees/feat/experimental (feat/experimental) - 4.2 MB
Last commit: a1b2c3d "WIP: new auth flow" (3 days ago)
Kept (protected):
.worktrees/develop (develop)
Space reclaimed: 4.2 MB
Worktrees remaining: 2
References pruned: yes
DB branches to clean:
neonctl branches delete feat-auth
neonctl branches delete fix-login-bug
neonctl branches delete chore-deps-update
Dry run report:
=== Dry Run - No Changes Made ===
Would remove (3 merged):
.worktrees/feat/auth - 2.3 MB
.worktrees/fix/login-bug - 1.1 MB
.worktrees/chore/deps-update - 0.8 MB
Would keep (1 unmerged):
.worktrees/feat/experimental - 4.2 MB
Would keep (1 protected):
.worktrees/develop
Potential space savings: 4.2 MB
Quick Reference
| Situation | Action |
|---|---|
| Default (no flags) | Remove merged worktrees only |
--dry-run | Preview without changes |
--all | Merged (auto) + unmerged (interactive) |
--force | Remove everything except protected |
| Protected branch | Always kept |
| Merged branch | Auto-removed |
| Unmerged branch | Kept (default) or interactive (--all) |
| DB branches detected | Reminder with exact commands |
Common Mistakes
Running --force without --dry-run first
- Always preview with
--dry-runbefore force-cleaning
Forgetting DB branch cleanup
- Worktree cleanup doesn't auto-delete DB branches. Follow the reminder commands.
Not running cleanup regularly
- Stale worktrees accumulate disk space. Run
/git-worktree-clean --dry-runweekly.
Usage
/git-worktree-clean
/git-worktree-clean --dry-run
/git-worktree-clean --all
Flags: $ARGUMENTS