Skip to main content

​
What are Git Worktrees?

Git worktrees allow you to check out multiple branches from the same repository simultaneously. Each worktree is a separate working directory linked to the same .git repository, enabling you to work on different branches in parallel without switching contexts.

​
Why Use Worktrees?

​
Traditional Workflow Pain Points

In a traditional git workflow, switching branches requires:
  1. Stashing changes - Save your uncommitted work
  2. Switching branches - git checkout other-branch
  3. Losing context - Your editor state, running servers, and mental model reset
  4. Reinstalling dependencies - If package.json changed between branches

​
Worktree Advantages

No Context Switching

Keep multiple branches active simultaneously. Your editor, terminal, and mental model stay intact.

Parallel Development

Work on multiple features, bug fixes, or experiments at the same time without conflicts.

Independent Dependencies

Each worktree has its own node_modules, avoiding version conflicts when switching between branches.

Clean Separation

Physically separate directories make it impossible to accidentally commit changes to the wrong branch.

​
How GWTree Manages Worktrees

GWTree automates the entire worktree creation workflow. Here’s what happens under the hood:

​
Repository Structure

When you create a worktree with GWTree, it follows a predictable naming pattern: 
parent-directory/
├── my-repo/              # Main repository (origin)
├── my-repo-feature-auth/ # Worktree for auth feature
├── my-repo-api/          # Worktree for API work
└── my-repo-dashboard/    # Worktree for dashboard UI
Each worktree:
  • Lives in the same parent directory as the main repo
  • Has its own working directory and files
  • Shares the same .git database (saves disk space)
  • Can be opened in separate editor windows

​
Automatic Branch Management

GWTree handles branch conflicts automatically: 
// From src/commands/create.ts:234-237
let newBranchForWorktree = branchName;
let counter = 1;
while (branches.includes(newBranchForWorktree)) {
  newBranchForWorktree = `${branchName}-${counter}`;
  counter++;
}
If you try to create a worktree with branch name feature but that branch already exists, GWTree automatically names it feature-1, feature-2, etc.

​
Repository Preparation

Before creating a worktree, GWTree ensures your repository is in a clean state:
1

Stash uncommitted changes

Saves your work in progress so you don’t lose any changes
git stash
2

Switch to main branch

Ensures the worktree branches from your primary branch
git checkout main
3

Pull latest changes

Updates your local main branch to match the remote
git pull --rebase origin main
4

Prune stale worktrees

Removes references to worktrees that no longer exist
git worktree prune

​
Real-World Example

Traditional workflow: 
# You're working on feature-auth
git stash
git checkout main
git pull
git checkout -b hotfix-login
# Fix the bug
git checkout feature-auth
git stash pop
# Resume work, hope nothing broke
With worktrees: 
# You're working in my-repo-feature-auth/
gwt hotfix-login
cd ../my-repo-hotfix-login
# Fix the bug in separate directory
# feature-auth work is untouched

​
Disk Space Efficiency

Worktrees share the repository’s .git database: 
my-repo/.git/          # 150 MB - Shared database
my-repo-auth/          # 5 MB  - Just working files
my-repo-api/           # 5 MB  - Just working files
my-repo-dashboard/     # 5 MB  - Just working files
Three worktrees add only ~15 MB, not 450 MB (3 × 150 MB) if you cloned separately.

​
When to Use Worktrees

Perfect for:
  • Running multiple AI coding agents in parallel
  • Comparing implementations side-by-side
  • Testing features while developing others
  • Emergency bug fixes during feature development
  • Code review while preserving your work
Not ideal for:
  • Single-task, linear workflows
  • Very large repositories (>1 GB) where each worktree copy is expensive
  • Teams unfamiliar with git worktrees (requires learning curve)

​
Learn More

Multi-Agent Workflow

Learn how to run Claude Code, Command Code, and Cursor in parallel using worktrees