Git Worktree Manager

Manage git worktrees to enable efficient multi-branch development while keeping the main working directory clean.

Purpose

Enable parallel development on multiple branches without switching contexts, allowing isolation and organization of work across multiple features, bugfixes, and experiments.

When to Use

Use this skill when:

Creating Worktrees: Setting up worktrees for new feature branches
Organizing Worktrees: Structuring worktree directories for better management
Cleaning Up: Removing unused or orphaned worktrees
Multi-Branch Development: Working on multiple features simultaneously
Isolated Development: Keeping experimental changes separate from main work
CI/CD Workflows: Using worktrees for testing and deployment
Worktree Maintenance: Listing, switching, and managing multiple worktrees

Worktree Fundamentals

What is a Git Worktree?

A git worktree is a linked working tree attached to the same repository. Each worktree allows you to:

Check out different branches simultaneously
Work on multiple features in parallel
Keep main working directory clean
Test changes without switching branches

Directory Structure

Recommended organization:

project/
├── main-repo/          # Main working directory (default)
└── worktrees/          # All worktrees organized here
    ├── feature/feature-1/
    ├── bugfix/bug-2/
    ├── hotfix/critical-3/
    └── experiment/new-architecture/

Naming Conventions

Branch-Based: Name worktrees after their branches
Type Prefix: Use prefixes for organization (feature/, bugfix/, hotfix/, experiment/)
Descriptive Names: Clear, meaningful names that indicate purpose
No Special Characters: Avoid spaces, special characters in names

Core Operations

1. Create a Worktree

From Existing Branch

bash

# Navigate to main repository
cd /path/to/project

# Create worktree from existing branch
git worktree add ../worktrees/feature-name feature-branch-name

# Verify creation
cd ../worktrees/feature-name
git status

Create New Branch

bash

# Create worktree with new branch
git worktree add -b feature/new-feature ../worktrees/new-feature

# Switch to worktree
cd ../worktrees/new-feature

Detached HEAD Worktree

bash

# Create worktree at specific commit
git worktree add ../worktrees/temp-checkout HEAD~5

2. List Worktrees

Basic Listing

bash

# List all worktrees
git worktree list

# List with porcelain format (machine-readable)
git worktree list --porcelain

Detailed Status Check

bash

# Check status of all worktrees
for wt in $(git worktree list --porcelain | grep worktree | sed 's/worktree //'); do
    echo "=== $wt ==="
    cd "$wt" && git status --short && git log --oneline -1
done

3. Navigate Between Worktrees

Quick Navigation

bash

# Function to navigate to worktree
goto-worktree() {
    local wt=$1
    local project_root=$(git rev-parse --show-toplevel)
    local worktree_path="$project_root/../worktrees/$wt"
    
    if [ -d "$worktree_path" ]; then
        cd "$worktree_path"
        echo "Switched to worktree: $wt"
    else
        echo "Worktree not found: $wt"
    fi
}

Use with Projects

bash

# In .bashrc or .zshrc
alias gwt='goto-worktree'

# Then use:
gwt feature-name

4. Manage Worktree Status

Lock and Unlock

bash

# Lock a worktree (prevent operations)
git worktree lock ../worktrees/feature-name

# Unlock a worktree
git worktree unlock ../worktrees/feature-name

# Check locked status
git worktree list

Prune Worktrees

bash

# Clean up worktree administrative data
git worktree prune

# Prune with verbose output
git worktree prune -v

Worktree Cleanup

Identify Unused Worktrees

Check for Orphaned Worktrees

bash

# Find worktrees with deleted branches
git worktree list | while read path commit branch; do
    if ! git show-ref --verify --quiet "refs/heads/${branch#*/}"; then
        echo "Orphaned: $path ($branch)"
    fi
done

Check for Uncommitted Changes

bash

# List worktrees with uncommitted changes
for wt in $(git worktree list --porcelain | grep worktree | sed 's/worktree //'); do
    if [ -n "$(cd "$wt" && git status --porcelain)" ]; then
        echo "Uncommitted changes: $wt"
    fi
done

Safe Removal

Remove a Worktree

bash

# Safe removal (if clean)
git worktree remove ../worktrees/feature-name

# Force removal (ignores uncommitted changes)
git worktree remove --force ../worktrees/feature-name

Remove Multiple Worktrees

bash

# Remove all worktrees matching pattern
for wt in ../worktrees/feature-*; do
    git worktree remove "$wt"
done

Workflow Integration

Feature Development Workflow

markdown

1. Create worktree for new feature
   ```bash
   git worktree add -b feature/new-ui ../worktrees/feature/new-ui

Develop feature in isolation

bash

cd ../worktrees/feature/new-ui
# ... develop feature ...

Test changes locally
bash
```
cargo test
```

Commit and push to branch

bash

git add .
git commit -m "Implement new UI"
git push

Merge back to main

bash

cd /path/to/main-repo
git checkout main
git merge feature/new-ui

Clean up worktree

bash

git worktree remove ../worktrees/feature/new-ui


### Parallel Testing Workflow
```bash
# Test multiple branches simultaneously
for branch in feature/a feature/b feature/c; do
    git worktree add ../worktrees/$branch $branch
    cd ../worktrees/$branch
    cargo test &
done

# Wait for all tests to complete
wait

Bugfix Workflow

bash

# Create worktree for urgent bugfix
git worktree add -b hotfix/critical-issue ../worktrees/hotfix/critical-issue

# Fix and test in isolation
cd ../worktrees/hotfix/critical-issue
# ... fix bug ...

# Test thoroughly
cargo test

# Merge to release branch
git checkout release/v1.2
git merge hotfix/critical-issue

# Clean up
git worktree remove ../worktrees/hotfix/critical-issue

CI/CD Integration

yaml

# GitHub Actions workflow example
- name: Test with Worktrees
  run: |
    # Create worktree for testing
    git worktree add /tmp/ci-test $GITHUB_SHA
    
    # Run tests in worktree
    cd /tmp/ci-test
    cargo test --all
    
    # Clean up
    rm -rf /tmp/ci-test

Code Review Workflow

bash

# Create worktree for PR review
git worktree add ../worktrees/review/pr-123 origin/pr-123

# Review changes in isolation
cd ../worktrees/review/pr-123
# ... review code ...

# Run tests
cargo test

# Clean up after review
git worktree remove ../worktrees/review/pr-123

Git Configuration

Worktree-Specific Configuration

bash

# Configure behavior in specific worktree
cd ../worktrees/feature-name

# Set up local Git config
git config user.name "Developer Name"
git config user.email "developer@example.com"

# Configure branch-specific settings
git config branch.feature-name.mergeoptions "no-ff"

Aliases for Common Operations

bash

# Add to ~/.gitconfig
[alias]
    wt-list = worktree list
    wt-add = "!f() { git worktree add ../worktrees/$1 ${2:--b $2}; }; f"
    wt-remove = "!f() { git worktree remove ../worktrees/$1; }; f"
    wt-prune = worktree prune

Best Practices

DO:

✓ Organize worktrees in dedicated directory (../worktrees/) ✓ Use descriptive branch names and worktree paths ✓ Clean up worktrees after merging or abandoning work ✓ Test in worktree before merging to main branch ✓ Use worktrees for isolated, parallel development ✓ Prune worktrees regularly to remove orphaned data ✓ Lock worktrees during automated operations ✓ Verify worktree status before major operations

DON'T:

✗ Create worktrees in random locations ✗ Use worktrees as long-term storage (use branches instead) ✗ Leave worktrees with uncommitted changes indefinitely ✗ Forget to prune worktree administrative data ✗ Create worktrees with conflicting branches ✗ Mix worktree and non-worktree workflows without clear separation ✗ Remove worktrees without checking for uncommitted changes ✗ Use worktrees for unrelated changes (keep them focused)

Advanced Patterns

Main Branch Protection

bash

# Keep main branch clean
# Never commit directly to main from worktree
# Always create feature branches from main
# Merge feature branches into main from main checkout

# Example safe workflow:
# 1. In main: create-feature-branch
# 2. In worktree: develop and test
# 3. In main: merge-feature-branch
# 4. Remove worktree

Worktree Isolation

bash

# Each worktree is isolated environment
# No shared state between worktrees
# Each worktree has its own .git/config
# Changes in worktree don't affect main until merged

Stashing in Worktrees

bash

# Stash works independently in each worktree
cd ../worktrees/feature-a
git stash save "WIP feature A"

cd ../worktrees/feature-b
git stash save "WIP feature B"

Submodule Considerations

bash

# Worktrees interact with submodules carefully
# Each worktree has its own submodule checkout
# Be aware of submodule init/update operations

Troubleshooting

Common Issues

Issue: Worktree Already Exists

bash

# Error: fatal: 'worktrees/feature-name' already exists
# Solution: Remove existing worktree first
git worktree remove ../worktrees/feature-name
# Then recreate
git worktree add ../worktrees/feature-name feature-branch-name

Issue: Detached HEAD

bash

# Worktree in detached HEAD state
# Solution: Check out appropriate branch
cd ../worktrees/feature-name
git checkout feature-branch-name

Issue: Merge Conflicts

bash

# Conflicts when merging from worktree
# Solution: Resolve in worktree, then merge
cd ../worktrees/feature-name
git merge main
# Resolve conflicts
git commit
git checkout main
git merge feature-name

Issue: Large .git Directory

bash

# Worktrees can bloat .git directory
# Solution: Use prune regularly
git worktree prune
# Consider using sparse checkout for large repos

Tools and Commands Reference

Quick Reference

bash

# List all worktrees
git worktree list

# Create from branch
git worktree add ../worktrees/name branch-name

# Create with new branch
git worktree add -b new-branch ../worktrees/name

# Remove worktree
git worktree remove ../worktrees/name

# Force remove
git worktree remove --force ../worktrees/name

# Prune administrative data
git worktree prune

# Move a worktree
git worktree move ../worktrees/old-path ../worktrees/new-path

# Lock worktree
git worktree lock ../worktrees/name

# Unlock worktree
git worktree unlock ../worktrees/name

Status Checking

bash

# Check all worktree statuses
git worktree list

# Get detailed information
git worktree list --porcelain

# Find worktree for a branch
git worktree list | grep feature-branch-name

Integration with Development Workflows

With IDE

bash

# VS Code: Add multiple workspace roots
# Settings -> Workspace -> Add Folder...
# Add: /path/to/project, /path/to/worktrees/*

# JetBrains: Configure multiple project roots
# File -> Open -> Add Directory to Project

With Testing

bash

# Parallel test execution
for branch in $(git branch -r | grep -v HEAD); do
    git worktree add /tmp/test-$branch $branch
    cd /tmp/test-$branch && cargo test
    rm -rf /tmp/test-$branch
done

With CI/CD

yaml

# GitHub Actions: Use worktrees for isolated testing
- name: Parallel Testing
  run: |
    for branch in test-1 test-2 test-3; do
      git worktree add /tmp/$branch origin/$branch
      cd /tmp/$branch && cargo test
      rm -rf /tmp/$branch
    done

Maintenance

Regular Cleanup Schedule

Daily: Prune worktrees
Weekly: Check for orphaned worktrees
Monthly: Review and clean up old worktree directories

Monitoring

bash

# Monitor worktree usage
git worktree list | wc -l  # Count active worktrees

# Monitor disk usage
du -sh ../worktrees/

# Check for large .git directories
du -sh .git

Backup Considerations

bash

# Worktrees don't need separate backups
# All data is in shared git repository
# Main worktree is primary working directory
# Worktrees are temporary workspaces

Summary

Git worktrees enable:

Parallel Development: Multiple branches simultaneously
Isolation: Clean main working directory
Flexibility: Easy to create and remove workspaces
Organization: Structured worktree management
Efficiency: Faster context switching between features

Use worktrees for efficient, isolated multi-branch development while maintaining a clean main working directory.

git-worktree-manager

NPX Install

Tags

SKILL.md Content

Git Worktree Manager

Purpose

When to Use

Worktree Fundamentals

What is a Git Worktree?

Directory Structure

Naming Conventions

Core Operations

1. Create a Worktree

From Existing Branch

Create New Branch

Detached HEAD Worktree

2. List Worktrees

Basic Listing

Detailed Status Check

3. Navigate Between Worktrees

Quick Navigation

Use with Projects

4. Manage Worktree Status

Lock and Unlock

Prune Worktrees

Worktree Cleanup

Identify Unused Worktrees

Check for Orphaned Worktrees

Check for Uncommitted Changes

Safe Removal

Remove a Worktree

Remove Multiple Worktrees

Workflow Integration

Feature Development Workflow

Bugfix Workflow

CI/CD Integration

Code Review Workflow

Git Configuration

Worktree-Specific Configuration

Aliases for Common Operations

Best Practices

DO:

DON'T:

Advanced Patterns

Main Branch Protection

Worktree Isolation

Stashing in Worktrees

Submodule Considerations

Troubleshooting

Common Issues

Issue: Worktree Already Exists

Issue: Detached HEAD

Issue: Merge Conflicts

Issue: Large .git Directory

Tools and Commands Reference

Quick Reference

Status Checking

Integration with Development Workflows

With IDE

With Testing

With CI/CD

Maintenance

Regular Cleanup Schedule

Monitoring

Backup Considerations

Summary