git-cleanup

Git Cleanup

Safely clean up accumulated git worktrees and local branches by categorizing them into: safely deletable (merged), potentially related (similar themes), and active work (keep).

When to Use

When the user has accumulated many local branches and worktrees
When branches have been merged but not cleaned up locally
When remote branches have been deleted but local tracking branches remain

When NOT to Use

Do not use for remote branch management (this is local cleanup only)
Do not use for repository maintenance tasks like gc or prune
Not designed for headless or non-interactive automation (requires user confirmations at two gates)

Core Principle: SAFETY FIRST

Never delete anything without explicit user confirmation. This skill uses a gated workflow where users must approve each step before any destructive action.

Critical Implementation Notes

Squash-Merged Branches Require Force Delete

IMPORTANT: git branch -d will ALWAYS fail for squash-merged branches because git cannot detect that the work was incorporated. This is expected behavior, not an error.

When you identify a branch as squash-merged:

Plan to use git branch -D (force delete) from the start
Do NOT try git branch -d first and then ask again for -D - this wastes user confirmations
In the confirmation step, show git branch -D for squash-merged branches

MANDATORY: Before categorizing individual branches, group them by name prefix:

# Extract common prefixes from branch names
# e.g., feature/auth-*, feature/api-*, fix/login-*

Branches sharing a prefix (e.g., feature/api, feature/api-v2, feature/api-refactor) are almost certainly related iterations. Analyze them as a group:

Find the oldest and newest by commit date
Check if newer branches contain commits from older ones
Check which PRs merged work from each
Determine if older branches are superseded

Present related branches together with a clear recommendation, not scattered across categories.

Thorough PR History Investigation

Don't rely on simple keyword matching. For [gone] branches:

# 1. Get the branch's commits that aren't in default branch
git log --oneline "$default_branch".."

Workflow

Phase 1: Comprehensive Analysis

Gather ALL information upfront before any categorization:

Note on branch names: Git branch names can contain characters that break shell expansion. Always quote "$branch" in commands.

Do this BEFORE individual categorization.

Identify branch groups by shared prefixes:

For each group with 2+ branches:

Compare commit histories - Which branches contain commits from others?
Find merge evidence - Which PRs incorporated work from this group?
Identify the "final" branch - Usually the most recent or most complete
Mark superseded branches - Older iterations whose work is in main or in a newer branch

SUPERSEDED requires evidence, not just shared prefix:

A PR merged the work into main, OR
A newer branch contains all commits from the older branch
Name prefix alone is NOT sufficient — similarly named branches may contain independent work

Example analysis for feature/api-* branches:

Phase 3: Categorize Remaining Branches

For branches NOT in a related group, categorize individually:

Category definitions:

Category	Meaning	Delete Command
SAFE_TO_DELETE	Merged into default branch	`git branch -d`
SQUASH_MERGED	Work incorporated via squash merge	`git branch -D`
SUPERSEDED	Part of a group, work verified in main via PR or in newer branch	`git branch -D`
REMOTE_GONE	Remote deleted, work NOT found in main	Review needed
UNPUSHED_WORK	Has commits not pushed to remote	Keep
LOCAL_WORK	Untracked branch with unique commits	Keep
SYNCED_WITH_REMOTE	Up to date with remote	Keep

Phase 4: Dirty State Detection

Check ALL worktrees and current directory for uncommitted changes:

Display warnings prominently:

GATE 1: Present Complete Analysis

Present everything in ONE comprehensive view. Group related branches together:

Use AskUserQuestion with clear options:

Delete all recommended (groups + merged + squash-merged)
Delete specific groups/categories
Let me pick individual branches

Do not proceed until user responds.

GATE 2: Final Confirmation with Exact Commands

Show the EXACT commands that will run, with correct flags:

IMPORTANT: This is the ONLY confirmation needed for deletion. Do not add extra confirmations if -D is required.

Phase 5: Execute

Run each deletion as a separate command so partial failures don't block remaining deletions. Report the result of each:

If a deletion fails, report the error and continue with remaining deletions.

Phase 6: Report

Safety Rules

Never invoke automatically - Only run when user explicitly uses /git-cleanup
Two confirmation gates only - Analysis review, then deletion confirmation
Use correct delete command - -d for merged, -D for squash-merged/superseded
Never touch protected branches - main, master, develop, release/* (filtered programmatically)
Block dirty worktree removal - Refuse without explicit data loss acknowledgment
Group related branches - Don't scatter them across categories

Rationalizations to Reject

These are common shortcuts that lead to data loss. Reject them:

Rationalization	Why It's Wrong
"The branch is old, it's probably safe to delete"	Age doesn't indicate merge status. Old branches may contain unmerged work.
"I can recover from reflog if needed"	Reflog entries expire. Users often don't know how to use reflog. Don't rely on it as a safety net.
"It's just a local branch, nothing important"	Local branches may contain the only copy of work not pushed anywhere.
"The PR was merged, so the branch is safe"	Squash merges don't preserve branch history. Verify the specific commits were incorporated.
"I'll just delete all the `[gone]` branches"	`[gone]` only means the remote was deleted. The local branch may have unpushed commits.
"The user seems to want everything deleted"	Always present analysis first. Let the user choose what to delete.
"The branch has commits not in main, so it has unpushed work"	"Not in main" ≠ "not pushed". A branch can be synced with its remote but not merged to main. Always check `git log origin/<branch>..<branch>`.

Git Cleanup

Safely clean up accumulated git worktrees and local branches by categorizing them into: safely deletable (merged), potentially related (similar themes), and active work (keep).

When to Use

When the user has accumulated many local branches and worktrees
When branches have been merged but not cleaned up locally
When remote branches have been deleted but local tracking branches remain

When NOT to Use

Do not use for remote branch management (this is local cleanup only)
Do not use for repository maintenance tasks like gc or prune
Not designed for headless or non-interactive automation (requires user confirmations at two gates)

Core Principle: SAFETY FIRST

Never delete anything without explicit user confirmation. This skill uses a gated workflow where users must approve each step before any destructive action.

Critical Implementation Notes

Squash-Merged Branches Require Force Delete

IMPORTANT: git branch -d will ALWAYS fail for squash-merged branches because git cannot detect that the work was incorporated. This is expected behavior, not an error.

When you identify a branch as squash-merged:

Plan to use git branch -D (force delete) from the start
Do NOT try git branch -d first and then ask again for -D - this wastes user confirmations
In the confirmation step, show git branch -D for squash-merged branches

MANDATORY: Before categorizing individual branches, group them by name prefix:

# Extract common prefixes from branch names
# e.g., feature/auth-*, feature/api-*, fix/login-*

Branches sharing a prefix (e.g., feature/api, feature/api-v2, feature/api-refactor) are almost certainly related iterations. Analyze them as a group:

Find the oldest and newest by commit date
Check if newer branches contain commits from older ones
Check which PRs merged work from each
Determine if older branches are superseded

Present related branches together with a clear recommendation, not scattered across categories.

Thorough PR History Investigation

Don't rely on simple keyword matching. For [gone] branches:

# 1. Get the branch's commits that aren't in default branch
git log --oneline "$default_branch".."

Workflow

Phase 1: Comprehensive Analysis

Gather ALL information upfront before any categorization:

Note on branch names: Git branch names can contain characters that break shell expansion. Always quote "$branch" in commands.

Do this BEFORE individual categorization.

Identify branch groups by shared prefixes:

For each group with 2+ branches:

Compare commit histories - Which branches contain commits from others?
Find merge evidence - Which PRs incorporated work from this group?
Identify the "final" branch - Usually the most recent or most complete
Mark superseded branches - Older iterations whose work is in main or in a newer branch

SUPERSEDED requires evidence, not just shared prefix:

A PR merged the work into main, OR
A newer branch contains all commits from the older branch
Name prefix alone is NOT sufficient — similarly named branches may contain independent work

Example analysis for feature/api-* branches:

Phase 3: Categorize Remaining Branches

For branches NOT in a related group, categorize individually:

Category definitions:

Category	Meaning	Delete Command
SAFE_TO_DELETE	Merged into default branch	`git branch -d`
SQUASH_MERGED	Work incorporated via squash merge	`git branch -D`
SUPERSEDED	Part of a group, work verified in main via PR or in newer branch	`git branch -D`
REMOTE_GONE	Remote deleted, work NOT found in main	Review needed
UNPUSHED_WORK	Has commits not pushed to remote	Keep
LOCAL_WORK	Untracked branch with unique commits	Keep
SYNCED_WITH_REMOTE	Up to date with remote	Keep

Phase 4: Dirty State Detection

Check ALL worktrees and current directory for uncommitted changes:

Display warnings prominently:

GATE 1: Present Complete Analysis

Present everything in ONE comprehensive view. Group related branches together:

Use AskUserQuestion with clear options:

Delete all recommended (groups + merged + squash-merged)
Delete specific groups/categories
Let me pick individual branches

Do not proceed until user responds.

GATE 2: Final Confirmation with Exact Commands

Show the EXACT commands that will run, with correct flags:

IMPORTANT: This is the ONLY confirmation needed for deletion. Do not add extra confirmations if -D is required.

Phase 5: Execute

Run each deletion as a separate command so partial failures don't block remaining deletions. Report the result of each:

If a deletion fails, report the error and continue with remaining deletions.

Phase 6: Report

Safety Rules

Never invoke automatically - Only run when user explicitly uses /git-cleanup
Two confirmation gates only - Analysis review, then deletion confirmation
Use correct delete command - -d for merged, -D for squash-merged/superseded
Never touch protected branches - main, master, develop, release/* (filtered programmatically)
Block dirty worktree removal - Refuse without explicit data loss acknowledgment
Group related branches - Don't scatter them across categories

Rationalizations to Reject

These are common shortcuts that lead to data loss. Reject them:

Rationalization	Why It's Wrong
"The branch is old, it's probably safe to delete"	Age doesn't indicate merge status. Old branches may contain unmerged work.
"I can recover from reflog if needed"	Reflog entries expire. Users often don't know how to use reflog. Don't rely on it as a safety net.
"It's just a local branch, nothing important"	Local branches may contain the only copy of work not pushed anywhere.
"The PR was merged, so the branch is safe"	Squash merges don't preserve branch history. Verify the specific commits were incorporated.
"I'll just delete all the `[gone]` branches"	`[gone]` only means the remote was deleted. The local branch may have unpushed commits.
"The user seems to want everything deleted"	Always present analysis first. Let the user choose what to delete.
"The branch has commits not in main, so it has unpushed work"	"Not in main" ≠ "not pushed". A branch can be synced with its remote but not merged to main. Always check `git log origin/<branch>..<branch>`.

Documentation

Documentation

Git Cleanup

When to Use

When NOT to Use

Core Principle: SAFETY FIRST

Critical Implementation Notes

Squash-Merged Branches Require Force Delete

Thorough PR History Investigation

Workflow

Phase 1: Comprehensive Analysis

Phase 3: Categorize Remaining Branches

Phase 4: Dirty State Detection

GATE 1: Present Complete Analysis

GATE 2: Final Confirmation with Exact Commands

Phase 5: Execute

Phase 6: Report

Safety Rules

Rationalizations to Reject

Documentation

git-cleanup

Documentation

Git Cleanup

When to Use

When NOT to Use

Core Principle: SAFETY FIRST

Critical Implementation Notes

Squash-Merged Branches Require Force Delete

Thorough PR History Investigation

Workflow

Phase 1: Comprehensive Analysis

Phase 3: Categorize Remaining Branches

Phase 4: Dirty State Detection

GATE 1: Present Complete Analysis

GATE 2: Final Confirmation with Exact Commands

Phase 5: Execute

Phase 6: Report

Safety Rules

Rationalizations to Reject

git-cleanup

Documentation

Documentation

Git Cleanup

When to Use

When NOT to Use

Core Principle: SAFETY FIRST

Critical Implementation Notes

Squash-Merged Branches Require Force Delete

Group Related Branches BEFORE Categorization

Thorough PR History Investigation

Workflow

Phase 1: Comprehensive Analysis

Phase 2: Group Related Branches

Phase 3: Categorize Remaining Branches

Phase 4: Dirty State Detection

GATE 1: Present Complete Analysis

GATE 2: Final Confirmation with Exact Commands

Phase 5: Execute

Phase 6: Report

Safety Rules

Rationalizations to Reject

Documentation

git-cleanup

Documentation

Git Cleanup

When to Use

When NOT to Use

Core Principle: SAFETY FIRST

Critical Implementation Notes

Squash-Merged Branches Require Force Delete

Group Related Branches BEFORE Categorization

Thorough PR History Investigation

Workflow

Phase 1: Comprehensive Analysis

Phase 2: Group Related Branches

Phase 3: Categorize Remaining Branches

Phase 4: Dirty State Detection

GATE 1: Present Complete Analysis

GATE 2: Final Confirmation with Exact Commands

Phase 5: Execute

Phase 6: Report

Safety Rules

Rationalizations to Reject