Using Git Worktrees

Activates after design approval. Creates isolated workspace on new branch, runs project setup, and verifies clean test baseline for feature work.

Download this Skill

npx degit LangbaseInc/agent-skills/using-git-worktrees my-git-worktrees

What are Git Worktrees?

Git worktrees allow you to have multiple working directories attached to the same repository, each on a different branch.

Benefits

Work on multiple branches simultaneously
No stashing required when switching contexts
Isolated environments for each feature
Fast context switching without checkout delays
Parallel testing across branches
Clean separation of concerns

Common Commands

Create Worktree

# Create new branch and worktree
git worktree add ../feature-branch feature-branch

# Use existing branch
git worktree add ../bugfix bugfix-123

List Worktrees

git worktree list

Remove Worktree

# Remove and clean up
git worktree remove ../feature-branch

# Force remove if needed
git worktree remove --force ../feature-branch

Prune Deleted Worktrees

git worktree prune

Workflow

1. After Design Approval

Design is approved and ready for implementation

2. Create Worktree

git worktree add ../new-feature new-feature
cd ../new-feature

3. Run Project Setup

npm install
# or yarn/pnpm install

4. Verify Clean Baseline

npm test
# Ensure all tests pass before starting

5. Start Feature Work

Work in isolation without affecting main workspace

Best Practices

Name worktrees after feature branches
Keep worktrees in parallel directories
Clean up after merging
Run setup in each worktree
Verify tests before starting work
Use relative paths for portability

Directory Structure

project/
├── main/              # Main worktree
│   └── .git/
├── feature-a/         # Feature worktree
├── feature-b/         # Another feature
└── bugfix-123/        # Bugfix worktree

Use Cases

Working on multiple features
Reviewing PRs without switching
Running tests on different branches
Comparing implementations
Hot-fixing while developing
Maintaining multiple versions

Cleanup

After merging:

# Remove worktree
git worktree remove ../feature-branch

# Delete merged branch
git branch -d feature-branch

Tips

Don't commit directly in worktrees if using shared .git
Each worktree can have its own node_modules
IDE settings may need adjustment
Absolute paths can break between worktrees

Skills