Git Worktree Complete Guide

📖 What is Git Worktree?

Git Worktree is a Git feature that lets you create multiple working directories (worktrees) in the same repository, each pointing to a different branch or commit.

🔍 Core Concepts

• Main Worktree：The original git repository directory
• Linked Worktree：Additional working directories derived from the main worktree
• Shared .git Directory：All worktrees share the same .git directory

🎯 Why Use Worktree?

✅ Advantages

1. Save Disk Space — Multiple branches share .git directory, avoiding duplicate storage
2. Parallel Development — Work on different branches simultaneously, no switching needed
3. Avoid State Pollution — Each worktree has independent working state
4. Boost Efficiency — No frequent branch switching or rebuilding needed

📊 Disk Space Comparison

Scenario	Traditional	Worktree	Saved
3 branches	300GB	150GB	50%
5 branches	500GB	180GB	64%

🛠️ Basic Operations

1. Create Worktree

# Create worktree for existing branch
git worktree add <path> <branch-name>

# Create worktree for new branch
git worktree add -b <new-branch> <path> <start-point>

# Create worktree for specific commit
git worktree add <path> <commit-hash>

2. List Worktrees

git worktree list

3. Remove Worktree

# Safe removal
git worktree remove <path>

# Force removal (when uncommitted changes exist)
git worktree remove --force <path>

4. Move Worktree

git worktree move <old-path> <new-path>

📋 Practical Examples

Case 1: Parallel Feature Development

# Main worktree: develop trunk features
cd /project/main

# Create worktree for feature1
git worktree add ../feature1 feature/login-redesign

# Create worktree for feature2
git worktree add ../feature2 feature/payment-integration

# Now you can work on three features simultaneously!

Case 2: Fix Production Bug

# Main worktree: continue new feature dev
cd /project/main

# Create worktree for production branch
git worktree add ../hotfix production

# Fix bug in hotfix directory, no impact on main dev
cd ../hotfix

Case 3: Code Review & Testing

# Create worktree for PR branch testing
git worktree add ../pr-test pr/feature-new-api

# Remove after testing
git worktree remove ../pr-test

⚠️ Important Notes

🔧 Advanced Tips

1. Automation Script

#!/bin/bash
# Create dev environment script
create_dev_environment() {
    local repo_path=$1
    local branches=("${@:2}")

    for branch in "${branches[@]}"; do
        local worktree_path="../${branch}-worktree"
        echo "Creating $branch worktree..."
        git worktree add "$worktree_path" "$branch"
    done
}

2. IDE Configuration

• VSCode：Open a separate window for each worktree
• IntelliJ：Open each worktree as an independent project

3. CI/CD Integration

# GitHub Actions example
jobs:
  test-worktrees:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Create worktrees for testing
        run: |
          git worktree add ../feature-a feature/login
          git worktree add ../feature-b feature/payment

💡 Real Case: Project Transformation

Before

Desktop/
├── A-trunk/    (128GB)
├── A-patch/    (97GB)
└── A-Agent/    (99GB)
Total: 324GB

After

Desktop/
├── A-trunk/           (128GB) - Main worktree
├── A-patch-worktree/  (8.8GB) - worktree
└── A-Agent-worktree/  (8.8GB) - worktree
Total: 145.6GB
Saved: 178GB (55%) 🎉

📈 Best Practices

1. Naming Convention

# ✅ Good naming
../feature-login-redesign
../hotfix-production-issue
../release-1.3.0

# ❌ Avoid these
../worktree1
../temp
../test

2. Recommended Directory Structure

project/
├── main/           # Main worktree
├── feature-auth/   # Feature branch worktree
├── hotfix-bug/     # Hotfix worktree
└── release-1.2/    # Release branch worktree

3. Quick Reference

# View help
git worktree --help

# Verbose list
git worktree list --verbose

# Periodically clean unused worktrees
git worktree list | grep -v "main" | awk '{print $1}' | xargs -I {} git worktree remove {}