Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ahmadawais/gwtree/llms.txt

Use this file to discover all available pages before exploring further.

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us