cleanup-git-worktrees

Audits and safely removes stale Git worktrees and merged local branches.

Updated Jan 27, 2026
One-click install
npx skills add https://github.com/SmallAi-API/smaihub --skill cleanup-git-worktrees-smallai-api
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: cleanup-git-worktrees
Source: https://github.com/SmallAi-API/smaihub/tree/main/.agents/skills/cleanup-git-worktrees
Command: npx skills add https://github.com/SmallAi-API/smaihub --skill cleanup-git-worktrees-smallai-api

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Repositories accumulate stale Git worktrees and local branches over time, and deleting them by hand risks losing dirty work, unpushed commits, or branches whose squash-merged PRs leave no ancestry trail. This Skill classifies every worktree and branch deterministically so only verified-safe targets are removed. ## Core Features & Use Cases - Deterministic audit: Classifies each worktree and branch as protected, deletable (candidate-merged, candidate-pr-merged, candidate-gone, candidate-stale), or needing review, using merge ancestry, GitHub PR state via the gh CLI, upstream tracking, age, and unpushed-commit counts. - Guarded cleanup: Re-classifies every target immediately before deletion, refuses anything not marked as a candidate, runs as a dry run unless --apply is passed, and never deletes dirty worktrees or branches with unpushed commits. - Broken registration handling: Detects prunable worktree registrations, distinguishes them from leftover directories, and reports them safely instead of crashing. - Use Case: After weeks of parallel feature work, run the audit to get one table grouping deletable, review-needed, and protected worktrees, then approve a single batch cleanup that removes merged branches while preserving anything with uncommitted or unpushed work. ## Quick Start Ask the assistant to audit all Git worktrees and stale branches in this repository and remove the ones that are safely merged or inactive.

Frequently Asked Questions about cleanup-git-worktrees

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

FAQPage Schema
How do I safely delete stale Git worktrees and branches?

Run the audit command to classify every worktree and branch, review the grouped table of deletable versus protected targets, then run the clean command with explicit branch names and --apply. The script re-verifies each target before deleting and refuses anything not classified as a candidate.

How to tell if a Git branch was merged after a squash merge?

Squash merges leave no ancestry, so git merge-base reports not merged. Use the gh CLI to check that the PR state is MERGED and the local tip equals the PR head SHA, or search the base branch log for each extra commit's subject.

Does the cleanup script delete branches with unpushed commits?

No. Any branch with unpushed commits is classified as review-gone-unpushed or otherwise protected, and the clean command refuses to delete it. Zero unpushed commits means every local commit is reachable from a remote ref, so deletion loses nothing.

What happens to dirty worktrees during cleanup?

Dirty worktrees are classified as protect-dirty and are never deleted. Untracked paths matching the noise regex, such as node_modules, do not count as dirt and are removed together with the worktree using git worktree remove --force.

Why does git worktree list show prunable entries?

A prunable entry means the worktree registration points to a gitdir that no longer exists, usually after a partial removal. Running git worktree prune drops only the registration; any leftover directory must be inspected and removed manually after user approval.

Is the cleanup command a dry run by default?

Yes. Without the --apply flag, the clean command only prints what would be removed. Even with --apply, it re-classifies each target immediately before deletion and aborts on anything that is not a verified candidate.