git-worktree（Git 工作树）

Git Worktree - Parallel Development

Overview

Git worktrees enable multiple working directories from a single repository. Each worktree has its own branch while sharing the same Git object database.

Core principle: Check worktree status, create worktree for parallel work, reference cleanup commands as needed.

When to Use

Use worktrees when:

• Working on multiple branches simultaneously
• Emergency hotfix needed without disrupting current work
• Reviewing PRs in isolation
• Testing across branches without stashing

Avoid when:

• Quick branch switch (use git switch instead)
• Single feature, single branch workflow

The Workflow

Step 1: Check Worktree Status

Before creating a worktree, check what already exists:

# List all worktrees
git worktree list

# Verbose output with branch info
git worktree list --verbose

Step 2: Create Worktree

Basic creation:

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

# Create from specific base branch
git worktree add ../project-hotfix -b hotfix-critical origin/main

# Create from existing remote branch
git worktree add ../project-review pr-123

Tip: Place worktrees outside the repo directory (e.g., ../project-feature-name) so they aren't tracked by Git.

Recommended configuration (run once):

git config worktree.guessRemote true
git config worktree.useRelativePaths true  # Requires Git 2.45+

Step 3: Work in Worktree

Navigate to the worktree and work normally:

cd ../project-feature-name
# Install dependencies, run tests, start Claude, etc.

Worktree Management Reference

These commands are available for managing worktrees. Surface these to the user when relevant:

List worktrees:

# List all worktrees
git worktree list

# Verbose output with branch and commit info
git worktree list --verbose

Remove worktrees:

# Remove a worktree (must have no uncommitted changes)
git worktree remove ../project-feature-name

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

Prune stale worktrees:

# Clean up metadata for manually deleted worktrees
git worktree prune

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

# Repair a disconnected worktree
git worktree repair ../project-feature-name

Troubleshooting

"Another worktree already uses this branch"

Cause: Can't checkout same branch in multiple worktrees.

Solution:

# Check which worktree has it
git worktree list | grep branch-name

# Create new branch from same base instead
git worktree add ../new-path -b branch-copy origin/branch-name

"Worktree contains modified or untracked files"

Cause: Can't remove worktree with uncommitted changes.

Solution:

# Commit or stash changes first
cd ../project-feature-name
git add . && git commit -m "Final changes"

# Or force remove (discards changes)
git worktree remove -f ../project-feature-name

Stale Worktree References

Cause: Manually deleted worktree directory without git worktree remove.

Solution:

# List worktrees (shows "prunable" entries)
git worktree list --verbose

# Clean up stale metadata
git worktree prune

Examples

Example 1: Create worktree for new feature

Create worktree with descriptive branch name

git worktree add../myproject-auth -b feature/auth cd../myproject-auth

Install dependencies and verify setup

npm install npm test

**Why this is good:** Checks existing worktrees, uses descriptive naming, verifies setup before work.
</Good>

<Bad>

Create worktree without checking existing ones

git worktree add ../temp -b temp cd ../temp

**Why this is bad:** No verification of existing worktrees, vague naming makes tracking difficult, no setup verification.

### Example 2: Emergency hotfix pattern

# Fix bug, test, commit

npm test git add. git commit -m "Fix payment processor race condition" git push -u origin hotfix/payment-bug

# Return to original work

cd../myproject git worktree remove../myproject-hotfix

Why this is good: Branches from correct base (main), tests before committing, cleans up after. </Good>

<Bad>

# Create hotfix from current feature branch
git worktree add ../fix -b fix
cd ../fix
# Make changes, forget to clean up

Why this is bad: Wrong base branch (includes feature work), vague naming, no cleanup.

Example 3: Review PR without switching

Review and test

npm install npm test

Leave comments, then clean up

cd../myproject git worktree remove../myproject-pr-123

**Why this is good:** Fetches PR properly, uses PR number in path, cleans up after review.
</Good>

<Bad>

Try to checkout PR in main worktree

git checkout pr-123 # Loses current work

**Why this is bad:** Switches branch in main worktree, loses current state, forces stashing.

## Integration

**This skill enables:**

- Working on multiple branches simultaneously without context switching
- Running parallel Claude Code sessions (one per worktree)
- Emergency hotfixes without disrupting feature work
- Safe PR review in isolated environments

**Pairs with:**

- **track-session** - Create separate SESSION_PROGRESS.md in each worktree to track independent progress
- **commit workflows** - Each worktree has its own staging area and commits independently
- **Parallel Claude sessions** - Name each Claude session after its worktree branch for clarity

**Integration pattern with track-session:**

Create worktree

git worktree add ../myproject-feature -b feature/new-api cd ../myproject-feature

Create independent progress tracking

echo "# Session Progress - New API Feature" > SESSION_PROGRESS.md

Start Claude session named "myproject - New API Feature"

Work proceeds with independent progress tracking

**Multi-worktree workflow:**

Terminal 1: Feature work in main worktree

cd ~/myproject

Claude session: "myproject - main"

Terminal 2: Hotfix in separate worktree

cd ~/myproject-hotfix

Claude session: "myproject - hotfix"

Terminal 3: PR review in separate worktree

cd ~/myproject-pr-123

Claude session: "myproject - PR review"

**Best practices:**

- Name Claude sessions to match worktree purpose
- Each worktree tracks progress independently
- Use `git worktree list` to see all active work
- Clean up worktrees when branches are merged

## References

- [Git Worktree Documentation](https://git-scm.com/docs/git-worktree)
- [Git Worktree Tutorial](https://git-scm.com/docs/git-worktree#_examples)