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.