git:worktrees

Git Worktrees

概述

Git worktrees 可在不同目录中同时检出多个分支，且这些目录共用同一个仓库。可以创建 worktree，而不必暂存更改或单独克隆仓库。

核心原则： 每个活动分支对应一个 worktree。通过切换目录而不是切换分支来切换工作上下文。

核心概念

概念	描述
主 worktree	通过 git clone 或 git init 创建的原始工作目录
关联 worktree	使用 git worktree add 创建的其他目录
共享的 .git	所有 worktree 共用同一个 Git 对象数据库（不会重复存储）
分支锁定	每个分支一次只能在一个 worktree 中检出
Worktree 元数据	.git/worktrees/ 中用于跟踪关联 worktree 的管理文件

快速参考

任务	命令
创建 worktree（现有分支）	git worktree add <path> <branch>
创建 worktree（新分支）	git worktree add -b <branch> <path>
创建 worktree（从引用创建新分支）	git worktree add -b <branch> <path> <start>
创建分离头指针 worktree	git worktree add --detach <path> <commit>
列出所有 worktree	git worktree list
移除 worktree	git worktree remove <path>
强制移除 worktree	git worktree remove --force <path>
移动 worktree	git worktree move <old> <new>
锁定 worktree	git worktree lock <path>
解锁 worktree	git worktree unlock <path>
清理过期 worktree	git worktree prune
修复 worktree 链接	git worktree repair
比较不同 worktree 中的文件	diff ../worktree-a/file ../worktree-b/file
从其他分支获取一个文件	git checkout <branch> -- <path>
获取部分文件更改	git checkout -p <branch> -- <path>
挑选提交	git cherry-pick <commit>
挑选提交但不提交	git cherry-pick --no-commit <commit>
合并但不自动提交	git merge --no-commit <branch>

基本命令

创建 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

列出 Worktree

# Simple list
git worktree list

# Verbose output with additional details
git worktree list -v

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

输出示例：

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

移除 Worktree

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

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

移动 Worktree

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

锁定/解锁 Worktree

# 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

清理过期 Worktree

# 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

修复 Worktree

# Repair worktree links after moving directories manually
git worktree repair

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

工作流模式

模式 1：并行处理功能开发和紧急修复

在进行功能开发时修复 Bug：

# 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

模式 2：工作期间审查 PR

在不影响当前工作的情况下审查 PR：

# 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

模式 3：比较实现

并排比较不同分支中的代码：

# 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

模式 4：长时间运行的任务

继续开发的同时，隔离运行测试/构建：

# 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

模式 5：稳定的参考版本

保持干净的主检出目录以供参考：

# 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

模式 6：从多个功能分支选择性合并

合并来自多个功能分支的特定更改：

# 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

比较并合并不同 Worktree 中的更改

由于所有 worktree 共用同一个 Git 仓库，你可以比较文件、挑选提交，并在 worktree 之间选择性地合并更改。

比较并审查文件更改

由于 worktree 只是目录，你可以直接比较文件：

# 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

从 Worktree 合并单个文件

你可以使用 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

对于部分文件更改（仅选择特定代码块/行）：

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

此操作会提示你逐个接受或拒绝每个更改代码块，选项如下：

• y - 应用此代码块
• n - 跳过此代码块
• s - 拆分为更小的代码块
• e - 手动编辑此代码块

从 Worktree 挑选提交

挑选提交以提交为单位。由于所有 worktree 共用同一个仓库，你可以挑选任意提交：

# 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

合并来自多个 Worktree 的更改

你可以从多个分支进行合并或挑选提交：

# 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

选择性合并——选择要包含的更改

选项 1：选择性检出文件

# 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"

选项 2：交互式选择补丁

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

选项 3：Cherry-pick 并选择性暂存

# 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"

选项 4：手动选择合并内容

# 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"

选项 5：使用 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

目录结构约定

以可预测的方式组织工作树：

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

命名约定： <project>-<purpose> 或 <project>-<branch>

最佳实践

实践	原因
使用同级目录	将工作树放在主项目的同级目录，便于导航
按用途命名	project-review 比 project-pr-123 更清晰
及时清理	完成后移除工作树，避免混淆
锁定远程工作树	如果工作树位于网络/USB 存储设备上，避免其被清理
实验时使用 --detach	避免创建一次性分支
移除前先提交	执行 git worktree remove 前，务必提交或暂存更改

常见问题及解决方法

问题：“Branch is already checked out”

原因： 尝试检出已在另一个工作树中处于活动状态的分支。

解决方法：

# Find where the branch is checked out
git worktree list

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

问题：手动删除后工作树仍残留

原因： 未使用 git worktree remove，直接删除了工作树目录。

解决方法：

# Clean up stale metadata
git worktree prune

问题：手动移动工作树

原因： 未使用 git worktree move，直接移动了工作树目录。

解决方法：

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

问题：工作树所在的驱动器已移除

原因： 工作树位于已断开连接的可移动存储设备上。

解决方法：

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

# If permanent, prune it
git worktree prune

常见错误

错误	修正方法
使用 rm -rf 删除工作树	始终使用 git worktree remove，必要时再运行 git worktree prune
忘记分支已锁定到工作树	遇到检出错误前，先运行 git worktree list
未清理临时工作树	任务完成后立即移除工作树
在嵌套位置创建工作树	使用同级目录（../project-feature），不要使用子目录
手动移动工作树目录	使用 git worktree move，或之后运行 git worktree repair

与 Agent 工作流集成

隔离并行 Agent 任务：

# 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

使用分离的 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

验证清单

使用工作树前：

• 了解分支只能在一个工作树中检出
• 确认工作树的创建位置（使用同级目录）
• 为临时工作树制定清理方案

创建工作树时：

• 使用描述性目录名称
• 确认分支未在其他位置检出
• 考虑在实验时使用 --detach

移除工作树时：

• 提交或暂存所有未提交的更改
• 使用 git worktree remove，不要使用 rm -rf
• 如果目录是手动删除的，请运行 git worktree prune