Using Git Worktrees

main-repo/           # Main working directory (main branch)
├── src/
├── tests/
└── ...

worktrees/
├── feature-a/       # Worktree for feature-a branch
└── feature-b/       # Worktree for feature-b branch

Basic Commands

Create a Worktree

# Create new branch in new worktree
git worktree add ../my-feature -b feature/my-feature

# Create worktree from existing branch
git worktree add ../existing-feature feature/existing-feature

# Create worktree for a PR
git worktree add ../pr-123 pr/123

List Worktrees

git worktree list

# Output:
# /path/to/main-repo        abc1234 [main]
# /path/to/my-feature       def5678 [feature/my-feature]
# /path/to/existing-feature ghi9012 [feature/existing-feature]

Remove a Worktree

# Remove worktree after branch is merged
git worktree remove ../my-feature

# Force remove if untracked files
git worktree remove --force ../my-feature

Workflow Patterns

Pattern 1: Hotfix While Developing

# You're working on feature-A
cd ~/projects/my-app

# Urgent bug comes in - create worktree for hotfix
git worktree add ../my-app-hotfix -b hotfix/urgent-fix

# Switch to hotfix
cd ../my-app-hotfix

# Make fix, then commit using the finishing-a-development-branch skill
# (Do NOT run `git add` or `git commit` directly — use the skill)
git push origin hotfix/urgent-fix

# Return to feature work
cd ../my-app

# Clean up after hotfix merges
git worktree remove ../my-app-hotfix

Pattern 2: PR Review While Developing

# Create worktree to review PR
git worktree add ../pr-review pr/123

cd ../pr-review

# Run tests, review code
rtk bun test (or rtk npm test)
rtk bun run lint (or rtk npm run lint)

# Return to your work
cd ../my-app

# Clean up
git worktree remove ../pr-review

Pattern 3: Parallel Features

# Main repo: feature-a
cd ~/projects/my-app
# Working on feature A...

# Create worktree for feature-b
git worktree add ../my-app-feature-b -b feature/b

# Create another for spike
git worktree add ../my-app-spike -b spike/refactor-auth

# Can now switch between contexts instantly
cd ../my-app-feature-b  # Work on feature B
cd ../my-app-spike      # Work on spike
cd ../my-app            # Back to feature A

Worktree Directory Structure

project/
├── .git/                    # Git directory
├── src/                     # Main branch files
└── ...

# Worktrees (can be anywhere)
../project-feature-a/
├── .git                     # File pointing to main .git
├── src/                     # Feature-a branch files
└── ...

../project-feature-b/
├── .git                     # File pointing to main .git
├── src/                     # Feature-b branch files
└── ...

Tips for Managing Worktrees

Naming Convention

# Include project name and branch name
git worktree add ../myapp-feature-auth feature/auth
git worktree add ../myapp-hotfix-123 hotfix/issue-123

Shared Dependencies

# If using Node.js, each worktree needs its own node_modules
cd ../myapp-feature-auth
rtk bun install (or rtk npm install)

# Or use workspaces for shared dependencies

IDE Setup

# Each worktree can be opened in its own IDE window
code ../myapp-feature-auth
code ../myapp-feature-b

# Or use multi-root workspace

Best Practices

1. Clean up after merging - Remove worktrees when branches are deleted
2. Use descriptive names - Include project and branch in worktree name
3. Keep worktrees nearby - Use consistent parent directory
4. Document active worktrees - Keep a note of what's where

Common Issues

Issue: "already checked out"

$ git worktree add ../feature feature/my-feature