worktree-kit_skill

Overview

This skill manages Git worktrees and related environment files from a simple CLI script. It helps create, list, switch, and clean worktrees, and copy .env files into registered worktrees for isolated parallel work. Designed for workflows that require safe, repeatable workspace isolation under a single repository.

How this skill works

The manager script runs commands from the repository root and keeps worktrees under a local .worktrees/ directory. Commands include create, list, switch (prints the worktree path), cleanup (removes clean worktree directories only), and copy-env (copies .env* into a registered worktree without overwriting). The tool refuses to operate on symlinked .worktrees paths and skips symlinked .env targets for safety.

When to use it

• Start a parallel feature branch or experiment without touching your current working tree.
• Prepare an isolated review environment for a colleague or CI step.
• Switch quickly between multiple long-lived or short-lived contexts inside the same repo.
• Clean up completed or abandoned worktrees while preserving branches and avoiding forced deletes.
• Copy local .env files into a worktree for local testing without risking overwrites.

Best practices

• Create worktrees via the manager so they live under .worktrees/ and are tracked consistently.
• Do not expect create to change your current branch; it only prepares the new worktree.
• Run cleanup only when the worktree is clean; cleanup will not force-remove uncommitted changes.
• Use copy-env to seed configuration, noting it will not overwrite existing .env* files and skips symlinks.
• Avoid symlinked components in .worktrees/ or worktree path; the tool refuses to operate on symlinked paths for safety.
• When creating from a base, allow an optional origin fetch only if the base looks like a branch; local refs are accepted.

Example use cases

• Create a feature worktree for an experimental change without disturbing the main working tree: worktree-kit create feature-a main
• Open a review environment for a pull request: worktree-kit create pr-123 origin/pr/123 && worktree-kit switch pr-123
• Copy your local .env into a registered worktree for integration testing: worktree-kit copy-env staging
• List all active worktrees and paths quickly during multi-feature development: worktree-kit list
• Clean up finished worktrees after merging, preserving Git branches: worktree-kit cleanup