rbergman/worktrees

Git Worktrees

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

Primary tool: bd worktree — handles git worktree + beads integration automatically.

---

When to Use

• Parallel subagents need filesystem isolation
• Feature work that shouldn't affect current workspace
• Separate builds/servers running simultaneously
• Before executing implementation plans

---

Guardrails

• Do not merge a worktree branch to main without explicit user sign-off — merges affect shared codebase and may contain unreviewed work
• Do not delete a worktree without explicit user sign-off — deletion destroys uncommitted changes
• Do not close beads for a worktree branch without user sign-off
• After completing implementation, stop and report status. Do not proceed to merge.
• Use /merge when ready to integrate — it enforces the pre-flight checklist.

---

Setup: Ensure .worktrees/ is Ignored

Before creating any worktrees, ensure .worktrees/ is in .gitignore. This is a one-time setup that covers all future worktrees:

# Check if .worktrees/ is already ignored
git check-ignore -q .worktrees/ || echo '.worktrees/' >> .gitignore

If you added the line, commit it:

git add .gitignore && git commit -m "Ignore .worktrees/ directory"

Why this matters: Without this, beads adds each worktree individually to .gitignore, creating noise. With .worktrees/ ignored, all worktrees underneath are automatically covered.

---

Creating a Worktree

All worktrees go under .worktrees/ in the repo root. This is the standard location.

bd worktree create .worktrees/feature-auth

What it does automatically:

1. Creates git worktree at the specified path
2. Sets up .beads/redirect pointing to main repo's database
3. Creates the branch (same name as the directory by default)

With custom branch name:

bd worktree create .worktrees/bugfix --branch fix-123

---

Personal Prefs Across Worktrees

CLAUDE.local.md only exists in one worktree. To share personal preferences across all worktrees, use a home-directory import in each worktree's CLAUDE.local.md:

# CLAUDE.local.md
@~/.claude/my-project-instructions.md

This way all worktrees load the same personal preferences from a single source. The @~/... import syntax resolves to your home directory regardless of which worktree you're in.

---

Beads in Worktrees

Beads stores issue state in the primary repo's .beads/embeddeddolt/ (gitignored) and exports the transport to .beads/issues.jsonl (committed). Running bd from a linked worktree shares the same database — that's correct — but the JSONL export still lands relative to the primary checkout, and any mutation dirties files that are visible across all worktrees.

Ownership rule. The agent who runs a mutating bd command (bd create / update / close / remember / dep) owns the resulting .beads/issues.jsonl change:

1. Batch the JSONL change into the same logical commit as the code change that motivated it. If it must stand alone, land it from primary as chore(beads): ....
2. Never commit MM .beads/issues.jsonl you didn't author. Leave it for the owning agent unless you're explicitly coordinating.

JSONL commit discipline. Hooks help but aren't sufficient — auto-export can succeed while the hook's internal git add fails. After any bead mutation:

git status --short                 # verify .beads/issues.jsonl is staged ('M ', not 'MM' or ' M')
bd export -o .beads/issues.jsonl   # explicit re-export if needed
git add .beads/issues.jsonl        # restage if 'MM' (export happened after staging)

MM .beads/issues.jsonl means the export landed after staging — restage before committing.

Recovery for abandoned worktree mutations. git restore .beads/issues.jsonl resets only the exported transport file; the actual bead state lives in the gitignored embedded Dolt database. Behavior depends on what you want:

• Keep the bead change, just not as a JSONL edit yet: git restore .beads/issues.jsonl is fine. The Dolt state survives, and the next bd export reproduces it. Don't panic-revert thinking git restore undid the bead work.
• Discard the bead change too: git restore alone is insufficient — the next bd export (from any worktree, including the one that originally mutated) will re-emit the mutation back into the JSONL. You must reverse the mutation in Dolt first: bd update <id> --status=open to undo a close, bd close <id> to retire a stray bd create, etc. Then re-export and verify git status is clean.

---

Before Stepping Away from a Worktree

A shared filesystem means one worktree's broken WIP can fail another worktree's quality gates (Stop hooks, just check-fast, etc.). When pausing or ending a session in a worktree, leave it in one of three states:

1. Committed — even a wip: commit is fine. Captures intent and clears the working tree.
2. Stashed — git stash -u captures untracked work too.
3. Clean — git status --short shows no entries.

Never strand a broken-compile or failing-lint state in a shared worktree. The next agent (you, a teammate, or a future session) inherits the filesystem.

---

After Creation

1. Enter Worktree

cd .worktrees/feature-auth

2. Run Project Setup

# Node.js
[ -f package.json ] && npm install

# Rust
[ -f Cargo.toml ] && cargo build

# Go
[ -f go.mod ] && go mod download

3. Verify Baseline

npm test  # or cargo test, go test ./...

If tests fail: Report failures, ask whether to proceed.

4. Verify Beads Shared

bd ready  # Should show same beads as main workspace

---

Listing Worktrees

bd worktree list

Or standard git:

git worktree list

---

Removing a Worktree

Use bd worktree remove — includes safety checks:

bd worktree remove feature-auth

Safety checks (automatic):

• Uncommitted changes
• Unpushed commits
• Stashes

Skip checks (not recommended):

bd worktree remove feature-auth --force

---

Worktree Info

Check current worktree status:

bd worktree info

---

Quick Reference

| Task | Command | |------|---------| | Ensure .worktrees/ ignored | git check-ignore -q .worktrees/ \|\| echo '.worktrees/' >> .gitignore | | Create worktree | bd worktree create .worktrees/<name> | | Create with branch | bd worktree create .worktrees/<name> --branch <branch> | | List worktrees | bd worktree list | | Remove worktree | bd worktree remove .worktrees/<name> | | Check status | bd worktree info | | Verify beads sync | bd ready (in worktree) |

---

Why bd worktree?

| Manual git worktree | bd worktree | |---------------------|-------------| | Separate commands for git + beads | Single command | | No beads redirect setup | Automatic redirect to main DB | | No safety checks on remove | Checks for uncommitted/unpushed |

---

Example Workflow

# One-time: ensure .worktrees/ is ignored
git check-ignore -q .worktrees/ || echo '.worktrees/' >> .gitignore

# Create isolated workspace
bd worktree create .worktrees/feature-auth

# Enter and setup
cd .worktrees/feature-auth
npm install
npm test  # ✓ 47 passing

# Verify beads shared
bd ready  # Shows same issues as main

# Work on feature...
bd claim auth-001

# When done
cd ../..
bd worktree remove .worktrees/feature-auth

---

Known Limitations

Worktrees Share the Dolt Database

Worktrees created with bd worktree create share the main repo's Dolt database via .beads/redirect. This is the correct behavior — all worktrees see the same beads data.

If a worktree was created with git worktree add instead, it gets an independent empty Dolt DB. Fix by deleting the worktree's .beads/dolt/ and .beads/embeddeddolt/ (whichever is present), then creating a .beads/redirect file containing the relative path to the main repo's .beads/ (e.g., ../../.beads).

---

Fallback (No Beads)

If beads isn't installed, use manual git worktree:

# Verify ignored
git check-ignore -q .worktrees/ || echo '.worktrees/' >> .gitignore

# Create
git worktree add .worktrees/feature-auth -b feature-auth

# Remove
git worktree remove .worktrees/feature-auth

But you lose: automatic redirect setup and safety checks.