name: cleanup-worktree
description: This skill should be used when the user asks to "clean up worktree", "remove worktree", "delete branch after merge", "cleanup after PR merge", "remove merged branch", or needs to clean up a git worktree and its associated branch after a PR has been merged.
version: 1.0.0

Cleanup Worktree

Clean up a git worktree and its local branch after a PR has been merged. Handles Docker containers/volumes if they were used in the worktree.

Prerequisites

Before cleaning up, verify:
1. The PR has actually been merged (or the user confirms they want to clean up anyway)
2. There are no uncommitted changes in the worktree

Workflow

1. Confirm with user

Before doing anything destructive, confirm:
- Which worktree to clean up (current directory or specified path)
- That the PR has been merged or the user wants to proceed anyway

Check PR status if on a branch with an associated PR:

gh pr view --json state --jq '.state'

2. Check for uncommitted changes

git status --porcelain

If there are uncommitted changes, warn the user and ask how to proceed:
- Stash the changes
- Discard the changes
- Abort cleanup

3. Check for Docker usage

Check if Docker containers exist for this worktree. The project name is typically openemr-<dirname>:

dirname="${PWD##*/}"
project_name="openemr-${dirname}"
docker compose -p "$project_name" ps -q 2>/dev/null

Or check for a .env file with COMPOSE_PROJECT_NAME:

grep -s '^COMPOSE_PROJECT_NAME=' .env

If containers exist, they must be removed before the worktree can be deleted (mounted volumes prevent removal).

4. Clean up Docker (if applicable)

If Docker was used, stop and remove containers and volumes:

# Using compose files if they exist
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml down -v

# Or using project name directly
docker compose -p "$project_name" down -v

Confirm volumes were removed:

docker volume ls --filter "name=$project_name"

If volumes persist, remove them explicitly:

docker volume rm $(docker volume ls -q --filter "name=$project_name")

5. Get worktree and branch info

Before removing, capture the info needed:

# Get current worktree path
worktree_path="$(pwd)"

# Get branch name
branch_name="$(git branch --show-current)"

# Get the main worktree path (to run commands from after removal)
git worktree list --porcelain | grep -A1 'worktree.*main$' | head -1 | sed 's/worktree //'

6. Navigate out of the worktree

Change to a different worktree (typically main) before removing:

cd ../main

Or to the parent worktree directory.

7. Remove the worktree

Try graceful removal first:

git worktree remove "$worktree_path"

If that fails (e.g., untracked files), ask user if force removal is OK:

git worktree remove --force "$worktree_path"

8. Delete the local branch

Try safe deletion first (fails if not fully merged):

git branch -d "$branch_name"

If that fails and user confirms, force delete:

git branch -D "$branch_name"

9. Prune remote tracking branches (optional)

If the remote branch was also deleted:

git fetch --prune

Error Handling

"worktree is dirty"

Worktree has uncommitted changes. Options:
- git stash before removal
- git worktree remove --force to discard changes

"directory not empty" or "device or resource busy"

Usually means Docker volumes are still mounted. Ensure all containers are stopped and volumes removed:

docker compose -p "$project_name" down -v --remove-orphans

"branch not fully merged"

The branch wasn't merged to the base branch. Verify the PR was actually merged, then use -D to force delete if confirmed.

Notes

• Always confirm before destructive operations
• The main/ worktree should never be removed
• If cleanup fails partway through, report what was done and what remains
• After cleanup, user will be in the main worktree (or another specified worktree)