Git - Worktrees

Main Repository (.git)
├── main-worktree/     (main branch)
├── feature-worktree/  (feature/auth branch)
└── hotfix-worktree/   (hotfix/security branch)

# Create worktree for existing branch
git worktree add ../feature-work feature/authentication

# Create worktree with new branch
git worktree add ../hotfix-work -b hotfix/security-fix

# Create worktree from specific commit
git worktree add ../review-work abc1234

# List all worktrees
git worktree list

# List with verbose details
git worktree list --verbose

# List with porcelain format
git worktree list --porcelain

# Remove worktree (must be clean)
git worktree remove ../feature-work

# Force remove (even with modifications)
git worktree remove --force ../feature-work

# Prune deleted worktrees from list
git worktree prune

# Setup multiple features
git worktree add ../auth-feature -b feature/authentication
git worktree add ../ui-feature -b feature/new-ui
git worktree add ../api-feature -b feature/api-v2

# Work in each directory independently
cd ../auth-feature
# Develop authentication feature

cd ../ui-feature  
# Develop UI improvements

cd ../api-feature
# Develop API changes

# Main development continues
cd main-repo
git checkout main

# Prepare release in separate worktree
git worktree add ../release-v2.0 -b release/v2.0
cd ../release-v2.0

# Stabilize release
git cherry-pick <commit>
git revert <bad-commit>

# Test and package release
npm run build
npm run test

# Continue main development
cd main-repo

# Create hotfix worktree from production
git worktree add ../hotfix-urgent -b hotfix/urgent-fix origin/production

cd ../hotfix-urgent
# Fix critical issue
git add .
git commit -m "Fix critical security vulnerability"

# Deploy hotfix
git push origin hotfix/urgent-fix

# Merge back to main
cd ../main-repo
git merge hotfix/urgent-fix

# Create worktree tracking different remote
git worktree add ../upstream-work -b upstream-main origin/main

# Add another remote in worktree
cd ../upstream-work
git remote add upstream https://github.com/original/project.git
git fetch upstream
git branch --set-upstream-to=upstream/main

# Create temporary worktree for testing
git worktree add --detach ../temp-test HEAD~5

cd ../temp-test
# Test specific commit
make test

# Clean up
cd ../main-repo
git worktree remove ../temp-test

# Create worktree for bisecting
git worktree add ../bisect-work -b bisect-session

cd ../bisect-work
git bisect start
git bisect bad HEAD
git bisect good v1.0

# Continue bisecting in isolation
# while main development continues

# Configure worktree-specific settings
cd ../feature-work
git config core.editor vim
git config user.email [email protected]

# Check configuration
git config --list

# Shared configurations (affects all worktrees)
git config --global user.name "Your Name"
git config branch.main.remote origin

# Worktree-specific configurations
git config --local core.filemode false
git config --local push.default current

# Open different features in separate editors
code ../main-repo        # Main development
code ../feature-work     # Feature development  
code ../release-work     # Release preparation

# Each instance maintains separate:
# - File history
# - Search indexes  
# - Debug sessions
# - Terminal sessions

# Independent build directories
cd ../main-repo
npm run build    # Builds to ./dist

cd ../feature-work  
npm run build    # Builds to ./dist (separate)

# Parallel testing
cd ../main-repo && npm test &
cd ../feature-work && npm test &
wait

# Descriptive worktree names
git worktree add ../main-development main
git worktree add ../feature-auth-system feature/authentication
git worktree add ../release-v2.1-prep release/v2.1
git worktree add ../hotfix-security-patch hotfix/cve-2023-001

# Organized structure
project/
├── main/                 # Main repository
├── worktrees/
│   ├── feature-auth/     # Feature development
│   ├── feature-ui/       # UI improvements
│   ├── release-v2.0/     # Release preparation
│   └── hotfix-urgent/    # Critical fixes
└── builds/
    ├── main/             # Main build outputs
    ├── feature-auth/     # Feature build outputs
    └── release-v2.0/     # Release build outputs

# Regular cleanup script
#!/bin/bash
# cleanup-worktrees.sh

# Remove merged feature worktrees
for worktree in $(git worktree list --porcelain | grep '^worktree' | cut -d' ' -f2)
do
  cd "$worktree"
  branch=$(git branch --show-current)
  
  if git merge-base --is-ancestor HEAD origin/main; then
    echo "Removing merged worktree: $worktree"
    cd ..
    git worktree remove "$worktree"
  fi  
done

# Prune stale worktrees
git worktree prune

# Error: branch is already checked out
git worktree add ../duplicate-work main
# fatal: 'main' is already checked out at '/path/to/main'

# Solution: Use different branch or detached HEAD
git worktree add --detach ../duplicate-work main

# Check worktree disk usage
du -sh ../*/

# Share object database (already shared)
# But working directories are separate

# Clean build artifacts across worktrees
find ../*/node_modules -name "*.cache" -delete
find ../*/dist -type f -delete

# Fix worktree references
git worktree repair

# Remove and recreate problematic worktree
git worktree remove --force ../broken-work
git worktree add ../fixed-work existing-branch

# CI script using worktrees
#!/bin/bash
# ci-parallel-tests.sh

# Create test worktrees
git worktree add ci-unit-tests $COMMIT_SHA
git worktree add ci-integration-tests $COMMIT_SHA  
git worktree add ci-e2e-tests $COMMIT_SHA

# Run tests in parallel
(cd ci-unit-tests && npm run test:unit) &
(cd ci-integration-tests && npm run test:integration) &
(cd ci-e2e-tests && npm run test:e2e) &

wait

# Cleanup
git worktree remove ci-unit-tests
git worktree remove ci-integration-tests  
git worktree remove ci-e2e-tests

# Review script
#!/bin/bash
# review-pr.sh PR_NUMBER

PR_BRANCH="pr-$1"
git fetch origin pull/$1/head:$PR_BRANCH

# Create review worktree
git worktree add ../review-pr-$1 $PR_BRANCH

echo "Review environment ready at ../review-pr-$1"
echo "Compare with main: diff -r . ../review-pr-$1"