Skip to main content
Git worktrees revolutionize feature development by giving each feature its own isolated directory. Work on multiple features simultaneously without branch switching, stashing, or context loss.

​
The Problem with Traditional Workflow

Traditional git workflow forces you to:
  • Switch branches constantly
  • Stash uncommitted changes
  • Lose IDE context and open files
  • Reinstall dependencies after switching
  • Close and reopen terminals
Worktrees solve all of this.

​
Feature Development Flow

1

Start a new feature

Create a worktree for your feature:
gwt feature-login
This creates:
  • A new branch: feature-login
  • A new directory: repo-feature-login/
  • Pulls latest from main automatically
Your editor opens automatically (VS Code or Cursor based on your config).
2

Develop in isolation

Work normally in the worktree:
cd repo-feature-login
npm install  # Dependencies specific to this worktree
npm run dev  # Run dev server
Make changes, commit as you go:
git add .
git commit -m "Add login form validation"
3

Switch to another feature

Need to work on something else? Just create another worktree:
gwt hotfix-payment-bug -x
The -x flag skips opening an editor. Your first feature stays untouched:
  • All files exactly as you left them
  • Dev server still running
  • No stashing needed
4

Check status across features

View progress on all your features:
gwt status
Output shows:
  • Uncommitted changes in each worktree
  • Commits ahead/behind main
  • Merge status
5

Complete and merge

When your feature is ready:
# Push your branch
cd repo-feature-login
git push origin feature-login

# Create a PR (optional)
gh pr create --fill

# After PR is approved, merge and cleanup
gwt merge feature-login
The merge command handles everything:
  • Switches to main
  • Merges the branch
  • Removes the worktree
  • Deletes the local branch

​
Common Scenarios

Multiple Related Features

Work on related features in parallel:
gwt user-auth user-profile user-settings -x
Develop all three simultaneously, test interactions between them.

Feature + Hotfix

Feature work interrupted by urgent bug:
# Already working in repo-feature-login
# Create hotfix without disrupting feature
gwt hotfix-critical -x
cd repo-hotfix-critical
# Fix bug, test, commit
git push origin hotfix-critical
gwt merge hotfix-critical
# Return to feature work
cd repo-feature-login
Your feature work remains untouched.

Long-Running Features

Keep long-running feature branches fresh:
cd repo-big-feature
git fetch origin
git rebase origin/main
npm install  # Update dependencies
npm test     # Ensure tests still pass

Experimental Work

Try risky changes without fear:
gwt experiment-new-architecture -x
cd repo-experiment-new-architecture
# Make experimental changes
# If it works, keep it
# If not, just delete the worktree
gwt rm

​
Fast Creation Modes

​
Quick Mode

Create worktree with a single name: 
GWT feature-login  # Creates repo-feature-login with feature-login branch

​
Fast Mode (Skip Prompts)

Use -y to skip all prompts and use saved defaults: 
gwt feature-dashboard -y

​
Batch Mode

Create multiple worktrees at once: 
gwt auth api dashboard tests -x

​
Ultra-Fast Mode

Combine flags for instant creation: 
GWT_EDITOR=none gwt auth api dashboard -y

​
Configuration Tips

Set your preferred editor globally: 
gwt config
Options:
  • code - VS Code
  • cursor - Cursor
  • none - Don’t open editor
  • default - System default
Config stored in ~/.config/gwtree/config.json: 
{
  "editor": "cursor",
  "installDeps": true,
  "lastPm": "npm"
}

​
Cleaning Up

Clean up features that have been merged to main:
gwt clean
Safely removes only merged worktrees.
Start fresh by removing all worktrees:
gwt clean --all
Use with caution - removes all worktrees including unmerged work.
Interactive search and remove:
gwt rm
Select the worktree to remove from a list.
See all your worktrees:
gwt ls

​
Best Practices

Keep main worktree clean - Use the main repository directory for quick checks and worktree management only.
Name worktrees descriptively - Use clear names like feature-user-auth or fix-payment-bug so you know what each worktree contains.
Don’t nest worktrees - Create all worktrees as siblings to your main repository, not inside it.

​
Troubleshooting

Each worktree can run its own dev server on a different port:
# Worktree 1
cd repo-feature-a
PORT=3000 npm run dev

# Worktree 2  
cd repo-feature-b
PORT=3001 npm run dev
Each worktree has its own node_modules:
cd repo-feature-login
rm -rf node_modules
npm install
If you encounter conflicts when merging:
cd repo-feature-login
git fetch origin
git rebase origin/main
# Resolve conflicts
git add .
git rebase --continue

​
Next Steps

Parallel Agents

Run multiple AI agents simultaneously on different features.

Code Review

Review PRs without disrupting your current work.