nv-worktree-cleanup

Audits git worktrees and removes merged, missing, or confirmed stale entries with their branches.

39.7k|4.4k|Updated Aug 26, 2021
One-click install
npx skills add https://github.com/novuhq/novu --skill nv-worktree-cleanup
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: nv-worktree-cleanup
Source: https://github.com/novuhq/novu/tree/main/.cursor/skills/nv-worktree-cleanup
Command: npx skills add https://github.com/novuhq/novu --skill nv-worktree-cleanup

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Over time, developers accumulate stale git worktrees and their associated local branches, wasting disk space and cluttering the repository state. Manually checking which worktrees are merged, missing, or safe to delete is tedious and error-prone, especially with squash-merged branches that git cannot detect as merged.

Core Features & Use Cases

  • Worktree Classification: Enumerates all worktrees via git worktree list --porcelain and classifies each as merged-direct, merged-squash (via GitHub CLI PR lookup), dirty, unpushed, missing, or active.
  • Safe Deletion Workflow: Uses git branch -d by default, requires explicit user confirmation before any --force removal, and never deletes the main worktree or the worktree the agent is currently running in.
  • Batch Confirmation: Presents all removal candidates in a single multi-select approval step grouped by category, then executes removals, branch deletions, and git worktree prune.
  • Use Case: After finishing several feature branches, ask the agent to clean up worktrees; it fetches origin, identifies two merged worktrees and one missing directory, gets your approval, and removes them while flagging a dirty worktree you still need.

Quick Start

Ask the agent to clean up your git worktrees and remove any that have been merged or are no longer on disk.

Frequently Asked Questions about nv-worktree-cleanup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I clean up stale git worktrees safely?

Run git worktree list --porcelain to enumerate entries, classify each by merge status against origin's base branch, then remove confirmed entries with git worktree remove and delete their branches with git branch -d. Finish with git worktree prune to clear missing paths.

How to detect squash-merged branches before deleting worktrees?

Squash-merges leave branches unmerged in git topology, so merge-base checks fail. Use gh pr list --state merged --head <branch> with the GitHub CLI to confirm the branch's PR was merged before force-deleting with git branch -D.

Can git worktree remove delete a dirty worktree?

No, git worktree remove refuses on worktrees with uncommitted changes unless you pass --force. This skill flags dirty worktrees and only force-removes them after explicit user opt-in during the confirmation step.

Why does git branch -d fail after removing a worktree?

git branch -d refuses to delete branches that are not fully merged or still checked out. Remove the worktree first, and for squash-merged branches verify the merge via gh pr list, then use git branch -D with user confirmation.

What happens to worktrees whose directories were manually deleted?

Worktrees missing on disk are classified as missing and skipped during removal. Running git worktree prune at the end clears their stale administrative metadata from the repository.