nixos/shared/linked-dotfiles/opencode/skills/do-job/references/git-worktree.md

Git Worktree Patterns

Overview

Git worktrees allow multiple working directories from single repository, enabling parallel work on different branches without stashing or switching.

Basic Commands

Create Worktree

# From main/develop branch
cd <repo>/develop
git pull

# Create new worktree
git worktree add <path> -b <branch-name>

List Worktrees

git worktree list

Remove Worktree

# From any location in repo
git worktree remove <path>

# Or manually
rm -rf <path>
git worktree prune

Naming Patterns

Directory Structure

repos/
├── document-api/
│   ├── develop/          # Main worktree
│   ├── fix-permissions/  # Feature worktree
│   └── add-tags/         # Another feature worktree

Branch Naming

Format: <username>/PI-XXXXX_<description>

Examples:

• nate/PI-70535_rename-folder-fix
• nate/PI-70361_upload-permissions
• nate/PI-69924_delete-access-level

Workflow Patterns

Starting Work

# Navigate to develop
cd document-api/develop

# Update develop
git pull

# Create worktree for ticket
git worktree add ../pi-70535-rename-fix -b nate/PI-70535_rename-folder-fix

# Move to worktree
cd ../pi-70535-rename-fix

During Work

# Normal git operations work in worktree
git status
git add .
git commit -m "PI-70535: Fix folder rename permissions"
git push -u origin nate/PI-70535_rename-folder-fix

After PR Merge

# From anywhere in repo
git worktree remove ../pi-70535-rename-fix

# Clean up
git worktree prune
git branch -d nate/PI-70535_rename-folder-fix

# Update develop
cd develop
git pull

Common Issues

Worktree Already Exists

# Error: worktree already exists
# Solution: Remove old worktree first
git worktree remove <path>
git worktree prune

Branch Already Exists

# Error: branch already exists
# Solution: Use existing branch or delete old one
git worktree add <path> <existing-branch>

# Or delete old branch
git branch -D <branch-name>
git worktree add <path> -b <branch-name>

Locked Worktree

# If worktree shows as locked
git worktree unlock <path>
git worktree remove <path>

Orphaned Worktrees

# Clean up references to deleted worktrees
git worktree prune

Best Practices

Keep Worktrees Short-Lived

• Create for specific ticket
• Remove after PR merged
• Don't accumulate many worktrees

Use Descriptive Names

# ❌ Bad
git worktree add ../work -b fix

# ✅ Good
git worktree add ../rename-folder-fix -b nate/PI-70535_rename-folder-fix

Always Branch from Latest

# Update base branch before creating worktree
cd develop
git pull
git worktree add ../feature -b username/PI-XXXXX_feature

Clean Up Regularly

# List all worktrees
git worktree list

# Remove merged/abandoned worktrees
git worktree remove <path>
git worktree prune

Advantages Over Branch Switching

Parallel Work

Work on multiple tickets simultaneously without switching contexts:

Terminal 1: cd document-api/develop    # Review PRs
Terminal 2: cd document-api/feature-1  # Active development
Terminal 3: cd document-api/hotfix     # Emergency fix

Preserve State

Each worktree maintains its own:

• Working directory state
• Staged changes
• Build artifacts
• IDE configuration

Avoid Stashing

No need to stash changes when switching tasks:

# Traditional flow (with stashing)
git stash
git checkout other-branch
# ... do work ...
git checkout original-branch
git stash pop

# Worktree flow (no stashing)
cd ../other-worktree
# ... do work ...
cd ../original-worktree
# Everything still there

Limitations

Shared References

All worktrees share:

• Git objects
• Remote configuration
• Git hooks
• Submodules

Disk Space

Each worktree requires full working directory (but shares .git objects).

Cannot Checkout Same Branch

# Error: branch already checked out
# One branch can only be checked out in one worktree at a time
git worktree add ../dup -b existing-branch  # Fails if already checked out