using-git-worktrees

Detailed Guide to the using-git-worktrees Skill

Skill Overview

using-git-worktrees is a Claude skill specifically designed to create and manage isolated Git workspaces. It helps developers establish independent development environments before starting feature work or executing implementation plans, enabling true parallel development across multiple branches without frequent branch switching.

Use Cases

Feature development requiring isolation: When starting development of a new feature and wanting complete separation from the current workspace to avoid code conflicts and state confusion caused by switching branches.

Before executing implementation plans: Before using skills such as brainstorming, subagent-driven-development, or executing-plans to carry out specific tasks, this skill must be used first to create an isolated development environment, ensuring traceability and safety.

Parallel development across multiple branches: When working on multiple branches simultaneously—for example, developing a new feature while handling a hotfix, or continuing development of another feature during code review—Git worktrees provide multiple independent development environments.

Core Features

Intelligent directory selection and priority management

- Automatically checks existing worktree directories, prioritizing .worktrees/ or worktrees/
- Consults directory preferences in the project's CLAUDE.md
- If no configuration is found, intelligently asks the user to choose between a project-local or global location
- Follows a clear priority order: existing directory > CLAUDE.md configuration > user choice

Security verification and environment protection

- Automatically verifies that a directory is ignored by .gitignore before creating a project-local worktree
- If the directory is not ignored, automatically adds it to .gitignore and commits the change
- Prevents accidental inclusion of worktree contents in the main repository
- Global locations (~/.config/superpowers/worktrees) require no verification and are completely independent of the project

Automated project setup and baseline verification

- Automatically detects the project type and runs the corresponding dependency installation commands (Node.js, Rust, Python, or Go)
- Automatically runs the test suite after creating the worktree to verify a clean baseline
- If the tests fail, clearly reports the failure and asks whether to continue
- Provides a complete location report and confirms readiness

Frequently Asked Questions

What are Git worktrees, and what are they used for?

Git worktrees are a Git feature that allows you to create multiple independent working directories that share the same Git repository object database. This means you can work on different branches simultaneously in different directories without switching branches or cloning multiple copies of the repository each time. With Git worktrees, you can handle a hotfix on the main branch while developing a new feature in another worktree; the two environments remain completely independent.

How do I create and use a Git worktree?

When using this skill, the system automatically creates a worktree according to a standardized process: it first checks existing directories and configurations, then verifies security, creates the worktree, automatically runs project setup tasks such as npm install, and finally verifies the test baseline. You only need to invoke this skill before starting feature work, and the system will complete all configuration automatically. The basic manual command is git worktree add <path> -b <branch-name>, but this skill provides a complete automated workflow with security verification.

Will using a Git worktree affect the main repository?

Not at all. A worktree's working directory is independent of the main repository. Although they share the Git object database, each has its own working files and index. Commits made in a worktree are properly synchronized with the Git repository, while the working files remain isolated. When using this skill, the system also ensures that the worktree directory is ignored by .gitignore, preventing its contents from being accidentally committed to the main repository. Once your work is complete, you can use git worktree remove to delete the worktree without affecting the main repository or any other worktrees.