git-worktree_skill

Overview

This skill manages Git worktrees for isolated, parallel development using a single manager script. It creates, lists, switches, and cleans up worktrees while copying environment files and keeping .worktrees ignored. The design favors KISS: simple commands, interactive confirmations, and safe defaults. It prevents accidental use of raw git worktree commands by centralizing setup and cleanup logic.

How this skill works

The manager script runs git worktree operations while adding safety and convenience steps: it ensures .worktrees is listed in .gitignore, copies .env* files from the main repo, and enforces a consistent directory structure. Commands include create, list, switch, copy-env, and cleanup, all of which prompt interactively and show clear status. Worktrees are lightweight file-system-linked checkouts that share git objects with the main repo, so branches and history are preserved without full clones. The tool refuses direct raw git worktree calls and provides explicit prompts before destructive actions.

When to use it

• Reviewing a PR when you are not on the PR branch — offer an isolated worktree
• Starting a new feature and you want parallel work without switching your main branch
• Working on multiple features simultaneously and needing fast context switches
• Cleaning up finished worktrees to free disk and reduce clutter
• When you need .env files copied into an isolated checkout quickly

Best practices

• Always run the manager script (not raw git worktree commands) to preserve env files and .gitignore settings
• Name worktrees using branch-like, descriptive names to keep directories clear
• Create from main by default; only override the base branch when necessary
• Use interactive prompts to confirm create/cleanup operations to avoid accidental deletes
• Run cleanup from the main repo root to remove inactive worktrees safely

Example use cases

• Isolated code review: create a worktree for the PR branch, test locally, then cleanup
• Parallel feature dev: open two worktrees for different features and switch between them without stashing
• Emergency fix: create a small worktree from main, apply fix, push, then remove the worktree
• Env propagation: create worktrees that automatically receive .env, .env.local, .env.test files for consistent local runs
• Cleanup routine: list inactive worktrees interactively and remove finished ones with confirmation