git-worktree-master_skill

This skill helps you diagnose and repair complex git worktree issues, reclaim orphaned or locked worktrees, and maintain a clean multi-worktree workflow.

HTML

4

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill shakes-tzd/contextune --skill git-worktree-master

SKILL.md14.0 KB

Overview

This skill provides expert git worktree troubleshooting, cleanup, and management. It diagnoses stuck or locked worktrees, orphaned registrations, directory/branch mismatches, and performance issues from many worktrees. It offers safe remediation steps, prevention guidance, and optional automation scripts for recurring cleanup.

How this skill works

I start with diagnostics: list worktrees, detect lock files, check registrations, disk usage, and running git processes. Based on findings I present a clear summary of issues and propose conservative fixes (remove locks, prune stale entries, remove or recreate worktrees, run git fsck). For broad cleanup I can run targeted or nuclear scripts, and I always verify repository integrity after changes.

When to use it

When you get "worktree is locked" or "cannot remove worktree" errors
If directories were deleted manually but git still lists worktrees
When branches conflict because a branch is already checked out elsewhere
If you see many worktrees harming performance or disk usage
Before running destructive cleanup or automation in a shared repo

Best practices

Diagnose before fixing: git worktree list --porcelain and inspect .git/worktrees for locks
Always use git worktree remove to remove worktrees; avoid rm -rf on worktree directories
Prune stale registrations regularly: git worktree prune
Delete local branches only after merge and confirmation (git branch -d)
Avoid interrupting git operations in worktrees; coordinate long operations during low activity

Example use cases

Locked worktree: detect and remove .git/worktrees/<path>/locked, then git worktree remove or --force if needed
Orphaned registrations: run git worktree prune to clean entries for missing directories
"Already exists" errors: remove leftover directory or prune then recreate with git worktree add
Post-sprint cleanup: remove merged worktrees and delete merged branches to reclaim disk and reduce noise
Nuclear cleanup: remove all non-root worktrees with confirmation and prune afterwards

FAQ

No. Lock files only indicate an interrupted operation. I verify no git processes are running and then remove locks safely; uncommitted changes in the working directory remain unless you remove the worktree directory itself.

How do I avoid orphaned worktrees in the future?

Use git worktree remove to remove worktrees, run git worktree prune regularly, and add build artifacts (node_modules, target) to .git/info/exclude so worktrees stay lightweight.