Git worktree 并行维护多个功能分支的操作方法

同时维护两个功能分支时，反复切换分支最容易把未提交改动、构建产物和本地调试状态搅在一起。git worktree 的解决思路很直接：保留一个主工作树，再把其他分支检出到兄弟目录。每个目录有独立的工作文件、HEAD 和索引，但共享同一个仓库的对象和引用，因此不需要重复克隆完整仓库。

Git worktree 官方文档：https://git-scm.com/docs/git-worktree

先理解一条硬规则：一个分支对应一个工作树

一个仓库可以有主工作树和多个 linked worktree。常规情况下，同一个本地分支不能同时在两个工作树中检出；这正是 Git 用来避免两个目录同时修改同一分支的保护机制。规划时应让“任务、分支、目录”保持一一对应，例如：

下面假设当前终端位于 project 主工作树中，兄弟目录将创建在它的上一级目录。路径并非必须这样安排，但统一命名可以显著降低认错目录的概率。

第一步：检查现状并规划兄弟目录

先确认主工作树没有未处理的改动，并列出本地、远端分支以及已经登记的工作树：

# 查看当前工作树是否存在未提交改动
git status --short

# 列出本地与远端分支，确认目标分支名称
git branch --all --list

# 列出当前仓库已登记的全部工作树
git worktree list

成功条件：git worktree list 至少显示当前主工作树的绝对路径、当前提交和 [main]；计划使用的兄弟目录不存在，目标新分支也尚未被其他工作树占用。

如果列表中已经出现目标分支，先进入对应目录完成或清理任务，不要用 --force 绕过保护。强制重复检出会破坏“一个任务一个目录”的可追踪性。

第二步：从 main 创建新功能分支

创建一个新的支付功能工作树，目标是从当前 main 建立 feature/payment，并把它检出到兄弟目录 ../project-payment：

# 从 main 创建 feature/payment，并在兄弟目录中检出
git worktree add -b feature/payment ../project-payment main

这条命令同时完成三件事：创建本地分支、登记 linked worktree、检出文件。命令成功后，进入新目录确认身份：

# 在新目录中核对当前分支和工作区状态
git -C ../project-payment branch --show-current
git -C ../project-payment status --short

成功条件：第一条输出 feature/payment，第二条没有输出，表示新工作树处于目标分支且当前干净。

第三步：接入已有本地分支或远端分支

如果分支已经存在，不再使用 -b。例如本地已有 feature/search：

# 把已有本地分支检出到新的兄弟目录
git worktree add ../project-search feature/search

远端已有分支时，建议先更新远端引用，再显式建立本地跟踪分支。这样目录、分支名和上游关系都清楚：

# 更新远端引用，避免基于过期的远端状态创建工作树
git fetch origin

# 创建本地跟踪分支并检出到独立修复目录
git worktree add --track -b hotfix/login ../project-hotfix origin/hotfix/login

成功条件：git -C ../project-hotfix branch -vv 显示当前分支为 hotfix/login，并跟踪 origin/hotfix/login。如果 Git 提示分支已被其他工作树检出，应回到第一步查找占用目录，而不是重复创建。

第四步：用机器可读列表核对映射

普通列表适合快速查看；需要准确核对或交给脚本处理时，用 porcelain 格式：

# 以稳定的机器可读格式输出路径、提交和分支
git worktree list --porcelain

典型输出会按工作树分组：

worktree /workspace/project
HEAD 8c14a2d...
branch refs/heads/main

worktree /workspace/project-payment
HEAD 8c14a2d...
branch refs/heads/feature/payment

逐组确认三项：worktree 是预期目录，branch 是预期本地分支，HEAD 是创建时的基线提交。若使用 git worktree add --detach 创建临时检查目录，列表会标记 detached，它适合查看或测试历史提交，不适合直接当作长期功能分支。

第五步：在多个目录中并行开发

之后每个任务都在自己的目录运行构建、测试和提交。它们共享对象数据库与分支引用，所以一个工作树提交后，其他工作树可以立即看到该提交对象；但未提交文件、暂存区和当前 HEAD 各自独立。

# 在支付功能工作树中完成独立提交
git -C ../project-payment add .
git -C ../project-payment commit -m "feat: add payment flow"

# 回到主工作树查看功能分支的新提交
git log --oneline main..feature/payment

成功条件：提交只改变 feature/payment 的分支指针；主工作树仍停留在 main，其文件不会被自动切换。需要合并时，应在主工作树中先更新并测试，再按团队流程合并或变基。

依赖目录、构建缓存和本地配置通常也会各占一份。大型项目要提前评估磁盘空间；需要共享的缓存应通过工具自己的缓存配置管理，不要把一个工作树的可写构建目录硬链接给另一个。

第六步：清理工作树并维护元数据

任务结束后，先检查目标目录是否干净，再让 Git 正式移除工作树：

# 确认目标工作树没有未提交或未跟踪的重要文件
git -C ../project-payment status --short

# 由 Git 删除目录并注销 linked worktree 元数据
git worktree remove ../project-payment

# 清理曾被手动删除目录所遗留的过期元数据
git worktree prune

成功条件：git worktree list 不再显示 project-payment。默认情况下，存在改动的工作树不能被移除；此时应先提交、暂存到安全位置或备份文件，而不是直接强制删除。

如果只是移动 linked worktree，可使用 git worktree move ；若目录被系统工具移动、主仓库路径变化或元数据关联失效，可用 git worktree repair 修复。位于可拔插磁盘上的工作树可以执行 git worktree lock --reason "外接磁盘" 防止被自动清理，重新可用后再 unlock。

常见边界与排查

提示分支已经被检出怎么办？

运行 git worktree list 找到占用目录。继续使用那个工作树，或在确认干净后移除它。不要把强制参数作为日常方案。

手动删除目录后列表仍有记录怎么办？

执行 git worktree prune 清理失效的 linked worktree 元数据。如果目录只是被移动而不是删除，优先使用 git worktree repair 恢复关联。

可以在多个工作树中使用 submodule 吗？

Git 官方文档仍将多工作树中的 submodule 支持标为不完整，不建议把依赖复杂 submodule 的仓库直接套入大量并行 worktree。先在测试仓库验证初始化、更新和清理行为，再决定团队流程。

最终核对清单

• 目录名能直接对应任务和分支，不复用已有路径。
• 新分支使用 -b 并显式给出基线；已有分支不重复创建。
• 远端分支先 fetch，再显式创建本地跟踪分支。
• 开始开发前用 git worktree list --porcelain 核对路径、分支和提交。
• 每个目录独立安装依赖、运行测试和提交，避免共享可写构建目录。
• 移除前确认工作区干净，使用 git worktree remove 而不是手动删目录。