vt-c-using-git-worktrees¶

Use when starting feature work that needs isolation from the current workspace, or before executing an implementation plan - sets up a built-in worktree under .claude/worktrees/, runs project setup, and verifies a clean test baseline

Plugin: vt-base
Category: Tooling
Command: /vt-c-using-git-worktrees

Using Git Worktrees¶

Overview¶

A worktree is a second working copy of the same repository, so two branches can be checked out at once without switching. Since SPEC-202 the toolkit creates them one way only: the built-in worktree feature, which puts every worktree under .claude/worktrees/<name> and manages its lifecycle with the session. Nothing here creates worktrees by hand any more.

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

Worktree Roles¶

Before creating a new worktree, know what the existing ones are for. V025 uses three worktree roles, each defined by the branch it holds:

Role	Branch	Purpose
Main-Holder	`main`	The worktree that currently holds `main` — often none; `main` is usually checked out nowhere and gets a holder only transiently, at merge time.
Active-Workspace	long-lived `chore/` / `docs/`	The repo-root checkout where tooling commands run and commit between merges to `main`; renamed in place when its name drifts.
Feature	`feature/spec-NNN-*`	One per active spec, under `.claude/worktrees/`; created by the built-in feature and merged back after `/vt-d-complete`.

Full roles, standard procedures (merge into main, sync after main-merge, rename), anti-pattern error signatures, and the spec-numbering-across-branches procedure: docs/solutions/patterns/v025-multi-worktree-workflow.md.

Creating a worktree¶

Three doors to the same feature — pick whichever fits the session you are in:

Where you are	How
In a Claude session	`EnterWorktree` with `name: <name>` (or `path:` to re-enter an existing one)
At a terminal	`claude --worktree <name>` — new worktree, branch and session in one command
In Claude Desktop	Start a session with worktree isolation

For spec work you do not call any of these yourself: /vt-d-activate SPEC-NNN classifies the working copy and offers the worktree at the right moment.

What the new worktree branches from is the worktree.baseRef setting — fresh (default) branches from the origin default branch, head from the invoking checkout's local HEAD. No mode checks out a named existing branch — that is why /vt-d-activate renames the auto-named branch rather than asking for one up front.

Gitignored files do not travel. A worktree is a fresh checkout, so .env, .env*.local and anything else gitignored is absent until you say otherwise. List the paths that should be copied into every new worktree in the project's .worktreeinclude.

⚠ Credential warning: those files hold secrets. If your worktrees live under ~/Library/CloudStorage/, ~/OneDrive*, ~/iCloud Drive/, ~/Dropbox/ or ~/Google Drive/, propagating credentials there exposes them to the cloud sync. Keep repositories with secrets out of cloud-synced locations — .worktreeinclude copies the file wherever the worktree happens to be, it does not judge the destination.

After the worktree exists¶

1. Run project setup¶

Auto-detect and run the 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

2. Verify a clean baseline¶

Run the project's tests so a later failure can be told apart from one you inherited:

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

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

3. Report the location¶

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

Quick Reference¶

Situation	Action
Spec work	Let `/vt-d-activate SPEC-NNN` create or enter the worktree
Ad-hoc isolation inside a session	`EnterWorktree` with a `name`
Ad-hoc isolation from a terminal	`claude --worktree <name>`
A worktree for this name already exists	Enter it by `path` instead of creating a colliding one
The dev-server needs `.env*`	Add the path to `.worktreeinclude`, then recreate the worktree
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

Common Mistakes¶

Two working copies for one spec - Problem: A second worktree is made for a spec that already has one, and the two diverge. - Fix: Check git worktree list first; enter the existing one by path.

Proceeding with failing tests - Problem: New bugs cannot be told apart from pre-existing ones. - 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.).

Worktree dev-server fails on first start with 500 / connection errors - Problem: .env*.local files are gitignored, so the new worktree has no credentials and any code reading process.env / os.environ sees undefined values. - Fix: Put those paths in .worktreeinclude so every new worktree gets them, then read the credential warning above before doing so in a cloud-synced repository.

Red Flags¶

Never: - Create a second working copy for a spec that already has one - Skip the baseline test verification - Proceed with failing tests without asking - Copy credentials into a cloud-synced location

Always: - Check git worktree list before creating anything - Let /vt-d-activate place spec worktrees - Auto-detect and run project setup - Verify a clean test baseline

Next actions¶

Report the worktree path, the branch it holds, and the baseline test result — the developer needs all three before deciding to continue.
Working on a spec? Hand back to /vt-d-2-plan in the session that now sits in the worktree.
Working ad hoc? Continue in this worktree and, when the work is done, merge it following merge into main rather than checking main out here.

Integration¶

Called by: - /vt-d-2-plan (Phase 2) - REQUIRED when a design is approved and implementation follows - Any skill needing an isolated workspace

Pairs with: - /vt-d-5-finalize - REQUIRED for cleanup after work is complete - /vt-d-executing-plans - the work happens in this worktree