Git 内置命令 —— 同一仓库挂载多个工作目录，实现多分支并行开发，无需 stash 或切换分支。
为什么值得关注
传统工作流切换分支前必须 stash 或提交，worktree 允许同时 checkout 多个分支到不同目录，互不干扰。适合：同时修复 hotfix 和开发新功能、并行运行测试、隔离实验性改动。
语法
git worktree add [-f] [--detach] [-b <branch>] <path> [<commit-ish>]
git worktree list [-v | --porcelain]
git worktree lock [--reason <string>] <worktree>
git worktree move <worktree> <new-path>
git worktree prune [-n] [-v] [--expire <expire>]
git worktree remove [-f] <worktree>
git worktree repair [<path>...]
git worktree unlock <worktree>
子命令
| 子命令 | 说明 |
|---|---|
add | 创建新 worktree，checkout 指定分支或提交 |
list | 列出所有 worktree（主 + 链接） |
lock | 锁定 worktree，防止被 prune/move/delete |
unlock | 解锁 worktree |
move | 移动 worktree 到新路径 |
remove | 删除 worktree（仅干净状态，否则加 -f） |
prune | 清理 $GIT_DIR/worktrees 中的过期元数据 |
repair | 修复因手动移动导致的路径关联损坏 |
常用选项（add）
| 选项 | 说明 |
|---|---|
-b <branch> | 创建新分支并 checkout |
-B <branch> | 强制创建/重置分支 |
-d / --detach | 以 detached HEAD 方式 checkout |
--no-checkout | 创建 worktree 但不 checkout（用于 sparse-checkout 等定制） |
-f / --force | 强制创建（分支已被其他 worktree 使用时） |
--lock | 创建后立即锁定 |
常用示例
# 基于当前 HEAD 创建新 worktree（自动创建同名分支）
git worktree add ../hotfix
# 在新 worktree 中创建并 checkout 新分支
git worktree add -b feature/login ../feature-login
# checkout 已有分支到新目录
git worktree add ../release-1.0 release/1.0
# 以 detached HEAD 方式创建（临时实验）
git worktree add -d ../experiment
# 列出所有 worktree
git worktree list
# 删除 worktree
git worktree remove ../hotfix
# 强制删除有未提交改动的 worktree
git worktree remove -f ../hotfix
# 清理已手动删除目录的残留元数据
git worktree prune工作原理
- 主 worktree 由
git init/git clone创建，元数据在.git/ - 链接 worktree 的元数据存储在
.git/worktrees/<name>/，包含独立的HEAD、index - 同一仓库的所有 worktree 共享 objects、refs（除 per-worktree 文件外）
- 同一分支不能同时被两个 worktree checkout（除非
--force）
适用场景
- 并行开发：同时在
main修 bug、在feature开发新功能 - Code Review：checkout PR 分支到独立目录，不影响当前工作
- 长时间构建/测试：在另一个 worktree 跑测试，当前目录继续编码
- AI Agent 隔离：为每个 Agent 任务创建独立 worktree，避免互相干扰
局限性
- 同一分支不能被多个 worktree 同时 checkout
- 主 worktree 不能被
remove或move（含 submodule 的 linked worktree 也不能 move） - 手动删除 worktree 目录后需运行
prune清理元数据
相关命令
git branch— 分支管理git stash— 临时保存工作区（worktree 的替代方案之一）git checkout/git switch— 单 worktree 下的分支切换- git-revert — 撤销提交，不改写历史