Use when working on multiple branches simultaneously, context switching without stashing, reviewing PRs while developing, testing in isolation, or comparing implementations across branches - provides git worktree commands and workflow patterns for parallel development with multiple working directori

Git Worktrees Overview Git worktrees enable checking out multiple branches simultaneously in separate directories, all sharing the same repository. Create a worktree instead of stashing changes or cloning separately. Core principle: One worktree per active branch. Switch contexts by changing directories, not branches. Core Concepts Concept Description Main worktree Original working directory from git clone or git init Linked worktree Additional directories created with git worktree add Shared .git All worktrees share same Git object database (no duplication) Branch lock Each branch can only be checked out in ONE worktree at a time Worktree metadata Administrative files in .git/worktrees/ tracking linked worktrees Quick Reference Task Command Create worktree (existing branch) git worktree add <path <branch Create worktree (new branch) git worktree add b <branch <path Create worktree (new branch from ref) git worktree add b <branch <path <start Create detached worktree git worktree add detach <path <commit List all worktrees git worktree list Remove worktree git worktree remove <path Force remove worktree git worktree remove force <path Move worktree git worktree move <old <new Lock worktree git worktree lock <path Unlock worktree git worktree unlock <path Prune stale worktrees git worktree prune Repair worktree links git worktree repair Compare files between worktrees diff ../worktree a/file ../worktree b/file Get one file from another branch git checkout <branch <path Get partial file changes git checkout p <branch <path Cherry pick a commit git cherry pick <commit Cherry pick without committing git cherry pick no commit <commit Merge without auto commit git merge no commit <branch Essential Commands Create a Worktree List Worktrees Example output: Remove a Worktree Move a Worktree Lock/Unlock Worktrees Prune Stale Worktrees Repair Worktrees Workflow Patterns Pattern 1: Feature + Hotfix in Parallel To fix a bug while feature work is in progress: Pattern 2: PR Review While Working To review a PR without affecting current work: Pattern 3: Compare Implementations To compare code across branches side by side: Pattern 4: Long Running Tasks To run tests/builds in isolation while continuing development: Pattern 5: Stable Reference To maintain a clean main checkout for reference: Pattern 6: Selective Merging from Multiple Features To combine specific changes from multiple feature branches: Comparing and Merging Changes Between Worktrees Since all worktrees share the same Git repository, you can compare files, cherry pick commits, and selectively merge changes between them. Compare and Review File Changes Since worktrees are just directories, you can compare files directly: Merge Only One File from a Worktree You can selectively bring a single file from another branch using git checkout : For partial file changes (specific hunks/lines only): This prompts you to accept/reject each change hunk individually with options: y apply this hunk n skip this hunk s split into smaller hunks e manually edit the hunk Cherry Pick Commits from Worktrees Cherry picking works at the commit level. Since all worktrees share the same repository, you can cherry pick any commit: Merge Changes from Multiple Worktrees You can merge or cherry pick from multiple branches: Selective Merging Pick Which Changes to Include Option 1: Selective File Checkout Option 2: Interactive Patch Selection Option 3: Cherry Pick with Selective Staging Option 4: Merge with Manual Selection Option 5: Using git restore (Git 2.23+) Directory Structure Conventions Organize worktrees predictably: Naming convention: <project <purpose or <project <branch Best Practices Practice Rationale Use sibling directories Keep worktrees at same level as main project for easy navigation Name by purpose project review is clearer than project pr 123 Clean up promptly Remove worktrees when done to avoid confusion Lock remote worktrees Prevent pruning if worktree is on network/USB storage Use detach for experiments Avoid creating throwaway branches Commit before removing Always commit or stash before git worktree remove Common Issues and Solutions Issue: "Branch is already checked out" Cause: Attempting to checkout a branch that's active in another worktree. Solution: Issue: Stale worktree after manual deletion Cause: Deleted worktree directory without using git worktree remove . Solution: Issue: Worktree moved manually Cause: Moved worktree directory without using git worktree move . Solution: Issue: Worktree on removed drive Cause: Worktree was on removable storage that's no longer connected. Solution: Common Mistakes Mistake Fix Using rm rf to delete worktree Always use git worktree remove , then git worktree prune if needed Forgetting branch is locked to worktree Run git worktree list before checkout errors Not cleaning up temporary worktrees Remove worktrees immediately after task completion Creating worktrees in nested locations Use sibling directories ( ../project feature ) not subdirs Moving worktree directory manually Use git worktree move or run git worktree repair after Agent Workflow Integration To isolate parallel agent tasks: To experiment safely with detached HEAD: Verification Checklist Before using worktrees: [ ] Understand that branches can only be checked out in one worktree [ ] Know where worktrees will be created (use sibling directories) [ ] Plan cleanup strategy for temporary worktrees When creating worktrees: [ ] Use descriptive directory names [ ] Verify branch is not already checked out elsewhere [ ] Consider using detach for experiments When removing worktrees: [ ] Commit or stash any uncommitted changes [ ] Use git worktree remove , not rm rf [ ] Run git worktree prune if directory was deleted manually How to Compare Worktrees Workflow to compare files and directories between git worktrees, helping users understand differences in code across branches or worktrees. Instructions CRITICAL: Perform the following steps exactly as described: 1. Current state check : Run git worktree list to show all existing worktrees and their locations 2. Parse user input : Classify each provided argument: No arguments : Interactive mode ask user what to compare stat : Show summary statistics of differences (files changed, insertions, deletions) Worktree path : A path that matches one of the worktree roots from git worktree list Branch name : A name that matches a branch in one of the worktrees File/directory path : A path within the current worktree to compare 3. Determine comparison targets (worktrees to compare): a. If user provided worktree paths: Use those as comparison targets b. If user specified branch names: Find the worktrees for those branches from git worktree list c. If only one worktree exists besides current: Use current and that one as comparison targets d. If multiple worktrees exist and none specified: Present list and ask user which to compare e. If no other worktrees exist: Offer to compare with a branch using git diff 4. Determine what to compare (files/directories within worktrees): a. If user specified file(s) or directory(ies) paths: Compare ALL of them b. If no specific paths given: Ask user: "Compare entire worktree?" or "Compare specific files/directories? (enter paths)" 5. Execute comparison : For specific files between worktrees: For directories between worktrees: For branch level comparison (using git diff): For comparing with current working directory: 6. Format and present results : Show clear header indicating what's being compared For large diffs, offer to show summary first Highlight significant changes (new files, deleted files, renamed files) Provide context about the branches each worktree contains Comparison Modes Mode Description Command Pattern File diff Compare single file between worktrees diff u <wt1 /file <wt2 /file Directory diff Compare directories recursively diff r <wt1 /dir <wt2 /dir Summary only Show which files differ (no content) diff rq <wt1 / <wt2 / Git diff Use git's diff (branch based) git diff branch1..branch2 path Stat view Show change statistics git diff stat branch1..branch2 Worktree Detection The command finds worktrees using git worktree list : From this output, the command extracts: Path : The absolute path to the worktree directory Branch : The branch name in brackets (used when user specifies branch name) Examples Compare specific file between worktrees: Compare between two specific worktrees: Compare multiple files/directories: Compare entire directories: Get summary statistics: Interactive mode: Compare with branch worktree by branch name: Compare specific paths between branch worktrees: Output Format File Comparison Header: Summary Output: Common Workflows Review Feature Changes Compare Implementations Quick File Check Pre Merge Review Important Notes Argument detection : The command auto detects argument types by comparing them against git worktree list output: Paths matching worktree roots → treated as worktrees to compare Names matching branches in worktrees → treated as worktrees to compare Other paths → treated as files/directories to compare within worktrees Multiple paths : When multiple file/directory paths are provided, ALL of them are compared between the selected worktrees (not just the first one). Worktree paths : When specifying worktrees, use the full path or relative path from current directory (e.g., ../project feature ) Branch vs Worktree : If you specify a branch name, the command looks for a worktree with that branch checked out. If no worktree exists for that branch, it suggests using git diff instead. Large diffs : For large directories, the command will offer to show a summary first before displaying full diff output. Binary files : Binary files are detected and reported as "Binary files differ" without showing actual diff. File permissions : The diff will also show changes in file permissions if they differ. No worktrees : If no other worktrees exist, the command will explain how to create one and offer to use git diff for branch comparison instead. Integration with Create Worktree Use /worktrees create first to set up worktrees for comparison: Troubleshooting "No other worktrees found" Create a worktree first with /worktrees create <branch Or use git diff for branch only comparison without worktrees "Worktree for branch not found" The branch may not have a worktree created Run git worktree list to see available worktrees Create the worktree with /worktrees create <branch "Path does not exist in worktree" The specified file/directory may not exist in one of the worktrees This could indicate the file was added/deleted in one branch The command will report this in the comparison output How to Create Worktree Workflow to create and setup git worktrees for parallel development, with automatic detection and installation of project

git-worktrees