using-git-worktrees

Using Git Worktrees

Overview

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."

Iron Law: Use bd worktree, NOT git worktree

ALWAYS use bd worktree commands. NEVER use raw git worktree commands.

Why: bd worktree create does everything git worktree add does PLUS:

• Worktree automatically shares the main repo's beads database via git common directory discovery
• Adds the worktree path to .gitignore automatically
• Ensures consistent issue state across all worktrees

Raw git worktree add misses .gitignore setup and safety checks — while beads database sharing works via git common directory, you lose the automation bd worktree create provides.

| Action | Use This | NOT This | |--------|----------|----------| | Create worktree | bd worktree create .worktrees/<name> | ~~git worktree add~~ | | List worktrees | bd worktree list | ~~git worktree list~~ | | Remove worktree | bd worktree remove .worktrees/<name> (if the safety check flags the local-only branch as unpushed, verify the merge landed, then add --force) | ~~git worktree remove~~ | | Worktree info | bd worktree info | ~~(no equivalent)~~ |

Note: Claude Code provides a native EnterWorktree tool for worktree management. For non-beads projects, this is a viable alternative. For beads-integrated projects, bd worktree create remains mandatory — it handles database sharing and .gitignore management that EnterWorktree does not provide.

Deliberate divergence from upstream: superpowers v6.0.3 rewrote this skill to prefer the harness-native worktree tool first (EnterWorktree → existing .worktrees/ → raw git worktree). We do not adopt that native-tool-first selection order — it bypasses bd worktree's beads-database sharing across worktrees. The Iron Law above (always bd worktree) is intentional and takes precedence.

Directory Selection

Always create worktrees under .worktrees/ in the project root:

• bd worktree create .worktrees/<name> — creates the worktree at .worktrees/<name> and adds the path to .gitignore automatically
• Trap: the bare-name form (bd worktree create <name>) creates at ./<name>, cluttering the repo root — always pass the full path
• If your project's CLAUDE.md names a different preferred worktree directory, pass that path instead

Safety Verification

bd worktree create automatically adds the worktree path to .gitignore when inside the repo root. Verify as a safety net:

git check-ignore -q <worktree-path> 2>/dev/null

If NOT ignored (edge case — bd worktree create should have handled this): add the path to .gitignore and commit.

Pre-Flight Checks

Run these checks BEFORE creating any worktree.

Detect Existing Worktree Isolation

Check whether you are already inside a worktree:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
if [ "$GIT_DIR" != "$GIT_COMMON" ]; then
  echo "WARNING: Already inside a worktree."
fi

If already in a worktree, warn and ask via your structured question tool whether to proceed (creating a nested worktree) or abort.

Submodule Guard

Check whether you are inside a git submodule:

SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
if [ -n "$SUPERPROJECT" ]; then
  echo "WARNING: Inside a git submodule. Worktrees behave unpredictably here."
fi

If inside a submodule, warn and stop. Do NOT create worktrees inside submodules.

Consent Flow

• User-initiated (manual worktree creation): Ask via your structured question tool before creating — "I'd like to create a worktree at <path>. Proceed?"
• Dispatched by subagent-driven-development: Consent is implicit — the orchestrator authorized worktree creation. Skip the prompt.

Creation Steps

0. Claim the bead first

Before creating the worktree, claim the issue you're about to work on. This prevents ownerless work — you own the bead before any environment exists.

bd update <issue-id> --claim

--claim consent boundary. Claim the specific bead you are about to work on (bd update <id> --claim, above). The autonomous take-next form bd ready --claim is NOT this skill's pattern and is FORBIDDEN wherever the user picks the work — the consent gate binds even when this skill is not loaded.

1. Create Worktree with bd worktree create

# Standard — creates worktree at .worktrees/<name> with matching branch
bd worktree create .worktrees/<feature-name>

# With explicit branch name
bd worktree create .worktrees/<feature-name> --branch <branch-name>

# Then cd into it
cd .worktrees/<feature-name>

What bd worktree create does automatically:

1. Creates the git worktree with a new branch
2. Worktree automatically discovers the main repo's beads database via git common directory (no redirect file needed)
3. Adds worktree path to .gitignore (if inside repo root)

2. Run Project Setup

Auto-detect and run appropriate setup:

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

3. Verify Clean Baseline

Run tests to ensure worktree starts clean:

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

If tests fail: Report failures, then use your structured question tool to ask: Question: "Baseline tests failing in worktree (<N> failures). How should I proceed?" Options: "Investigate failures" (debug before starting feature work), "Proceed anyway" (start implementation despite pre-existing failures) A skipped, dismissed, or auto-resolved answer is not consent — stop and ask in plain text.

If tests pass: Report ready.

4. Report Location

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

Multiple Worktrees for Parallel Subagents

When Subagent-Driven Development runs independent tasks in parallel, the orchestrator creates and manages multiple worktrees. Subagents never create or destroy worktrees — they receive a path and work within it.

Pattern:

# 1. Orchestrator creates epic worktree (once)
bd worktree create .worktrees/<epic-name>

# 2. For each parallel task (max 5 concurrent):
bd worktree create .worktrees/<task-name> --branch feature/<epic>/<task>

# 3. Subagent receives path in its prompt:
#    "Work from: <task-worktree-path>"

# 4. After task passes review — orchestrator merges and cleans up:
cd .worktrees/<epic-name>
git merge feature/<epic>/<task>
bd worktree remove .worktrees/<task-name>
# (if the safety check flags the local-only branch as unpushed, verify the merge landed, then add --force)

Constraints:

• Maximum 5 concurrent task worktrees (resource limit)
• Orchestrator manages the full lifecycle — subagents never run bd worktree commands
• All task worktrees branch from the same HEAD commit (created before any subagent commits)
• After merge, run the full test suite on the epic worktree to catch integration issues

See also: beads-superpowers:subagent-driven-development → Parallel Batch Mode section for the full orchestration flow.

Quick Reference

| Situation | Action | |-----------|--------| | Creating a worktree | bd worktree create .worktrees/<name> — handles path + .gitignore | | Different directory preferred by project CLAUDE.md | pass that path the same way | | Dire