git-worktree

Worktree Creation

Create a worktree under .worktrees/<branch> with branch-specific setup that git worktree add alone does not handle:

• Copies .env, .env.local, .env.test, etc. from the main repo (skips .env.example)
• Trusts mise/direnv configs, with branch-aware safety rules so review branches do not auto-grant trust to untrusted .envrc content
• Adds .worktrees to .gitignore if not already ignored
• Does not modify the main repo checkout — from-branch is fetched, not checked out

Creating a worktree

bash scripts/worktree-manager.sh create <branch-name> [from-branch]

Defaults:

• from-branch defaults to origin's default branch (or main if that cannot be resolved)
• The new branch is created at origin/<from-branch> (or the local ref if the remote is unavailable)

Examples:

bash scripts/worktree-manager.sh create feat/login
bash scripts/worktree-manager.sh create fix/email-validation develop

After creation, switch to the worktree with cd .worktrees/<branch-name>.

Other worktree operations

Use git directly — no wrapper is needed and none is provided:

git worktree list                          # list worktrees
git worktree remove .worktrees/<branch>    # remove a worktree
cd .worktrees/<branch>                     # switch to a worktree
cd "$(git rev-parse --show-toplevel)"      # return to main checkout

To copy .env* files into an existing worktree created without them, run this from the main repo (not from inside the worktree, since branch names often contain slashes like feat/login):

cp .env* .worktrees/<branch>/

Dev tool trust behavior

When mise or direnv configs are present, the script attempts to trust them so hooks and scripts do not block on interactive prompts. Trust is baseline-checked against a reference branch:

• Trusted base branches (main, develop, dev, trunk, staging, release/*): the new worktree's configs are compared against that branch; unchanged configs are auto-trusted. direnv allow is permitted.
• Other branches (feature branches, PR review branches): configs are compared against the default branch; direnv allow is skipped regardless, because .envrc can source files that direnv does not validate.

Modified configs are never auto-trusted. The script prints the manual trust command to run after review.

When to create a worktree

Create a worktree when:

• Reviewing a PR while keeping the main checkout free for other work
• Running multiple features in parallel without branch-switching overhead
• Keeping the default branch free of in-progress state

Do not create a worktree for single-task work that can happen on a branch in the main checkout.

Integration

spec-work and spec-code-review offer this skill as an option. When the user selects "worktree" in those flows, invoke bash scripts/worktree-manager.sh create <branch> with a meaningful branch name derived from the work description (e.g., feat/crowd-sniff, fix/email-validation). Avoid auto-generated names like worktree-jolly-beaming-raven that obscure the work.

Troubleshooting

"Worktree already exists": the path is already in use. Either switch to it (cd .worktrees/<branch>) or remove it (git worktree remove .worktrees/<branch>) before recreating.

"Cannot remove worktree: it is the current worktree": cd out of the worktree first, then git worktree remove.

Dev tool trust was skipped: the script prints the manual command. Review the config diff (git diff <base-ref> -- .envrc), then run the printed command from the worktree directory.