sttts avatar

sttts-worktree

Git worktree management for Claude Code

version
0.2.10
GitHub stars
6

Install

/plugin install sttts-worktree@sttts-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add sttts/skills.

Contents

Discovered from source

Skills 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:

  1. Get the path and branch from git worktree list
  2. 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>
  3. 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:
    git -C <worktree-path> status --porcelain
    
    If output is non-empty, warn user about uncommitted changes
  • 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 .git objects - 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

More from sttts/skills

All 7