kmshihab7878 Git Worktrees
Isolated development environments. Parallel work without branch switching. Clean separation.
Triggers
- Need to work on multiple features simultaneously
- Subagent work that modifies overlapping files
- Experimental changes that should not touch the main working directory
- Running tests on one branch while developing on another
- Agent isolation via
EnterWorktree/ExitWorktreetools
When to Use Worktrees vs Branches
| Scenario | Use |
|---|---|
| Sequential feature work | Branch (simpler) |
| Parallel feature work | Worktree (isolated) |
| Quick hotfix while mid-feature | Worktree (no stash needed) |
| Subagent isolation | Worktree (via isolation: "worktree" on Agent tool) |
| Spike/experiment alongside main work | Worktree (disposable) |
| Code review while developing | Worktree (separate checkout) |
Worktree Workflow
Creating a Worktree
# Create a worktree for a new branch
git worktree add ../project-feature-name -b feature/feature-name
# Create a worktree for an existing branch
git worktree add ../project-hotfix hotfix/urgent-fix
# List active worktrees
git worktree list
Directory naming: Use ../<project>-<purpose> to keep worktrees adjacent to the main repo.
Working in a Worktree
# Each worktree is a full checkout — cd into it and work normally
cd ../project-feature-name
# Run tests, edit files, commit — all isolated from main worktree
# Install dependencies if needed (they're NOT shared)
npm install # or pip install -r requirements.txt, etc.
Cleaning Up
# When done with a worktree
cd /path/to/main/repo
git worktree remove ../project-feature-name
# Prune stale worktree references
git worktree prune
Agent Tool Integration
When spawning subagents, use isolation: "worktree" to give each agent its own copy:
Agent tool parameters:
isolation: "worktree"
prompt: "Implement feature X in the isolated worktree..."
The worktree is automatically cleaned up if the agent makes no changes. If changes are made, the worktree path and branch are returned in the result.
Baseline Verification
After creating a worktree, always verify the baseline:
# Ensure tests pass in the clean worktree before making changes
cd ../project-worktree
# Run the project's test suite
# If tests fail here, the problem is pre-existing — do not mask it
Dependency Detection
Some worktrees need dependency installation:
| Project Type | Check For | Install Command |
|---|---|---|
| Node.js | package.json |
npm install or bun install |
| Python | requirements.txt / pyproject.toml |
pip install -r requirements.txt or uv sync |
| Rust | Cargo.toml |
cargo build |
| Go | go.mod |
go mod download |
Rules
- Never delete worktrees with uncommitted changes — commit or stash first
- Never checkout the same branch in multiple worktrees
- Always clean up worktrees when done to avoid disk bloat
- Always verify baseline tests pass before starting work