Git Worktrees Skill

A comprehensive skill for creating isolated Git worktrees with smart directory selection and safety verification.

Overview

This skill enables systematic creation of isolated workspaces that share the same repository, allowing work on multiple branches simultaneously without switching contexts. It follows the principle: Systematic directory selection + safety verification = reliable isolation.

Features

• Smart Directory Selection: Automatically detects existing worktree directories (.worktrees/, worktrees/) or asks for user preference
• Safety Verification: Ensures .gitignore contains worktree directories to prevent accidental commits
• PR-Based Worktrees: Create worktrees from existing pull requests using GitHub CLI or GitHub MCP
• Environment Handling: Links .venv using symbolic links, copies .env* files with proper directory structure
• Multi-Language Support: Auto-detects and sets up Python (uv/poetry/pip), Node.js, Rust, Go projects
• Baseline Verification: Runs unit tests to ensure clean starting state
• Cross-Platform: Works on macOS, Linux, and Windows

Installation

git clone https://github.com/chen-gdp/git-worktrees-skill.git ~/.config/opencode/skill/using-git-worktrees

Prompt to give to AI:

Read https://github.com/chen-gdp/git-worktrees-skill/blob/main/INSTRUCTIONS.md and follow the installation steps.

For detailed installation instructions, verification steps, and troubleshooting, see INSTRUCTIONS.md.

Usage

Basic Usage

I'm using the using-git-worktrees skill to set up an isolated workspace.

From Pull Request

I'm using the using-git-worktrees skill to set up an isolated workspace from PR #42.

For New Branch

I'm using the using-git-worktrees skill to set up an isolated workspace for new feature.

How It Works

1. Directory Selection Logic

Priority order:

1. Existing directories: .worktrees/ (preferred) or worktrees/
2. CLAUDE.md preference: Checks for explicit worktree directory specification
3. User choice: Asks between project-local (.worktrees/) or global location

2. Safety Verification

• Project-local directories: Must be in .gitignore to prevent tracking
• Global directories: No verification needed (outside project)

3. Environment Setup

• Virtual environments: Links existing .venv from root using ln -s
• Environment files: Copies all .env* files from entire repo using cp (never reads contents), maintaining directory structure
• Project dependencies: Auto-detects package manager and runs appropriate install

4. Language Support

Language	Detection	Setup Commands	Priority
Python	pyproject.toml, requirements.txt	uv sync > poetry install > pip install	uv > poetry > pip
Node.js	package.json	npm install	-
Rust	Cargo.toml	cargo build	-
Go	go.mod	go mod download	-

5. Baseline Verification

Runs unit tests to ensure clean starting state:

• Checks Makefile for test-unit or test targets first
• Falls back to language-specific test commands
• Reports test status before proceeding

Directory Structure

project/
├── .gitignore          # Must contain .worktrees/ (if using project-local)
├── .worktrees/         # Project-local worktrees (hidden)
│   ├── feature-auth/
│   └── bugfix-issue/
├── worktrees/          # Alternative project-local
│   └── feature-api/
└── ~/.config/superpowers/worktrees/  # Global location
    └── myproject/
        └── feature-db/

Example Workflows

PR-Based Workflow

Worktree ready at /project/.worktrees/feature-auth-login
From PR #42: feature/auth-login → main
Tests passing (47 tests, 0 failures)
Ready to work on PR #42

New Branch Workflow

Worktree ready at /project/.worktrees/auth
Tests passing (89 tests, 0 failures)
Ready to implement auth feature

Safety Features

Security

• Never reads .env file contents - uses find/ls for detection only
• Copy .env files - each worktree gets its own isolated copy with correct directory structure
• Always verifies .gitignore - prevents accidental worktree commits

Reliability

• Baseline test verification - ensures clean starting state
• Project detection - works with any project structure
• Graceful fallbacks - handles missing tools/files gracefully

Configuration

Worktree Location Preference

Add to CLAUDE.md:

worktree directory: .worktrees

Custom Makefile Targets

install:
    npm install

test-unit:
    npm run test:unit

Integration

This skill integrates with:

• brainstorming - Required when design is approved and implementation follows
• finishing-a-development-branch - Required for cleanup after work complete
• executing-plans or subagent-driven-development - Work happens in created worktree

Contributing

1. Fork the repository
2. Create a worktree for your changes: git worktree add .worktrees/your-feature -b feature/your-name
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Author

Created for OpenCode - an AI-powered development environment.

---

Core principle: Systematic directory selection + safety verification = reliable isolation.