NeoLabHQ/git-worktrees

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

# Create worktree with existing branch
git worktree add ../feature-x feature-x

# Create worktree with new branch from current HEAD
git worktree add -b new-feature ../new-feature

# Create worktree with new branch from specific commit
git worktree add -b hotfix-123 ../hotfix origin/main

# Create worktree tracking remote branch
git worktree add --track -b feature ../feature origin/feature

# Create worktree with detached HEAD (for experiments)
git worktree add --detach ../experiment HEAD~5

List Worktrees

# Simple list
git worktree list

# Verbose output with additional details
git worktree list -v

# Machine-readable format (for scripting)
git worktree list --porcelain

Example output:

/home/user/project           abc1234 [main]
/home/user/project-feature   def5678 [feature-x]
/home/user/project-hotfix    ghi9012 [hotfix-123]

Remove a Worktree

# Remove worktree (working directory must be clean)
git worktree remove ../feature-x

# Force remove (discards uncommitted changes)
git worktree remove --force ../feature-x

Move a Worktree

# Relocate worktree to new path
git worktree move ../old-path ../new-path

Lock/Unlock Worktrees

# Lock worktree (prevents pruning if on removable storage)
git worktree lock ../feature-x
git worktree lock --reason "On USB drive" ../feature-x

# Unlock worktree
git worktree unlock ../feature-x

Prune Stale Worktrees

# Remove stale worktree metadata (after manual directory deletion)
git worktree prune

# Dry-run to see what would be pruned
git worktree prune --dry-run

# Verbose output
git worktree prune -v

Repair Worktrees

# Repair worktree links after moving directories manually
git worktree repair

# Repair specific worktree
git worktree repair ../feature-x

Workflow Patterns

Pattern 1: Feature + Hotfix in Parallel

To fix a bug while feature work is in progress:

# Create worktree for hotfix from main
git worktree add -b hotfix-456 ../project-hotfix origin/main

# Switch to hotfix directory, fix, commit, push
cd ../project-hotfix
git add . && git commit -m "fix: resolve critical bug #456"
git push origin hotfix-456

# Return to feature work
cd ../project

# Clean up when done
git worktree remove ../project-hotfix

Pattern 2: PR Review While Working

To review a PR without affecting current work:

# Fetch PR branch and create worktree
git fetch origin pull/123/head:pr-123
git worktree add ../project-review pr-123

# Review: run tests, inspect code
cd ../project-review

# Return to work, then clean up
cd ../project
git worktree remove ../project-review
git branch -d pr-123

Pattern 3: Compare Implementations

To compare code across branches side-by-side:

# Create worktrees for different versions
git worktree add ../project-v1 v1.0.0
git worktree add ../project-v2 v2.0.0

# Diff, compare, or run both simultaneously
diff ../project-v1/src/module.js ../project-v2/src/module.js

# Clean up
git worktree remove ../project-v1
git worktree remove ../project-v2

Pattern 4: Long-Running Tasks

To run tests/builds in isolation while continuing development:

# Create worktree for CI-like testing
git worktree add ../project-test main

# Start long-running tests in background
cd ../project-test && npm test &

# Continue development in main worktree
cd ../project

Pattern 5: Stable Reference

To maintain a clean main checkout for reference:

# Create permanent worktree for main branch
git worktree add ../project-main main

# Lock to prevent accidental removal
git worktree lock --reason "Reference checkout" ../project-main

Pattern 6: Selective Merging from Multiple Features

To combine specific changes from multiple feature branches:

# Create worktrees for each feature to review
git worktree add ../project-feature-1 feature-1
git worktree add ../project-feature-2 feature-2

# Review changes in each worktree
diff ../project/src/module.js ../project-feature-1/src/module.js
diff ../project/src/module.js ../project-feature-2/src/module.js

# From main worktree, selectively take changes
cd ../project
git checkout feature-1 -- src/moduleA.js src/utils.js
git checkout feature-2 -- src/moduleB.js
git commit -m "feat: combine selected changes from feature branches"

# Or cherry-pick specific commits
git cherry-pick abc1234  # from feature-1
git cherry-pick def5678  # from feature-2

# Clean up
git worktree remove ../project-feature-1
git worktree remove ../project-feature-2

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:

# Compare specific file between worktrees
diff ../project-main/src/app.js ../project-feature/src/app.js

# Use git diff to compare branches (works from any worktree)
git diff main..feature-branch -- src/app.js

# Visual diff with your preferred tool
code --diff ../project-main/src/app.js ../project-feature/src/app.js

# Compare entire directories
diff -r ../project-v1/src ../project-v2/src

Merge Only One File from a Worktree

You can selectively bring a single file from another branch using git checkout:

# In your current branch, get a specific file from another branch
git checkout feature-branch -- path/to/file.js

# Or get it from a specific commit
git checkout abc1234 -- path/to/file.js

# Get multiple specific files
git checkout feature-branch -- src/module.js src/utils.js

For partial file changes (specific hunks/lines only):

# Interactive patch mode - select which changes to take
git checkout -p feature-branch -- path/to/file.js

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:

# Find the commit hash (from any worktree or git log)
git log feature-branch --oneline

# Cherry-pick specific commit into your current branch
git cherry-pick abc1234

# Cherry-pick multiple commits
git cherry-pick abc1234 def5678

# Cherry-pick a range of commits
git cherry-pick abc1234^..def5678

# Cherry-pick without committing (stage changes only)
git cherry-pick --no-commit abc1234

Merge Changes from Multiple Worktrees

You can merge or cherry-pick from multiple branches:

# Merge multiple branches sequentially
git merge feature-1
git merge feature-2

# Or use octopus merge for multiple branches at once
git merge feature-1 feature-2 feature-3

# Cherry-pick commits from multiple branches
git cherry-pick abc1234  # from feature-1
git cherry-pick def5678  # from feature-2

Selective Merging - Pick Which Changes to Include

Option 1: Selective File Checkout

# Get specific files from different branches
git checkout feature-1 -- src/moduleA.js
git checkout feature-2 -- src/moduleB.js
git commit -m "Merge selected files from feature branches"

Option 2: Interactive Patch Selection

# Select specific hunks from a file
git checkout -p feature-1 -- src/shared.js

Option 3: Cherry-Pick with Selective Staging

# Apply changes without committing
git cherry-pick --no-commit abc1234

# Unstage what you don't want
git reset HEAD -- unwanted-file.js
git checkout -- unwanted-file.js

# Commit only what you kept
git commit -m "Selected changes from feature-1"

Option 4: Merge with Manual Selection

# Start merge but don't auto-commit
git merge --no-commit feature-1

# Review and modify staged changes
git status
git reset HEAD -- file-to-exclude.js
git checkout -- file-to-exclude.js

# Commit your selection
git commit -m "Merge selected changes from feature-1"

Option 5: Using git restore (Git 2.23+)

# Restore specific file from another branch
git restore --source=feature-branch -- path/to/file.js

# Interactive restore with patch selection
git restore -p --source=feature-branch -- path/to/file.js

Directory Structure Conventions

Organize worktrees predictably:

~/projects/
  myproject/              # Main worktree (main/master branch)
  myproject-feature-x/    # Feature branch worktree
  myproject-hotfix/       # Hotfix worktree
  myproject-review/       # Temporary PR review worktree

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:

# Find where the branch is checked out
git worktree list

# Either work in that worktree or remove it first
git worktree remove ../other-worktree

Issue: Stale worktree after manual deletion

Cause: Deleted worktree directory without using git worktree remove.

Solution:

# Clean up stale metadata
git worktree prune

Issue: Worktree moved manually

Cause: Moved worktree directory without using git worktree move.

Solution:

# Repair the worktree links
git worktree repair
# Or specify the new path
git worktree repair /new/path/to/worktree

Issue: Worktree on removed drive

Cause: Worktree was on removable storage that's no longer connected.

Solution:

# If temporary, lock it to prevent pruning
git worktree lock ../usb-worktree

# If permanent, prune it
git worktree prune

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:

# Create worktree for isolated task
git worktree add -b task-123 ../project-task-123
cd ../project-task-123
# Make changes, run tests, return
cd ../project

To experiment safely with detached HEAD:

# Create detached worktree (no branch to clean up)
git worktree add --detach ../project-experiment
cd ../project-experiment
# Experiment, then discard or commit to new branch
git worktree remove --force ../project-experiment

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:

   diff <worktree1>/<path> <worktree2>/<path>
   # Or for unified diff format:
   diff -u <worktree1>/<path> <worktree2>/<path>
   

   For directories between worktrees:

   diff -r <worktree1>/<directory> <worktree2>/<directory>
   # Or for summary only:
   diff -rq <worktree1>/<directory> <worktree2>/<directory>
   

   For branch-level comparison (using git diff):

   git diff <branch1>..<branch2> -- <path>
   # Or for stat summary:
   git diff --stat <branch1>..<branch2>
   

   For comparing with current working directory:

   diff <current-file> <other-worktree>/<file>
   

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:

/home/user/project           abc1234 [main]
/home/user/project-feature   def5678 [feature-x]
/home/user/project-hotfix    ghi9012 [hotfix-123]

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:

> /worktrees compare src/app.js
# Prompts to select which worktree to compare with
# Shows diff of src/app.js between current and selected worktree

Compare between two specific worktrees:

> /worktrees compare ../project-main ../project-feature src/module.js
# Compares src/module.js between the two specified worktrees

Compare multiple files/directories:

> /worktrees compare src/app.js src/utils/ package.json
# Shows diffs for all three paths between worktrees

Compare entire directories:

> /worktrees compare src/
# Shows all differences in src/ directory between worktrees

Get summary statistics:

> /worktrees compare --stat
# Shows which files differ and line counts

Interactive mode:

> /worktrees compare
# Lists available worktrees
# Asks which to compare
# Asks for specific paths or entire worktree

Compare with branch worktree by branch name:

> /worktrees compare feature-x
# Finds worktree for feature-x branch and compares

Compare specific paths between branch worktrees:

> /worktrees compare main feature-x src/ tests/
# Compares src/ and tests/ directories between main and feature-x worktrees

Output Format

File Comparison Header:

Comparing: src/app.js
  From: /home/user/project (main)
  To:   /home/user/project-feature (feature-x)
---
[diff output]

Summary Output:

Worktree Comparison Summary
===========================
From: /home/user/project (main)
To:   /home/user/project-feature (feature-x)

Files only in main:
  - src/deprecated.js

Files only in feature-x:
  + src/new-feature.js
  + src/new-feature.test.js

Files that differ:
  ~ src/app.js
  ~ src/utils/helpers.js
  ~ package.json

Statistics:
  3 files changed
  2 files added
  1 file removed

Common Workflows

Review Feature Changes

# See what changed in a feature branch
> /worktrees compare --stat
> /worktrees compare src/components/

Compare Implementations

# Compare how two features implemented similar functionality
> /worktrees compare ../project-feature-1 ../project-feature-2 src/auth/

Quick File Check

# Check if a specific file differs
> /worktrees compare package.json

Pre-Merge Review

# Review all changes before merging (compare src and tests together)
> /worktrees compare --stat
> /worktrees compare src/ tests/
# Both src/ and tests/ directories will be compared

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:

# Create worktrees for comparison
> /worktrees create feature-x, main
# Created: ../project-feature-x and ../project-main

# Now compare
> /worktrees compare src/

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 dependencies.

Instructions

CRITICAL: Perform the following steps exactly as described:

1. Current state check: Run git worktree list to show existing worktrees and git status to verify the repository state is clean (no uncommitted changes that might cause issues)

2. Fetch latest remote branches: Run git fetch --all to ensure local has knowledge of all remote branches

3. Parse user input: Determine what the user wants to create:

   • <name>: Create worktree with auto-detected type prefix
   • --list: Just show existing worktrees and exit
   • No input: Ask user interactively for the name

4. Auto-detect branch type from name: Check if the first word is a known branch type. If yes, use it as the prefix and the rest as the name. If no, default to feature/.

   Known types: feature, feat, fix, bug, bugfix, hotfix, release, docs, test, refactor, chore, spike, experiment, review

   Examples:

   • refactor auth system → refactor/auth-system
   • fix login bug → fix/login-bug
   • auth system → feature/auth-system (default)
   • hotfix critical error → hotfix/critical-error

   Name normalization: Convert spaces to dashes, lowercase, remove special characters except dashes/underscores

5. For each worktree to create: a. Branch name construction: Build full branch name from detected type and normalized name:

   • <prefix>/<normalized-name> (e.g., feature/auth-system)

   b. Branch resolution: Determine if the branch exists locally, remotely, or needs to be created:

   • If branch exists locally: git worktree add ../<project>-<name> <branch>
   • If branch exists remotely (origin/<branch>): git worktree add --track -b <branch> ../<project>-<name> origin/<branch>
   • If branch doesn't exist: Ask user for base branch (default: current branch or main/master), then git worktree add -b <branch> ../<project>-<name> <base>

   c. Path convention: Use sibling directory with pattern ../<project-name>-<name>

   • Extract project name from current directory
   • Use the normalized name (NOT the full branch with prefix)
   • Example: feature/auth-system → ../myproject-auth-system

   d. Create the worktree: Execute the appropriate git worktree add command

   e. Dependency detection: Check the new worktree for dependency files and determine if setup is needed:

   • package.json -> Node.js project (npm/yarn/pnpm/bun)
   • requirements.txt or pyproject.toml or setup.py -> Python project
   • Cargo.toml -> Rust project
   • go.mod -> Go project
   • Gemfile -> Ruby project
   • composer.json -> PHP project

   f. Package manager detection (for Node.js projects):

   • bun.lockb -> Use bun install
   • pnpm-lock.yaml -> Use pnpm install
   • yarn.lock -> Use yarn install
   • package-lock.json or default -> Use npm install

   g. Automatic setup: Automatically run dependency installation:

   • cd to worktree and run the detected install command
   • Report progress: "Installing dependencies with [package manager]..."
   • If installation fails, report the error but continue with worktree creation summary

6. Summary: Display summary of created worktrees:

   • Worktree path
   • Branch name (full name with prefix)
   • Setup status (dependencies installed or failed)
   • Quick navigation command: cd <worktree-path>

Worktree Path Convention

Worktrees are created as sibling directories to maintain organization:

~/projects/
  myproject/                # Main worktree (current directory)
  myproject-add-auth/       # Feature branch worktree (feature/add-auth)
  myproject-critical-bug/   # Hotfix worktree (hotfix/critical-bug)
  myproject-pr-456/         # PR review worktree (review/pr-456)

Naming rules:

• Pattern: <project-name>-<name> (uses the name part, NOT the full branch)
• Branch name: <type-prefix>/<name> (e.g., feature/add-auth)
• Directory name uses only the <name> portion for brevity

Examples

Feature worktree (default):

> /worktrees create auth system
# Branch: feature/auth-system
# Creates: ../myproject-auth-system

Fix worktree:

> /worktrees create fix login error
# Branch: fix/login-error
# Creates: ../myproject-login-error

Refactor worktree:

> /worktrees create refactor api layer
# Branch: refactor/api-layer
# Creates: ../myproject-api-layer

Hotfix worktree:

> /worktrees create hotfix critical bug
# Branch: hotfix/critical-bug
# Creates: ../myproject-critical-bug

List existing worktrees:

> /worktrees list
# Shows: git worktree list output

Setup Detection Examples

Node.js project with pnpm:

Detected Node.js project with pnpm-lock.yaml
Installing dependencies with pnpm...
✓ Dependencies installed successfully

Python project:

Detected Python project with requirements.txt
Installing dependencies with pip...
✓ Dependencies installed successfully

Rust project:

Detected Rust project with Cargo.toml
Building project with cargo...
✓ Project built successfully

Common Workflows

Quick Feature Branch

> /worktrees create new dashboard
# Branch: feature/new-dashboard
# Creates worktree, installs dependencies, ready to code

Hotfix While Feature In Progress

# In main worktree, working on feature
> /worktrees create hotfix critical bug
# Branch: hotfix/critical-bug
# Creates separate worktree from main/master
# Fix bug in hotfix worktree
# Return to feature work when done

PR Review Without Stashing

> /worktrees create review pr 123
# Branch: review/pr-123
# Creates worktree for reviewing PR
# Can run tests, inspect code
# Delete when review complete

Experiment or Spike

> /worktrees create spike new architecture
# Branch: spike/new-architecture
# Creates isolated worktree for experimentation
# Discard or merge based on results

Important Notes

• Branch lock: Each branch can only be checked out in one worktree at a time. If a branch is already checked out, the command will inform you which worktree has it.

• Shared .git: All worktrees share the same Git object database. Changes committed in any worktree are visible to all others.

• Clean working directory: The command checks for uncommitted changes and warns if present, as creating worktrees is safest with a clean state.

• Sibling directories: Worktrees are always created as sibling directories (using ../) to keep the workspace organized. Never create worktrees inside the main repository.

• Automatic dependency installation: The command automatically detects the project type and package manager, then runs the appropriate install command without prompting.

• Remote tracking: For remote branches, worktrees are created with proper tracking setup (--track flag) so pulls/pushes work correctly.

Cleanup

When done with a worktree, use the proper removal command:

git worktree remove ../myproject-add-auth

Or for a worktree with uncommitted changes:

git worktree remove --force ../myproject-add-auth

Never use rm -rf to delete worktrees - always use git worktree remove.

Troubleshooting

"Branch is already checked out"

• Run git worktree list to see where the branch is checked out
• Either work in that worktree or remove it first

"Cannot create worktree - path already exists"

• The target directory already exists
• Either remove it or choose a different worktree path

"Dependency installation failed"

• Navigate to the worktree manually: cd ../myproject-<name>
• Run the install command directly to see full error output
• Common causes: missing system dependencies, network issues, corrupted lockfile

"Wrong type detected"

• The first word is used as the branch type if it's a known type
• To force a specific type, start with: fix, hotfix, docs, test, refactor, chore, spike, review
• Default type is feature/ when first word isn't a known type

---

How to Merge Worktree

Workflow to help users merge changes from git worktrees into their current branch, supporting multiple merge strategies from simple file checkout to selective cherry-picking.

Instructions

CRITICAL: Perform the following steps exactly as described:

1. Current state check: Run git worktree list to show all existing worktrees and git status to verify working directory state

2. Parse user input: Determine what merge operation the user wants:

   • --interactive or no arguments: Guided interactive mode
   • File/directory path: Merge specific file(s) or directory from a worktree
   • Commit name: Cherry-pick a specific commit
   • Branch name: Merge from that branch's worktree
   • --from <worktree>: Specify source worktree explicitly
   • --patch or -p: Use interactive patch selection mode

3. Determine source worktree/branch: a. If user specified --from <worktree>: Use that worktree path directly b. If user specified a branch name: Find worktree for that branch from git worktree list c. If only one other worktree exists: Ask to confirm using it as source d. If multiple worktrees exist: Present list and ask user which to merge from e. If no other worktrees exist: Explain and offer to use branch-based merge instead

4. Determine merge strategy: Present options based on user's needs:

   Strategy A: Selective File Checkout (for specific files/directories)

   • Best for: Getting complete file(s) from another branch
   • Command: git checkout <branch> -- <path>

   Strategy B: Interactive Patch Selection (for partial file changes)

   • Best for: Selecting specific hunks/lines from a file
   • Command: git checkout -p <branch> -- <path>
   • Prompts user for each hunk: y (apply), n (skip), s (split), e (edit)

   Strategy C: Cherry-Pick with Selective Staging (for specific commits)

   • Best for: Applying a commit but excluding some changes
   • Steps:
     1. git cherry-pick --no-commit <commit>
     2. Review staged changes
     3. git reset HEAD -- <unwanted-files> to unstage
     4. git checkout -- <unwanted-files> to discard
     5. git commit -m "message"

   Strategy D: Manual Merge with Conflicts (for complex merges)

   • Best for: Full branch merge with control over resolution
   • Steps:
     1. git merge --no-commit <branch>
     2. Review all changes
     3. Selectively stage/unstage files
     4. Resolve conflicts if any
     5. git commit -m "message"

   Strategy E: Multi-Worktree Selective Merge (combining from multiple sources)

   • Best for: Taking different files from different worktrees
   • Steps:
     1. git checkout <branch1> -- <path1>
     2. git checkout <branch2> -- <path2>
     3. git commit -m "Merge selected files from multiple branches"

5. Execute the selected strategy:

   • Run pre-merge comparison if user wants to review (suggest /worktrees compare first)
   • Execute git commands for the chosen strategy
   • Handle any conflicts that arise
   • Confirm changes before final commit

6. Post-merge summary: Display what was merged:

   • Files changed/added/removed
   • Source worktree/branch
   • Merge strategy used

7. Cleanup prompt: After successful merge, ask:

   • "Would you like to remove any worktrees to clean up local state?"
   • If yes: List worktrees and ask which to remove
   • Execute git worktree remove <path> for selected worktrees
   • Remind about git worktree prune if needed

Merge Strategies Reference

| Strategy | Use When | Command Pattern | |----------|----------|-----------------| | Selective File | Need complete file(s) from another branch | git checkout <branch> -- <path> | | Interactive Patch | Need specific changes within a file | git checkout -p <branch> -- <path> | | Cherry-Pick Selective | Need a commit but not all its changes | git cherry-pick --no-commit + selective staging | | Manual Merge | Full branch merge with control | git merge --no-commit + selective staging | | Multi-Source | Combining files from multiple branches | Multiple git checkout <branch> -- <path> |

Examples

Merge single file from worktree:

> /worktrees merge src/app.js --from ../project-feature
# Prompts for merge strategy
# Executes: git checkout feature-branch -- src/app.js

Interactive patch selection:

> /worktrees merge src/utils.js --patch
# Lists available worktrees to select from
# Runs: git checkout -p feature-branch -- src/utils.js
# User selects hunks interactively (y/n/s/e)

Cherry-pick specific commit:

> /worktrees merge abc1234
# Detects commit hash
# Asks: Apply entire commit or selective?
# If selective: git cherry-pick --no-commit abc1234
# Then guides through unstaging unwanted changes

Full guided mode:

> /worktrees merge
# Lists all worktrees
# Asks what to merge (files, commits, or branches)
# Guides through appropriate strategy
# Offers cleanup at end

Directory merge with conflicts:

> /worktrees merge src/components/ --from ../project-refactor
# Strategy D: Manual merge with conflicts
# git merge --no-commit refactor-branch
# Helps resolve any conflicts
# Reviews and commits selected changes

Interactive Patch Mode Guide

When using --patch or Strategy B, the user sees prompts for each change hunk:

@@ -10,6 +10,8 @@ function processData(input) {
   const result = transform(input);
+  // Added validation
+  if (!isValid(result)) throw new Error('Invalid');
   return result;
 }
Apply this hunk? [y,n,q,a,d,s,e,?]

| Key | Action | |-----|--------| | y | Apply this hunk | | n | Skip this hunk | | q | Quit (don't apply this or remaining hunks) | | a | Apply this and all remaining hunks | | d | Don't apply this or remaining hunks in this file | | s | Split into smaller hunks | | e | Manually edit the hunk | | ? | Show help |

Cherry-Pick Selective Workflow

For Strategy C (cherry-picking with selective staging):

# 1. Apply commit without committing
git cherry-pick --no-commit abc1234

# 2. Check what was staged
git status

# 3. Unstage files you don't want
git reset HEAD -- path/to/unwanted.js

# 4. Discard changes to those files
git checkout -- path/to/unwanted.js

# 5. Commit the remaining changes
git commit -m "Cherry-pick selected changes from abc1234"

Multi-Worktree Merge Workflow

For Strategy E (merging from multiple worktrees):

# Get files from different branches
git checkout feature-auth -- src/auth/login.js src/auth/session.js
git checkout feature-api -- src/api/endpoints.js
git checkout feature-ui -- src/components/Header.js

# Review all changes
git status
git diff --cached

# Commit combined changes
git commit -m "feat: combine auth, API, and UI improvements from feature branches"

Common Workflows

Take a Feature File Without Full Merge

> /worktrees merge src/new-feature.js --from ../project-feature
# Gets just the file, not the entire branch

Partial Bugfix from Hotfix Branch

> /worktrees merge --patch src/utils.js --from ../project-hotfix
# Select only the specific bug fix hunks, not all changes

Combine Multiple PRs' Changes

> /worktrees merge --interactive
# Select specific files from PR-1 worktree
# Select other files from PR-2 worktree
# Combine into single coherent commit

Pre-Merge Review

# First review what will be merged
> /worktrees compare src/module.js
# Then merge with confidence
> /worktrees merge src/module.js --from ../project-feature

Important Notes

• Working directory state: Always ensure your working directory is clean before merging. Uncommitted changes can cause conflicts.

• Pre-merge review: Consider using /worktrees compare before merging to understand what changes will be applied.

• Conflict resolution: If conflicts occur during merge, the command will help identify and resolve them before committing.

• No-commit flag: Most strategies use --no-commit to give you control over the final commit message and what gets included.

• Shared repository: All worktrees share the same Git object database, so commits made in any worktree are immediately visible to cherry-pick from any other.

• Branch locks: Remember that branches can only be checked out in one worktree at a time. Use branch names for merge operations rather than creating duplicate worktrees.

Cleanup After Merge

After merging, consider cleaning up worktrees that are no longer needed:

# List worktrees
git worktree list

# Remove specific worktree (clean state required)
git worktree remove ../project-feature

# Force remove (discards uncommitted changes)
git worktree remove --force ../project-feature

# Clean up stale worktree references
git worktree prune

The command will prompt you about cleanup after each successful merge to help maintain a tidy workspace.

Troubleshooting

"Cannot merge: working directory has uncommitted changes"

• Commit or stash your current changes first
• Or use git stash before merge, git stash pop after

"Merge conflict in <file>"

• The command will show conflicted files
• Open files and resolve conflicts (look for <<<<<<< markers)
• Stage resolved files with git add <file>
• Continue with git commit

"Commit not found" when cherry-picking

• Ensure the commit hash is correct
• Run git log <branch> in any worktree to find commits
• Commits are shared across all worktrees

"Cannot checkout: file exists in working tree"

• File has local modifications
• Either commit, stash, or discard local changes first
• Then retry the merge operation

"Branch not found for worktree"

• The specified worktree may have been removed
• Run git worktree list to see current worktrees
• Use git worktree prune to clean up stale references

Integration with Other Commands

Pre-merge review:

> /worktrees compare src/
> /worktrees merge src/specific-file.js

Create worktree, merge, cleanup:

> /worktrees create feature-branch
> /worktrees compare src/
> /worktrees merge src/module.js --from ../project-feature-branch
# After merge, cleanup is offered automatically