Claude Code 如何用 git worktree 并行开发?

掘金热榜《一个项目五个 AI 同时干活,Claude Code 怎么让它们不互相打架》讨论了 Agent 并行开发中的目录隔离问题:五个 Claude Code 会话即使同时运行,只要共用同一个仓库根目录,就会共享工作文件、索引、分支切换和未提交状态。

并行任务应遵循“一项任务、一个分支、一个 worktree”。发现多个 Agent 共用目录时,先暂停任务并盘点改动,再为每个任务建立独立工作区;如果已经发生合并冲突,则先根据 git status 判断当前处于 merge、rebase 还是 cherry-pick,再决定解决、回滚还是继续。git worktree 只能隔离工作目录,不能消除最终合并时的代码冲突。

多个 Agent 是不是正在共用同一个工作目录?

不要采信 Agent 自述的“当前分支”或“已经隔离”,直接在实际终端执行:

pwd
git rev-parse --show-toplevel
git worktree list
git -C "/path/to/worktree" status --short

git rev-parse --show-toplevel 返回的是当前 Git 工作区根目录。多个终端如果得到相同路径,说明它们正在读写同一套文件、索引和未提交改动。

还可以检查两个路径是否属于同一个仓库:

git rev-parse --git-common-dir
git rev-parse --git-dir

同一个仓库的不同 worktree 会共享部分 Git 数据,因此 git-common-dir 相同是正常的;判断文件是否隔离,要看 --show-toplevel 和 git worktree list 中的实际路径。

如果多个 Agent 共用同一目录,不要直接执行 git reset、git clean、批量 stash 或删除文件。先记录每个 Agent 的任务、分支和改动,否则很难判断某段代码属于谁。git stash 也不是可靠的隔离边界,因为多个 worktree 共享同一个仓库的 stash 列表;一个 Agent 执行 stash pop,可能取走另一个 Agent 的记录。

哪些改动不应该交给多个 Agent 同时处理?

worktree 隔离的是目录,不会自动判断两个任务是否修改了同一条业务链路。开始并行前,应先建立“任务—分支—目录—允许修改路径”的对应关系:

任务对象 并行策略 原因
不同模块、没有共同依赖的文件 可以并行 合并时通常改动较小
同一个文件或同一组接口 串行,或只允许一个负责人 即使目录分开,最终仍可能发生内容冲突
依赖清单和锁文件 源码合并后统一生成 两个分支生成的锁文件可能对应不同依赖树
自动生成代码 由唯一负责人重新生成 直接合并生成物容易覆盖或产生漂移
数据库 schema 与迁移 严格串行 还涉及执行顺序、兼容窗口和共享数据库
同一个开发端口、测试库或外部服务 串行 worktree 隔离不了进程和外部资源

两个任务即使没有修改完全相同的文件,也可能修改同一个接口的生产者和消费者。例如一个任务调整请求结构,另一个任务仍按旧结构调用它。这种情况不会产生 Git 冲突标记,却属于语义冲突。使用独立 worktree 时,两个任务修改同一文件,最终合并仍然会冲突。

git worktree add 怎么为每个任务创建独立目录?

先更新并确认基线,再为每个任务创建名称唯一的分支和目录:

git fetch origin
git worktree add ../repo-feature-a -b feature/task-a origin/main
git worktree add ../repo-feature-b -b feature/task-b origin/main
git worktree list

这里的 origin/main 只是示例,实际应替换成项目使用的远程仓库和基线分支。worktree 拥有各自的工作文件和索引,但共享 Git 对象数据;因此可以同时运行多个 Claude Code,而不必不断切换主目录里的分支。

如果目标分支已经存在,不要再次使用 -b,可以改为:

git worktree add ../repo-feature-a feature/task-a

同一个分支通常不能同时被两个 worktree 检出,所以分支名和目录名都要保持唯一。如果命令提示分支已被使用,应先通过 git worktree list 查清它绑定了哪个目录,不要为了绕过错误而删除现有 worktree。

主工作区里的未提交改动不会自动进入新 worktree。常见的安全做法有三种:把确认过的改动提交到专用 WIP 分支;导出补丁;或者单独复制未跟踪文件。补丁必须写到 worktree 之外:

git status --short
git diff HEAD --binary > ../repo-main-wip.patch
git ls-files --others --exclude-standard

补丁不包含未跟踪文件,列表中的文件需要逐个确认并复制。若基线一致,应用前先检查补丁能否干净应用:

git -C ../repo-feature-a apply --check /absolute/path/to/repo-main-wip.patch
git -C ../repo-feature-a apply /absolute/path/to/repo-main-wip.patch

.env 等被 Git 忽略的文件不会出现在普通补丁中,也不会因为创建 worktree 自动出现。应在每个目录中单独配置或安全复制,注意不要把凭据提交进仓库。依赖目录同样需要分别安装,因为 node_modules、虚拟环境等通常也是各目录独立的状态。

claude --worktree 或桌面 Agent 视图会自动隔离任务吗?

先检查当前安装版本实际提供的参数:

claude --version
claude --help

只有帮助信息明确列出时,再使用相应入口:

claude --worktree

部分教程列出了 claude --worktree 和 -w,但这些选项属于版本相关行为,不能根据文章直接推断当前版本一定支持。 一篇针对 Claude Code v2.1.139 的解读称,后台任务会自动进入 .claude/worktrees/;这同样应当作为该版本的观察结果,而不是所有版本的通用保证。

手工建立 worktree 后,直接进入对应目录启动:

cd ../repo-feature-a
claude

启动后仍要立即核对:

pwd
git rev-parse --show-toplevel
git branch --show-current
git worktree list

自动入口、手工创建的 worktree 和桌面 Agent 视图不要未经检查就混用,否则可能出现“目录已经隔离,但 Agent 不知道”或“又额外创建了一个 worktree”的情况。

开发过程中怎么知道每个 Agent 改了什么?

在各目录中定期检查状态、差异和提交边界:

git -C ../repo-feature-a status --short
git -C ../repo-feature-a diff --stat
git -C ../repo-feature-a diff --check
git -C ../repo-feature-a log --oneline --decorate -n 5
git -C ../repo-feature-a branch --show-current

status --short 能看到已暂存、未暂存和未跟踪文件;diff --stat 用来判断改动范围;diff --check 可以发现空白错误以及残留的冲突标记;log 则用于确认 Agent 是否把其他任务的提交带进了当前分支。

提交时只暂存本任务负责的路径:

git -C ../repo-feature-a add -- path/to/owned/file
git -C ../repo-feature-a diff --cached --stat
git -C ../repo-feature-a commit -m "feat: implement task-a"

不要让 Agent 在已经分配好的 worktree 中随意切换到另一个任务分支。目录虽然分开了,分支和提交边界仍然可能串线。

为什么 worktree 已经分开,合并时还是冲突?

因为 worktree 解决的是“开发期间互相覆盖文件”,并没有解决“多个分支最终要变成同一份代码”。不同 worktree 最终仍要通过 merge、rebase 或 cherry-pick 汇合。

冲突来源 可能表现 处理重点
修改同一文件的同一区域 内容冲突 理解双方意图后手工合并
两个分支新增同名文件 add/add 冲突 决定保留哪个实现,或重新命名
一个分支删除文件,另一个继续修改 modify/delete 冲突 明确文件最终是否仍应存在
一个分支重命名,另一个修改旧路径 rename/delete 等冲突 同时确认旧路径和新路径的最终状态
同时修改依赖清单或锁文件 内容冲突或依赖树不一致 合并源码后统一重新生成
同时修改生成代码 文本冲突或生成结果漂移 以源文件为准重新生成
同时新增数据库迁移 文件冲突、编号冲突或执行顺序冲突 串行设计并验证迁移顺序
接口与调用方分别修改 Git 可能完全不报冲突 做语义审查和集成测试
分支基线过旧 冲突范围异常扩大 先更新基线再重新集成

基线过旧时,可以先查看当前分支与远程基线的分叉:

git merge-base HEAD origin/main
git log --oneline --left-right HEAD...origin/main

问题往往不是 worktree 失效,而是两个任务在不同的代码基础上各自前进。越晚更新基线,最终需要人工辨认的差异越多。

Git 报告未合并文件后,先看哪些信息?

先看仓库状态,再定位未合并路径:

git status
git diff --name-only --diff-filter=U
git ls-files -u
git diff

不要一看到冲突标记就全部删除。git ls-files -u 会显示冲突文件的暂存阶段:

git show :1:path/to/file
git show :2:path/to/file
git show :3:path/to/file

阶段 1 是共同基线,阶段 2 是当前一侧,阶段 3 是待合并的一侧。普通 merge 中,“当前一侧”通常是当前分支,“待合并的一侧”是正在合入的分支;但在 rebase 和 cherry-pick 中,ours 与 theirs 的具体含义会变化,所以必须结合 git status 判断当前操作,不能把一次 merge 的结论直接套用到 rebase。

git merge --abort、git rebase --abort 和 git cherry-pick --abort 该用哪个?

只执行与当前状态对应的一组命令:

当前操作 放弃本次操作 解决后继续
merge git merge --abort git merge --continue
rebase git rebase --abort git rebase --continue
cherry-pick git cherry-pick --abort git cherry-pick --continue

git status 是主要判断依据。如果发现基线选错、冲突范围异常扩大,或者任务方向已经改变,应先 abort,再更新基线重试,不要在残缺状态上继续叠加修改。

abort 会回到本次操作开始前的状态,已经写入冲突文件的人工处理也可能丢失。值得保留的解决结果应先复制到 worktree 外,或至少保存一份差异:

git diff --binary > ../conflict-resolution.patch

如果仓库同时显示多个操作状态,应结合 git status 和 git log 判断最近启动的是哪一个流程,不要连续尝试所有 abort 命令。

冲突文件怎么改,ours 和 theirs 能不能直接选?

ours 和 theirs 表示当前操作中相对的两侧,并非始终对应固定分支:

操作 ours theirs
merge 当前分支 正在合入的分支
rebase 正在变基到的上游分支 正在重放的提交
cherry-pick 当前分支 被挑选的提交

只有确认整份文件应该采用其中一侧时,才使用:

git restore --ours -- path/to/file
git restore --theirs -- path/to/file
git add path/to/file
git diff --cached

整文件选择很适合生成文件或确实互斥的实现,但不适合双方都修改了同一个业务模块的情况。此时应同时查看基线、当前版本和待合并版本,手工保留双方仍有效的逻辑。

如果冲突结果应当删除文件,应明确暂存删除:

git rm path/to/file

需要让 Claude Code 协助时,先限制它只分析,不允许它擅自清理仓库:

只分析当前冲突,不要执行 git reset、git checkout --ours/--theirs、
git clean,也不要删除未跟踪文件;请说明冲突双方的意图、风险、
建议的合并方式和需要补充的测试。

这样得到的是供人审查的合并建议,Agent 不会直接替你清理仓库或落盘破坏性改动。

两个 Agent 都改了锁文件、生成代码或数据库迁移怎么办?

这类文件应指定唯一负责人,或者等源码合并完成后再统一生成。依赖锁文件必须基于最终依赖树重新生成,不能因为 ours 或 theirs 少了一处冲突就认为结果正确。生成代码也应从最终源码重新生成,再检查生成物是否与源码一致。

数据库迁移的问题更复杂。除了文件内容冲突,还涉及迁移编号、执行顺序、旧版本兼容和回滚路径。多个 Agent 即使位于不同 worktree,如果同时连接同一个开发数据库,目录隔离也阻止不了运行时竞争。迁移应串行设计、串行执行,并按项目实际部署流程验证。

合并顺序怎么安排,才能减少下一轮冲突?

先让每个任务分支更新到共同基线,再按依赖关系逐个集成。通常先合并基础接口和数据结构,再合并依赖这些接口的功能:

git fetch origin
git -C ../repo-feature-a status --short
git -C ../repo-feature-a rebase origin/main
git switch main
git merge feature/task-a

rebase 会重写分支提交历史。如果这些提交已经推送并被其他成员使用,应先遵循团队约定,不能擅自改写共享历史。另一种统一策略是 cherry-pick,但不要让不同分支混用 merge、rebase 和 cherry-pick 而没有记录。

main 分支应由指定的主 worktree 持有。如果它已经在另一个 worktree 中检出,在功能目录执行 git switch main 会被 Git 拒绝;这不是 Agent 故障,也不应通过删除 worktree 强行绕过。

每次只集成一个任务,并立即运行项目已有的测试、lint 和构建命令。只有当前合并通过验证后,再接收下一项任务。否则多个分支一次性合入,出现问题时很难判断是哪项变更引入的。

任务失败后,怎么保留成果再删除 worktree?

优先保留提交。提交已经保存在分支上,即使删除 worktree 也不会消失。未提交内容则应先导出到 worktree 外:

git -C ../repo-feature-a status --short
git -C ../repo-feature-a diff HEAD --binary > ../repo-feature-a.patch
git -C ../repo-feature-a ls-files --others --exclude-standard
git -C ../repo-feature-a log --oneline --decorate -n 5

补丁仍然不包含未跟踪和被忽略的文件。未跟踪文件需要逐个复制;.env 等敏感文件应单独、安全地保存,不要为了“保住成果”直接提交。确有必要时,也可以先创建 WIP 提交,再删除工作目录。

确认成果已经提交、合并或备份后,再移除 worktree:

git worktree remove ../repo-feature-a
git worktree list
git worktree prune
git branch -d feature/task-a

正常执行 git worktree remove 时,Git 会清理对应的管理记录;git worktree prune 主要用于移除已经失效的登记项。不要手工删除 .git/worktrees 下的内容,也不要用强制删除或直接 rm -rf 绕过检查。

git branch -d 只会删除已经合并的分支。如果它提示分支尚未合并,应先保留分支或完成备份,不要立即改用强制删除。

Claude Code 的 worktree 报错为什么和普通 Git 冲突不一样?

如果日志显示 git 被改写成了 lean-ctx -c,随后又被 worktree guard 拒绝,这属于 hook 改写问题,而不是 Git 本身无法创建 worktree。

相关 issue 的报告环境是 lean-ctx 3.11.0 和 macOS,Claude Code 的 PreToolUse Bash hook 会把 git 调用包装起来。后续修复 #2208 让以下配置跳过整个 hook rewrite:

excluded_commands = ["git"]

这样 git 会按原命令执行,同时仍保留原有的 allowlist 检查。 排查时应确认安装版本是否包含该修复;如果没有,可先在普通终端验证 Git 本身是否正常:

git status
git worktree list

直接执行正常、只有 Claude Code 中的 git 失败,就应继续检查 hook 配置和版本,而不是重建 worktree。具体配置文件位置应以当前 lean-ctx 版本的说明为准。

session_search 返回零结果也可能是另一个相关问题。oh-my-claudecode 的 issue 记录了 4.15.0 中从仓库子目录启动时,session_search 错把 worktree 根目录折叠,导致所有查询返回 totalMatches: 0,但 transcript 实际存在;该问题由 #3335 修复。 升级前可以先从仓库根目录启动:

git rev-parse --show-toplevel
cd /absolute/path/to/repository/root

如果仍需检索旧记录,可以直接搜索已知 transcript。这个现象属于 oh-my-claudecode 扩展,不应误判为 Claude Code 本身丢失了会话。

桌面端自动创建 worktree 时也要核对路径和分支。Claude Code 仓库曾有 issue 报告桌面端在缺少提示的情况下自动创建 worktree,并提醒可能造成数据损失;现有 issue 答复没有给出适用于所有版本的修复细节,因此不能因为 issue 已关闭就推断当前环境一定安全。

每次让桌面 Agent 写入前,先自行检查:

git worktree list --porcelain
git status --short

确认实际目录、分支和未提交改动,再允许 Agent 继续执行。

worktree 仍然解决不了哪些问题?

worktree 解决的是工作文件、索引、分支和未提交状态之间的目录级串扰。它不会自动解决同一文件的语义冲突、接口设计分歧、数据库迁移顺序、共享端口和测试库竞争,也不会替团队决定多个任务应该按什么顺序集成。

五个 Agent 可以并行执行五个任务,但任务边界、串行关口和最终合并不能交给模型临时决定。流程应保持为:先核对实际工作目录,再维护任务与分支的映射;冲突出现后先判断 Git 操作状态;能够回滚时先保留成果再处理;最后逐个集成并验证。

© 版权声明
THE END
喜欢就支持一下吧
点赞0 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容