Scenario
AI development has a context-switching problem. For ex: you’re deep in a dev session that understands your codebase perfectly, then a critical bug forces you to git stash, git checkout main, wait for IDE reindexing, and lose all AI context. By the time you switch back, you’re starting from scratch.
What Are Git Worktrees?
Git worktrees let you have multiple working directories for the same repository, each checked out to different branches. Instead of switching branches in one directory, you work in separate directories simultaneously.
1
2
3
4
5
6
7
8
9
10
11
12
13
| # Traditional structure
project/
├── .git/ # Full repository metadata
├── src/ # Working files - destroyed on branch switch
└── node_modules/ # Dependencies - rebuilt constantly
# Worktree structure
project/
├── .git/ # Shared repository metadata
└── worktrees/
├── main/ # Main branch - permanent
├── feature-a/ # Feature A - isolated
└── hotfix-b/ # Hotfix B - parallel work
|
Benefits:
- Each directory maintains independent state
- IDE sees separate projects
- AI assistants maintain separate contexts
- Build tools run independently
Quick Start
Create isolated environments for parallel work:
1
2
3
4
5
6
7
8
9
10
11
| # Create worktree for new feature
git worktree add ../feature-oauth feature/oauth-integration
# Create worktree for existing branch
git worktree add ../hotfix-ssl hotfix/ssl-certificate-renewal
# List all your active worktrees
git worktree list
# /project-main abcd123 [main]
# /project-feature-oauth efgh456 [feature/oauth-integration]
# /project-hotfix-ssl ijkl789 [hotfix/ssl-certificate-renewal]
|
Each directory is completely independent. Start Claude Code in /project-feature-oauth and that session remembers everything about OAuth. Switch to /project-hotfix-ssl for a fresh Claude session focused on SSL issues.
Automation Script
Save time with this automation script:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
| #!/bin/bash
# Smart worktree manager
w() {
local project=$(basename "$PWD")
local branch=$1
local worktree_path="../$project-$branch"
if [[ -z "$branch" ]]; then
echo "Usage: w <branch-name>"
return 1
fi
# Auto-create worktree if it doesn't exist
if [[ ! -d "$worktree_path" ]]; then
echo "Creating worktree for branch: $branch"
git worktree add -b "$branch" "$worktree_path" 2>/dev/null || \
git worktree add "$worktree_path" "$branch"
# Copy environment files
cp .env* "$worktree_path/" 2>/dev/null || true
# Copy dependencies efficiently
[[ -d "node_modules" ]] && cp -al node_modules "$worktree_path/" 2>/dev/null || true
fi
cd "$worktree_path"
}
# Usage:
# w auth-feature # Create and switch to auth feature worktree
# w bug-fix-ssl # Create and switch to SSL bugfix worktree
|
Run w branch-name to create and switch to a worktree. The script auto-creates worktrees, copies environment files, and handles dependencies efficiently.
Storage efficiency
Storage efficiency through shared Git metadata:
1
2
3
4
5
6
7
8
9
10
11
| # Traditional: Multiple clones
project-main/ 850MB
project-feature/ 850MB
project-hotfix/ 850MB
Total: 2.55GB
# Worktrees: Shared .git
project/.git/ 250MB (shared)
main/ 150MB
feature/ 151MB
hotfix/ 149MB
|
When to Use Worktrees
- AI-assisted development (context preservation)
- Large codebases (slow IDE reindexing)
- Parallel feature development
- Complex build dependencies
Quick Reference
Essential Commands
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| # Create worktree for new branch
git worktree add ../feature-auth feature/auth
# Create worktree for existing branch
git worktree add ../hotfix-ssl hotfix/ssl-fix
# List active worktrees
git worktree list
# Remove completed worktree
git worktree remove ../feature-auth
# Prune deleted worktrees
git worktree prune
|