| name | git-worktree |
| description | Manage parallel git worktrees for isolated feature development, code review, and hotfix branches. Routes all git operations through a manager protocol that handles .env copying, port isolation, and dependency drift detection. Prevents cross-branch pollution and accidental commits to the wrong branch. |
When To Use
- Need to review a PR while working on a feature.
- Need to test a hotfix on
main without disturbing your feature branch.
- Need to run two versions of the app side-by-side (e.g., old vs new API).
- User says "check out this branch" while there are uncommitted changes.
- About to run a long-running task (build, test suite) and need to do other work in parallel.
Related: /ship for final merge workflow; /investigate for debugging on a separate branch.
Do not use this skill for simple git stash && git checkout workflows where only a quick file read is needed. Not suitable for monorepos with deeply interdependent packages without additional config.
Core Stance
git stash && git checkout is error-prone and destroys state. Cloning the repo multiple times wastes disk space and drifts out of sync.git worktree allows multiple branches to coexist in separate directories while sharing one .git object database.- Without protocol, worktrees create chaos:
.env files don't copy, node_modules drift, ports conflict, .gitignore rules differ per branch.
Research Backing
- Git documentation (kernel.org) —
git worktree is the canonical mechanism for parallel branch checkout; official support since Git 2.5 (2015).
- Hunt & Thomas (1999), The Pragmatic Programmer — "Version Control as a Time Machine": isolation of parallel workstreams reduces merge conflict surface area.
- Forsgren et al. (2018), Accelerate — trunk-based development with short-lived branches correlates with elite DevOps performance; worktrees enable fast context switching within trunk-based workflows.
Process
- Create worktree —
git worktree add .worktrees/[type]-[desc] [branch]. Types: feature, review, hotfix, spike, release.
- Copy environment files —
.env, .env.local, .env.development from root to worktree if they exist.
- Install dependencies — Run
npm install (or pnpm/yarn) inside the worktree if package.json exists.
- Assign port — If root uses port 3000, assign 3001, 3002, etc. Update worktree
.env with new port. Maintain PORT_REGISTRY.md.
- Update .gitignore — Add worktree-specific patterns:
.worktrees/*/.env, .worktrees/*/node_modules, .worktrees/*/.next, .worktrees/*/dist.
- Verify readiness —
git branch --show-current returns expected branch. git status shows clean state. Assigned port is free. npm start launches without errors. Smoke test returns 200.
Dependency Drift Detection
Before switching to a worktree unused >24 hours:
- Check if root
package.json changed since worktree creation (compare git log timestamps).
- If root is newer, re-install in worktree.
- If lockfiles differ, re-install.
Clean Deletion Protocol
git worktree remove .worktrees/[name] (or --force if uncommitted changes).- If branch was temporary,
git branch -D [branch].
- Remove entry from
PORT_REGISTRY.md.
- Run
git worktree prune.
Operating Rules
- Never
git checkout inside a worktree to a branch checked out in another worktree.
- Never commit to
main from a feature worktree unless explicitly doing a hotfix.
- Never copy
node_modules between worktrees (symlinks acceptable if package manager supports).
- Never assume
.env variables are the same across worktrees — always verify.
- When switching between worktrees: announce the switch, verify branch, verify no uncommitted changes in previous worktree (or stash with explicit message), re-read context files.
- Always prefix test/build/dev commands with worktree path or run from inside it — not from root.
Output Format
Maintain at .worktrees/PORT_REGISTRY.md:
| Worktree | Branch | Port | Status |
|----------|--------|------|--------|
| feature-auth-refactor | auth-refactor | 3001 | active |
| review-pr-447 | pr-447 | 3002 | active |
On worktree creation, announce:
Worktree `.worktrees/[name]/` ready on port [N].
Branch: [branch]
Verification: `git branch --show-current` returns [branch], smoke test passes.
Example
User: "Review PR #447 while I keep working on my auth branch."
Agent: Creates .worktrees/review-pr-447/ from PR branch, copies .env, assigns port 3002, installs deps, verifies smoke test. User can now cd .worktrees/review-pr-447 && npm run dev while auth branch continues in root.
