
sttts-worktree
Git worktree management for Claude Code
- version
- 0.2.10
- GitHub stars
- 6
Install
/plugin install sttts-worktree@sttts-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add sttts/skills.
Contents
Discovered from sourceSkills 3
Prune Worktrees
Clean up worktrees whose branches have been merged on GitLab or GitHub.
On Skill Load
Run the cleanup check automatically:
# 1. Detect remote type (GitLab or GitHub)
REMOTE_URL=$(git remote get-url origin)
if [[ "$REMOTE_URL" == *"gitlab"* ]]; then
CLI="glab"
elif [[ "$REMOTE_URL" == *"github"* ]]; then
CLI="gh"
else
echo "Unknown remote type: $REMOTE_URL"
exit 1
fi
# 2. List all worktrees (not just .git/checkouts/)
git worktree list
Detection Logic
Use git worktree list to find all worktrees regardless of location. Skip the main worktree (first entry).
For each non-main worktree:
- Get the path and branch from
git worktree list - Check if a merged MR/PR exists for that branch:
- GitLab:
glab mr list --merged --source-branch <branch> - GitHub:
gh pr list --state merged --head <branch>
- GitLab:
- If merged, mark for cleanup
Also check the current worktree - if we're on a branch that's been merged, flag it.
Output Format
Present findings to user:
Worktree Cleanup Check
======================
Merged (safe to remove):
/path/to/feature-123 (branch: feature-123, MR !45 merged)
/path/to/fix-bug (branch: fix-bug, PR #67 merged)
Not merged (keep):
/path/to/wip-stuff (branch: wip-stuff, no merged MR/PR)
Dirty (has uncommitted changes):
/path/to/dirty-one (branch: dirty-one, has uncommitted changes)
Cleanup Commands
After user confirms, remove merged worktrees:
# For each confirmed worktree
git worktree remove <path>
# Prune stale worktree references
git worktree prune
# Optionally delete the remote branch if still exists
git push origin --delete <branch>
Safety Rules
- NEVER auto-delete - always show list and ask for confirmation
- NEVER delete worktrees with uncommitted changes without warning
- Check for uncommitted changes before removing:
If output is non-empty, warn user about uncommitted changesgit -C <worktree-path> status --porcelain - Skip the main worktree - never offer to remove the primary checkout
Script
#!/bin/bash
set -euo pipefail
REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
# Detect CLI
if [[ "$REMOTE_URL" == *"gitlab"* ]]; then
CLI="glab"
elif [[ "$REMOTE_URL" == *"github"* ]]; then
CLI="gh"
else
echo "Error: Cannot detect GitLab or GitHub from remote: $REMOTE_URL"
exit 1
fi
echo "Checking worktrees for merged branches..."
echo
MERGED=()
UNMERGED=()
DIRTY=()
FIRST=true
# Parse git worktree list output: <path> <sha> [<branch>]
git worktree list | while read -r wt_path wt_sha wt_branch_raw; do
# Skip main worktree (first entry)
if $FIRST; then
FIRST=false
continue
fi
# Extract branch name from [branch] format
branch="${wt_branch_raw#[}"
branch="${branch%]}"
# Skip detached HEAD
if [[ "$branch" == "(detached" || -z "$branch" ]]; then
UNMERGED+=("$wt_path (detached HEAD)")
continue
fi
# Check for uncommitted changes
if [[ -n $(git -C "$wt_path" status --porcelain 2>/dev/null) ]]; then
DIRTY+=("$wt_path ($branch) - has uncommitted changes")
continue
fi
# Check if branch has merged MR/PR
if [[ "$CLI" == "glab" ]]; then
merged=$($CLI mr list --merged --source-branch "$branch" 2>/dev/null | head -1)
else
merged=$($CLI pr list --state merged --head "$branch" 2>/dev/null | head -1)
fi
if [[ -n "$merged" ]]; then
MERGED+=("$wt_path ($branch) - $merged")
else
UNMERGED+=("$wt_path ($branch)")
fi
done
if [[ ${#MERGED[@]} -gt 0 ]]; then
echo "MERGED (safe to remove):"
for item in "${MERGED[@]}"; do
echo " $item"
done
echo
fi
if [[ ${#DIRTY[@]} -gt 0 ]]; then
echo "DIRTY (has uncommitted changes - review first):"
for item in "${DIRTY[@]}"; do
echo " $item"
done
echo
fi
if [[ ${#UNMERGED[@]} -gt 0 ]]; then
echo "NOT MERGED (keep):"
for item in "${UNMERGED[@]}"; do
echo " $item"
done
echo
fi
if [[ ${#MERGED[@]} -eq 0 ]]; then
echo "No merged worktrees to clean up."
fi
Run this script, then ask the user which worktrees to remove.
Worktree Workflow
Opinionated workflow for git worktrees using .git/checkouts/ convention.
This skill must be explicitly loaded - it does not auto-trigger.
Convention
All worktrees are created in .git/checkouts/:
git worktree add .git/checkouts/<branch> -b <branch>
cd .git/checkouts/<branch>
Benefits:
- Keeps worktrees organized in one place
- Hidden from IDE file explorers (inside .git)
- Easy to find and clean up
Rules
When this workflow is active:
- Create worktrees in
.git/checkouts/- consistent location - Stay in the worktree - don't cd back to main checkout
- Don't touch main - work only on feature branch
- Don't delete before merge - confirm MR/PR is merged first
- Don't mark task complete before merge - merging happens after push
Setup
Enable for a repo:
git config --local claude.worktrees true
mkdir -p .git/checkouts
Disable:
git config --local --unset claude.worktrees
Creating a Worktree
git worktree add .git/checkouts/<branch> -b <branch>
cd .git/checkouts/<branch>
# All work happens here
Cleanup
Use /prune-worktrees to check for merged branches and clean up.
Manual cleanup:
git worktree remove .git/checkouts/<branch>
git worktree prune
Git Worktrees
Git worktrees allow working on multiple branches simultaneously in separate directories.
Commands
Create a worktree
# Create worktree with new branch
git worktree add <path> -b <new-branch>
# Create worktree for existing branch
git worktree add <path> <existing-branch>
List worktrees
git worktree list
Remove a worktree
# Remove worktree (directory must be clean)
git worktree remove <path>
# Force remove (even if dirty)
git worktree remove --force <path>
Prune stale references
git worktree prune
Common Patterns
Feature branch worktree
git worktree add ../feature-123 -b feature-123
cd ../feature-123
# work on feature
Hotfix while preserving current work
git worktree add ../hotfix -b hotfix/urgent-fix origin/main
cd ../hotfix
# fix the issue
git push
cd -
git worktree remove ../hotfix
Review a PR/MR locally
git worktree add ../review-pr-456 origin/feature-branch
cd ../review-pr-456
# review code
cd -
git worktree remove ../review-pr-456
Tips
- Each worktree has its own working directory and index
- You cannot have the same branch checked out in multiple worktrees
- Worktrees share the same
.gitobjects - efficient disk usage - Use
git worktree lock <path>to prevent accidental removal
Sponsors
Details
- Marketplace
- sttts/skills
- Source
- plugins/worktree
- Author
- Stefan Schimanski
- Category
- Productivity