using-git-worktrees

Using Git Worktrees - Intelligent Skills for Isolated Workspace Management

Skill Overview

Using Git Worktrees is a Superpowers skill that creates isolated Git workspaces before starting feature development. It enables reliable parallel development across multiple branches through systematic directory selection and safety validation.

Suitable Scenarios

When you need to develop a new feature and want it isolated from your current workspace, this skill automatically selects the appropriate directory, creates the worktree, runs project setup, and verifies the testing baseline—so you can begin in a clean environment.

Before using executing-plans or subagent-driven-development to execute an implementation plan, use this skill to create an isolated worktree. This helps avoid conflicts with the main branch or other work. It is a recommended complementary action for the fourth phase of the brainstorming skill.

When you need to work on multiple branches at the same time (e.g., developing Feature A, fixing Bug B, and reviewing Code C in parallel) without frequently switching branches or cloning multiple repositories, worktree lets you work in parallel within different directories of the same repository.

Core Features

The skill automatically selects a worktree directory by priority: first it checks existing .worktrees/ or worktrees/ directories, then checks configuration preferences in CLAUDE.md, and finally asks whether to use a project-local or global location. This ensures directory selection remains consistent and predictable.

Before creating a project-local worktree, it automatically verifies whether the directory is ignored by .gitignore, preventing accidental commits of worktree contents to the repository. If the directory is not ignored, it will automatically add it to .gitignore and commit the change, following the principle of “immediately fix the broken things.”

After creating the worktree, it automatically detects the project type (Node.js, Rust, Python, Go, etc.) and runs the corresponding dependency installation commands. Then it executes tests to verify a clean baseline. If tests fail, it reports what happened and asks whether to continue, ensuring you understand the starting state.

Common Questions

What’s the difference between Git worktree and traditional branch switching?

Git worktree lets you check out different branches simultaneously in multiple directories within the same repository—without switching branches or using git stash. Each worktree has its own independent working directory and staging area, but shares the same Git repository object database. This means you can work on multiple branches at the same time without interfering with each other. In contrast, traditional branch switching requires you to commit or stash your current changes first.

What safety considerations should be kept in mind when using worktree?

The most critical point is to ensure the worktree directory is ignored by .gitignore; otherwise, Git may track the worktree contents, polluting git status and potentially leading to accidental commits. This skill automatically runs git check-ignore to verify before creating the worktree. In addition, it’s recommended to run tests after creation to validate the baseline, so that if problems occur, you can distinguish whether they’re newly introduced bugs or pre-existing issues.

Should worktree be placed inside the project or in a global directory?

This depends on your team and working style. A project-local directory (e.g., .worktrees/) makes collaboration and CI/CD integration easier, but you must ensure it’s ignored by .gitignore. A global directory (e.g., ~/.config/superpowers/worktrees/<project>/) is fully independent of the project, which suits personal development or cases where you don’t want to pollute project directories. This skill will prioritize detecting existing directories and the CLAUDE.md configuration to stay consistent; if there’s no preference, it will ask you to choose.