Verified:GitHub

using-git-worktrees

Create isolated git worktrees with safety checks and project setup.

2|Updated May 19, 2024

Search Tags:#git #worktrees #isolation #gitignore #safety-verification #feature-work

One-click install

npx skills add https://github.com/YanBerdin/next-portfolio --skill using-git-worktrees-yanberdin

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: using-git-worktrees
Source: https://github.com/YanBerdin/next-portfolio/tree/main/.github/skills/using-git-worktrees
Command: npx skills add https://github.com/YanBerdin/next-portfolio --skill using-git-worktrees-yanberdin

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

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

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Core Features & Use Cases

Follow this priority order and safety steps to manage isolated workspaces:

1. Directory Selection Process

Check existing directories (.worktrees preferred, then worktrees)
If a CLAUDE.md preference exists (e.g., worktree directory), use it
Otherwise, prompt the user for a location:
.worktrees/ (project-local, hidden)
~/.config/superpowers/worktrees/<project-name>/ (global location)

2. Safety Verification

For Project-Local Directories (.worktrees or worktrees)

MUST verify directory is ignored before creating worktree with git check-ignore If NOT ignored:

Add appropriate line to .gitignore
Commit the change
Proceed with worktree creation Why critical: Prevents accidentally committing worktree contents to repository.

3. Creation Steps

Detect Project Name
Create Worktree
Run Project Setup
Verify Clean Baseline
Report Location

4. Run Project Setup

Auto-detect and run appropriate setup:

Node.js: npm install
Rust: cargo build
Python: pip install -r requirements.txt; poetry install
Go: go mod download

5. Verify Clean Baseline

Run tests to ensure worktree starts clean:

npm test
cargo test
pytest
go test ./...

If tests fail: Report failures, ask whether to proceed or investigate. If tests pass: Report ready.

6. Report Location

Worktree ready at <full-path> Tests passing (<N> tests, 0 failures) Ready to implement <feature-name>

Quick Reference

| Situation | Action | |-----------|--------| | .worktrees/ exists | Use it (verify ignored) | | worktrees/ exists | Use it (verify ignored) | | Both exist | Use .worktrees/ | | Neither exists | Check CLAUDE.md → Ask user | | Directory not ignored | Add to .gitignore + commit | | Tests fail during baseline | Report failures + ask | | No package.json/Cargo.toml | Skip dependency install |

Common Mistakes

Skipping ignore verification

Problem: Worktree contents get tracked, pollute git status
Fix: Always use git check-ignore before creating project-local worktree

Assuming directory location

Problem: Creates inconsistency, violates project conventions
Fix: Follow priority: existing > CLAUDE.md > ask

Proceeding with failing tests

Problem: Can't distinguish new bugs from pre-existing issues
Fix: Report failures, get explicit permission to proceed

Hardcoding setup commands

Problem: Breaks on projects using different tools
Fix: Auto-detect from project files (package.json, etc.)

Example Workflow

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

[Check .worktrees/ - exists] [Verify ignored - git check-ignore confirms .worktrees/ is ignored] [Create worktree: git worktree add .worktrees/auth -b feature/auth] [Run npm install] [Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth Tests passing (47 tests, 0 failures) Ready to implement auth feature

Red Flags

Never:

Create worktree without verifying it's ignored (project-local)
Skip baseline test verification
Proceed with failing tests without asking
Assume directory location when ambiguous
Skip CLAUDE.md check

Always:

Follow directory priority: existing > CLAUDE.md > ask
Verify directory is ignored for project-local
Auto-detect and run project setup
Verify clean test baseline

Integration

Called by:

brainstorming (Phase 4) - REQUIRED when design is approved and implementation follows
subagent-driven-development - REQUIRED before executing any tasks
executing-plans - REQUIRED before executing any tasks
Any skill needing isolated workspace

Pairs with:

finishing-a-development-branch - REQUIRED for cleanup after work complete

Frequently Asked Questions about using-git-worktrees

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I create an isolated git workspace for concurrent feature development?▼

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching, which solves the problem of context switching during concurrent feature development.

How do I prevent git worktree directories from being accidentally committed to the repository?▼

To prevent accidental commits, verify the worktree directory is ignored using git check-ignore before creation, and if not ignored, add it to .gitignore and commit the change before proceeding with worktree setup.

What is the best way to set up a new git worktree without breaking project conventions?▼

Follow a systematic directory selection priority: check existing directories first, then CLAUDE.md preferences, and finally prompt the user for a location to ensure consistency with established project conventions.

Why should I run tests before starting work in a new git worktree?▼

Running tests verifies a clean baseline in the new git worktree, ensuring you can distinguish new bugs from pre-existing issues and preventing confusion when failures occur during feature implementation.

Can I auto-detect and run project setup commands when creating a git worktree?▼

Yes, project setup is auto-detected by checking for files like package.json for npm install, Cargo.toml for cargo build, requirements.txt for pip install, and go.mod for go mod download to automatically install dependencies in the new worktree.

What happens if baseline tests fail during git worktree creation?▼

If baseline tests fail during worktree creation, the system reports the failures and asks whether to proceed or investigate, preventing you from starting feature work on a broken foundation with pre-existing issues.

hitsumabushi334

using-git-worktrees

A tool for creating and managing isolated Git worktrees efficiently and safely, ensuring your main workspace stays clean and your builds are reproducible. It .----This is the wrong one, ignore it. Let's try again.

Community

Basic