worktrees_skill

Overview

This skill teaches how to use Git worktrees to work on multiple branches at the same time by creating separate working directories that share the same repository. It focuses on practical commands, common workflow patterns, and troubleshooting tips so you can context-switch without stashing or cloning. Ideal for parallel feature development, PR reviews, isolated testing, and comparing implementations side-by-side.

How this skill works

The skill explains how git worktree creates linked directories that share the same Git object database while keeping one branch checked out per worktree. It covers commands to add, list, move, lock, prune, repair, and remove worktrees, plus patterns for creating new branches or detached HEAD worktrees for experiments. You learn to navigate by changing directories rather than switching branches in a single checkout.

When to use it

• Develop multiple features concurrently without stashing
• Review pull requests without interrupting active work
• Run long tests or CI builds in isolation
• Compare two branch implementations side-by-side
• Maintain a stable reference checkout while developing elsewhere
• Experiment with risky changes using detached HEAD worktrees

Best practices

• Create sibling directories (e.g., ../project-feature) for predictable navigation
• Name worktrees by purpose or branch for clarity (project-review, project-hotfix)
• Commit or stash changes before removing worktrees; avoid rm -rf
• Clean up temporary worktrees promptly with git worktree remove
• Use --detach for throwaway experiments to avoid creating unused branches
• Run git worktree list before checking out branches to avoid lock conflicts

Example use cases

• Hotfix while a feature is in progress: add a hotfix worktree from main, fix, push, then remove it
• PR review: fetch the PR branch, add a review worktree, run tests and inspect code without touching your main worktree
• Compare versions: create worktrees for v1 and v2 and diff specific files or run both builds concurrently
• Long-running CI: start tests in a test worktree while continuing development in the main directory
• Agent tasks isolation: create a worktree per agent task to prevent cross-contamination of changes