Git 怎样用 worktree 分离并行功能分支

当一个功能还没有做完，却临时需要修复线上分支时，反复 stash、切换分支和恢复现场很容易出错。Git worktree 可以让同一个仓库同时拥有多个工作目录，每个目录绑定一个分支，适合并行开发、紧急修复和短期验证。

官方地址：https://git-scm.com/docs/git-worktree

下面用一个主目录、一个搜索功能目录和一个热修复目录说明完整操作。界面图片是配合步骤制作的原创操作示意图，不是 Git 客户端或终端截图。

先理解 worktree 的目录关系

一个普通仓库有一个 main worktree，还可以挂接多个 linked worktree。它们共享对象库和提交历史，但各自拥有独立的工作目录、HEAD 和 index。因此，主目录正在修改文件时，另一个 worktree 仍然可以检出不同分支。

建议把并行目录放在主仓库的同级目录，名称直接体现分支用途，例如 ../demo-search。这样删除或移动目录时不容易误伤主仓库。

创建一个独立的功能目录

如果目标分支已经存在，可以直接指定分支名；如果分支还不存在，则使用 -b 创建它：

# 在当前仓库旁边创建目录，并新建 feature/search 分支
git worktree add -b feature/search ../demo-search

# 如果分支已经存在，直接把它检出到新目录
git worktree add ../demo-hotfix hotfix/login

第一条命令执行后，../demo-search 就是独立工作区。进入该目录后，提交、拉取和推送仍然使用普通 Git 命令：

# 进入功能 worktree，确认当前分支后再开始修改
cd ../demo-search
git branch --show-current

# 将功能改动提交到它自己的分支
git add .
git commit -m "实现搜索结果分页"
git push -u origin feature/search

用 list 检查所有并行工作区

不要只凭目录名判断当前状态，统一用 git worktree list 查看 Git 记录的路径、提交和分支：

# 查看主 worktree 和所有 linked worktree
git worktree list

# 用机器更容易读取的格式查看详细状态
git worktree list --porcelain

重点看三项：路径是否指向预期目录、分支是否正确、是否出现 prunable。如果目录被手动删除，Git 可能暂时保留关联记录，这时不要马上重新用同名路径创建。

并行开发时要注意的边界

• 同一个分支默认不能同时被两个 worktree 检出。看到 branch is already checked out 时，应先使用现有目录，或创建一个新的分支。
• 各 worktree 的未提交文件彼此独立，但共享提交历史；合并、变基和冲突处理仍然要回到具体分支完成。
• 脚本中的相对路径以当前 worktree 为基准。项目工具若依赖固定的上级目录，创建前先确认路径约定。
• 临时实验可以使用 detached HEAD，但它不适合作为长期功能分支，重要提交应及时创建或关联分支。

完成后安全移除 worktree

功能分支合并后，先确认目录没有需要保留的未提交文件，再从主仓库执行移除：

# 先列出 worktree，确认要删除的路径和分支
git worktree list

# 只移除已经干净的 linked worktree
git worktree remove ../demo-search

# 处理被手动删除后留下的过期管理记录
git worktree prune

如果目录仍有修改，Git 默认会拒绝删除，这是保护措施。需要保留改动时先提交或复制；只有确定内容不再需要时，才考虑带 --force 的移除。

常见问题怎么处理

为什么新 worktree 不能使用已有分支？因为该分支已经被另一个 worktree 检出。先运行 git worktree list 找到它，完成旧目录的工作后再移除，或者基于目标提交创建新分支。

目录删掉了，list 里还存在怎么办？回到主 worktree 执行 git worktree prune，清理已经不存在的目录记录。若只是目录移动了，优先使用 git worktree move 或 git worktree repair，不要反复删除内部记录。

什么时候不适合使用 worktree？如果项目很小、没有并行任务，普通分支切换更简单；如果构建目录、依赖缓存或本地配置必须全局共享，也要先确认多个目录不会互相覆盖。

速查表

把 worktree 当成“一个仓库、多份独立工作现场”即可。创建时明确目录和分支，使用中用 list 追踪，结束时先确认干净再 remove，就能把并行功能开发和紧急修复分开管理。