worktree

Git Worktree 管理器

使用 git worktree 同时在多个分支上工作。

前提条件

# Git 2.5+ (worktrees built-in)
git --version

命令行参考

列出 Worktree

# List all worktrees
git worktree list

# Porcelain format (machine-readable)
git worktree list --porcelain

创建 Worktree

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

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

# Specific path
git worktree add /path/to/worktree branch-name

# Detached HEAD at commit
git worktree add --detach ../temp abc123

删除 Worktree

# Remove worktree
git worktree remove ../feature-branch

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

# Prune stale worktrees
git worktree prune

Worktree 操作

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

# Lock worktree (prevent pruning)
git worktree lock ../feature-branch
git worktree lock --reason "long-running task" ../feature-branch

# Unlock
git worktree unlock ../feature-branch

工作流模式

并行功能开发

# Main repo working on feature-a
cd ~/repos/myproject
git checkout feature-a

# Create worktree for feature-b
git worktree add ../myproject-feature-b feature-b

# Now you have two checkouts:
# ~/repos/myproject (feature-a)
# ~/repos/myproject-feature-b (feature-b)

快速修复 Bug

# Currently working on feature
cd ~/repos/myproject

# Create worktree for hotfix
git worktree add ../myproject-hotfix -b hotfix/urgent main

# Fix bug in worktree
cd ../myproject-hotfix
# make changes
git commit -am "fix: urgent bug"
git push origin hotfix/urgent

# Create PR
gh pr create --base main --title "Hotfix: urgent bug"

# Clean up
cd ../myproject
git worktree remove ../myproject-hotfix

审查 PR

# Create worktree for PR branch
git fetch origin pull/123/head:pr-123
git worktree add ../myproject-pr-123 pr-123

# Review and test
cd ../myproject-pr-123
npm install
npm test

# Clean up after review
cd ../myproject
git worktree remove ../myproject-pr-123
git branch -D pr-123

长时间运行的对比

# Worktree for baseline
git worktree add ../myproject-baseline main

# Run tests on both
cd ~/repos/myproject
npm test > /tmp/feature-tests.log

cd ../myproject-baseline
npm test > /tmp/baseline-tests.log

diff /tmp/baseline-tests.log /tmp/feature-tests.log

目录结构

推荐的布局：

~/repos/
├── myproject/           # Main worktree (main branch)
├── myproject-feature-a/ # Feature worktree
├── myproject-feature-b/ # Another feature
└── myproject-hotfix/    # Hotfix worktree

或者嵌套式：

~/repos/myproject/
├── main/      # Main worktree
├── features/
│   ├── auth/  # Feature worktree
│   └── ui/    # Feature worktree
└── hotfix/    # Hotfix worktree

Beads 与 Worktree

在将 beads（任务跟踪器）与 worktree 一起使用时，请禁用守护进程：

# In shell config
export BEADS_NO_DAEMON=1

# Or per-command
bd --no-daemon ready
bd --no-daemon create "task"

常见问题

分支已被检出

# Error: 'branch' is already checked out at '/path'
# Solution: Use different branch or remove other worktree
git worktree remove /path/to/other

过期的 Worktree 引用

# Clean up deleted worktrees
git worktree prune

# Verbose output
git worktree prune --verbose

共享资源

每个 worktree 共享：

• .git 目录（refs、objects）
• 远程配置
• Hooks

每个 worktree 拥有独立的：

• 工作目录
• 索引（暂存区）
• HEAD

脚本

创建功能 Worktree

#!/bin/bash
FEATURE=$1
BASE=${2:-main}

git worktree add -b feature/$FEATURE ../${PWD##*/}-$FEATURE $BASE
cd ../${PWD##*/}-$FEATURE
npm install
echo "Worktree created at $(pwd)"

清理旧 Worktree

#!/bin/bash
# Remove worktrees for merged branches

for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
  branch=$(git -C "$wt" branch --show-current)
  if git branch --merged main | grep -q "$branch"; then
    echo "Removing merged worktree: $wt ($branch)"
    git worktree remove "$wt"
  fi
done
git worktree prune

最佳实践

1. 使用描述性路径 - 在目录中包含分支名称
2. 安装依赖 - 在每个 worktree 中运行 npm/yarn install
3. 定期清理 - 清理过期引用
4. 不要嵌套 worktree - 保持它们为同级目录
5. 锁定长时间运行的 worktree - 防止意外清理
6. 独立的 IDE 工作区 - 每个 worktree 使用自己的 IDE 窗口
7. 禁用 beads 守护进程 - 防止数据库冲突