Skip to main content
Worktrees let you have multiple working directories for the same repository, each on a different branch.

​
Overview

Instead of:
  • Stashing changes
  • Switching branches
  • Switching back
  • Restoring stash
You can:
  • Create a worktree on another branch
  • Work on both simultaneously
  • No context switching overhead

​
Commands

​
Add Worktree

wit worktree add <path> <branch>
Examples: 
# Create worktree for existing branch
wit worktree add ../feature-worktree feature-branch

# Create worktree with new branch
wit worktree add ../hotfix-worktree -b hotfix-123

​
List Worktrees

wit worktree list
Output: 
/home/user/project         a1b2c3d [main]
/home/user/feature-wt      e5f6g7h [feature-branch]
/home/user/hotfix-wt       i9j0k1l [hotfix-123]

​
Remove Worktree

wit worktree remove <path>
Example: 
wit worktree remove ../feature-worktree

​
Prune Stale Entries

wit worktree prune
Removes worktree entries where the directory no longer exists.

​
Workflow Example

​
Scenario: Working on Feature, Need to Hotfix

You’re deep in feature development when a critical bug is reported. Without worktrees: 
wit stash
wit switch main
# fix bug...
wit commit -m "Hotfix"
wit switch feature
wit stash pop
With worktrees: 
# Create a worktree for the hotfix
wit worktree add ../hotfix main

# Work on hotfix in separate directory
cd ../hotfix
# fix bug...
wit commit -m "Hotfix"
wit push

# Back to feature (no context switch!)
cd ../project
# Continue exactly where you left off

# Clean up
wit worktree remove ../hotfix

​
Directory Structure

~/code/
├── my-project/              # Main worktree (main branch)
│   ├── .wit/              # The actual repository
│   ├── src/
│   └── package.json
├── my-project-feature/      # Linked worktree (feature branch)
│   ├── .wit -> link       # Links to main .wit
│   ├── src/
│   └── package.json
└── my-project-hotfix/       # Linked worktree (hotfix branch)
    ├── .wit -> link
    ├── src/
    └── package.json

​
Use Cases

​
Parallel Development

# Work on two features simultaneously
wit worktree add ../feature-a feature-a
wit worktree add ../feature-b feature-b

# Now you have three directories:
# - Main repo (can stay on main)
# - feature-a worktree
# - feature-b worktree

​
Testing Branches

# Create worktree to test a PR
wit worktree add ../pr-123 origin/pr-123

# Test in that directory
cd ../pr-123
npm install
npm test

# Clean up
cd ../project
wit worktree remove ../pr-123

​
Long-running Operations

# Run a long build in a worktree
wit worktree add ../build-wt main
cd ../build-wt
npm run build:production &

# Continue working in main worktree
cd ../project
# Edit files, make commits, etc.

​
Code Review

# Review someone's branch
wit worktree add ../review origin/teammate-feature

# Open in IDE, review, then clean up
wit worktree remove ../review

​
Best Practices

Use consistent namingName worktrees clearly:
wit worktree add ../project-feature feature-x
wit worktree add ../project-hotfix hotfix-123
Clean up when doneDon’t leave worktrees lying around:
wit worktree list
wit worktree remove ../old-worktree
Share node_modules (optional)For JavaScript projects, symlink node_modules:
cd ../new-worktree
ln -s ../main-project/node_modules node_modules

​
Limitations

  • Each branch can only be checked out in one worktree
  • The main worktree cannot be removed
  • All worktrees share the same .wit directory

​
Worktrees vs Other Approaches

ApproachProsCons
WorktreesNo context switch, parallel workDisk space
StashingNo extra directoriesManual, error-prone
CloneComplete isolationSeparate repo, sync issues
Auto-stashAutomaticStill switches context

​
Troubleshooting

A branch can only be in one worktree:
fatal: 'feature' is already checked out at '/path/to/worktree'
Remove the existing worktree or use a different branch.
Remove or choose a different path:
rm -rf ../old-worktree
wit worktree add ../old-worktree branch
If you deleted a worktree directory manually:
wit worktree prune