worktree-cleanup
Remove merged or stale git worktrees. Use after PRs are merged or when worktrees are no longer needed.
When & Why to Use This Skill
The Worktree Cleanup skill automates the removal of merged, stale, or redundant Git worktrees to maintain a clean and organized local development environment. By integrating safety checks for uncommitted changes and merge status, it helps developers reclaim disk space and streamline their post-PR workflow without the risk of data loss.
Use Cases
- Post-Merge Cleanup: Automatically removing local worktrees after a Pull Request has been successfully merged into the main branch to keep the workspace tidy.
- Disk Space Management: Identifying and deleting long-forgotten or stale worktrees that are consuming significant storage on the local machine.
- Workspace Organization: Maintaining a concise and relevant list of active worktrees to reduce cognitive load and prevent accidental commits to outdated branches.
- Environment Reset: Safely clearing out experimental worktrees once a task is completed or abandoned, ensuring the primary repository remains uncluttered.
| name | worktree-cleanup |
|---|---|
| description | "Remove merged or stale git worktrees. Use after PRs are merged, work is done, or when worktrees are no longer needed." |
| mcp_fallback | none |
| category | worktree |
Worktree Cleanup
Remove worktrees safely to free disk space and maintain organization.
When to Use
- PR has been merged
- Worktree no longer needed
- Free disk space
- Maintain clean worktree list
Quick Reference
# Remove single worktree by path
git worktree remove worktrees/ProjectOdyssey-42-feature
# Auto-clean all merged worktrees
./scripts/cleanup_merged_worktrees.sh
Workflow
- Verify state - Check no uncommitted changes:
cd worktrees/ProjectOdyssey-42 && git status - Commit changes - Make sure all changes are committed and the task is finished
- Switch away - Don't be in the worktree you're removing
- Remove worktree - Use git command
- Verify - Run
git worktree listto confirm removal
Safety Checks
Before removing a worktree:
- Branch is merged to main (check GitHub PR status)
- No uncommitted changes (run
git statusin worktree) - Not currently using the worktree (be in different directory)
- PR is actually merged (check "Development" section on issue)
Error Handling
| Error | Solution |
|---|---|
| "Worktree has uncommitted changes" | Commit changes |
| "Not a worktree" | Verify path with git worktree list |
| "Worktree is main" | Don't remove primary worktree |
Scripts Available
scripts/cleanup_merged_worktrees.sh- Auto-clean merged worktrees
References
- See
worktree-createskill for creating worktrees