返回日报条目

资料节译

Git worktree 共享 stash:并行代理可能取走彼此的改动

阅读原文

书籍:Prompt Engineering Pocket Guide

**我还写了:**Thinking in Go(2 册系列)—Complete Guide to Go Programming +Hexagonal Architecture in Go

我的项目:Hermes IDE |GitHub — 为使用 Claude Code 和其他 AI 编程工具交付代码的开发者打造的 IDE

我:xgabriel.com |GitHub

两个编程智能体同时在同一个仓库上工作,各自在自己的 Git 工作树中处理自己的问题。两者都运行了同一项检查:暂存修复,运行测试以证明没有修复时测试会失败,再把修复取回。智能体 A 取回时拿回了智能体 B 的暂存内容。B 取回时拿回了 A 的。现在,每个工作树里都有一个来自另一项任务的文件,而暂存列表已经空了。

这是objectstack issue #5742中的报告,该问题于 2026 年 8 月 6 日提交。问题记录称,git stash pop“执行成功,并打印了正常的 ‘Dropped refs/stash@{0}’ 行。”没有错误,也没有警告。之所以找回了这份工作,是因为一名智能体注意到仍在终端滚屏缓冲区中的被删除提交哈希,并将它保存到了一个引用中。

工作树隔离了你的文件、HEAD和索引。它并不隔离暂存区;手册用一句很容易扫过去的话明确说明了这一点。

git-worktree 手册(截至 Git 2.56.0)有一个名为 REFS 的章节。规则很简短:“一般来说,所有伪引用都按工作树区分,而所有以 refs/ 开头的引用都是共享的。”伪引用包括像 HEAD 这样的引用,它们直接位于 $GIT_DIR 下。接着是例外:“refs/bisect、refs/worktree 和 refs/rewritten 中的引用不共享。”

再看git-stash 手册:“你最近创建的暂存保存在 refs/stash 中;更早的暂存可在该引用的 reflog 中找到。”

refs/stash以 refs/ 开头,且不在例外列表中。因此,每个仓库只有一个暂存区,而不是每个工作树各有一个。较早的条目位于该引用的 reflog 中,而gitrepository-layout指出,logs目录也从公共目录读取,“logs/HEAD 除外”。最新条目和整个列表都位于共享的 .git 中。

不带参数的 git stash pop 会取出 stash@{0},也就是共享列表中最新的条目。它不会检查哪个工作树或分支创建了它。

Two separate desks, each with its own papers, both reaching into one shared drawer

每个工作树都有自己的桌面。暂存区则是一个大家都会打开的抽屉。

在一个临时仓库中,从同一个提交创建两个工作树:

mkdir stash-demo && cd stash-demo
git init -q
echo "v1" > app.txt
git add app.txt && git commit -qm "init"
git worktree add -q -b agent-a ../wt-a
git worktree add -q -b agent-b ../wt-b
# agent A sets its half-done fix aside
cd ../wt-a
echo "A's half-done fix" >> app.txt
git stash push -m "agent-a: wip"
# agent B never stashed anything
cd ../wt-b
git stash list
git stash pop
cat app.txt

在 wt-b 中,git stash list显示有一个条目,创建于分支 agent-a,并带有你指定的说明。git stash pop将它应用到 wt-b/app.txt 并删除该条目,因为两个工作树都从同一个提交开始,而且改动可以干净地应用。回到 wt-a 并运行 git stash list:暂存列表为空,而那里的 app.txt 仍是 v1。A 尚未完成的修复现在只作为未提交的改动存在于 B 的文件夹中,位于 B 的分支上。

唯一的提示是标签。列表会在说明前显示 On agent-a:。单独使用 pop 不会读取它。

你可以观察 git 如何做出这个判断。在任一工作树中,查询每个路径解析到哪里:

cd ../wt-a
git rev-parse --git-path HEAD
git rev-parse --git-path index
git rev-parse --git-path refs/stash
git rev-parse --git-path logs/refs/stash

前两个解析到工作树在 .git/worktrees/wt-a/ 下的私有目录。后两个解析到主 .git。手册也用一个分支给出了相同的示例:--git-path HEAD在worktrees/<id>内解析,而 --git-path refs/heads/master“使用 $GIT_COMMON_DIR”,“因为所有工作树共享引用”。

手册对 git worktree add 的描述概括了这一点:新工作树会共享“一切,除了按工作树区分的文件,例如 HEAD、index 等”。结合 REFS 规则和仓库布局:

每个工作树独有所有工作树共享
HEAD及其 reflog(logs/HEAD )对象数据库
索引(暂存区)分支、标签、远程跟踪引用
伪引用( MERGE_HEAD 、ORIG_HEAD 等)refs/stash及其 reflog
refs/bisect 、refs/worktree 、refs/rewrittenconfig(除非选择启用config.worktree )
config.worktree,启用extensions.worktreeConfighooks/和info/

共享列的影响不止暂存区。智能体在 .git/hooks 中安装的钩子会在每个工作树中运行。智能体设置 git config 而不使用 --worktree,会改变所有工作树共用的仓库配置。根据手册的 CONFIGURATION FILE 章节,只有运行 git config extensions.worktreeConfig true 后才会有按工作树区分的配置。

共享暂存区是一个有意为之的设计选择。2015 年 7 月,在审阅一组关于将 CHERRY_PICK_HEAD 作为引用处理的补丁时,Junio Hamano 在 Git 邮件列表中写道:“我认为我们希望暂存区像 HEAD 一样,在所有工作树间共享,而 contrib/workdir 正是这样处理的。”

对一个人来说,共享暂存区很方便。你可以在一个检出目录中暂存改动,再在另一个目录中应用它,把改动移到另一个分支的文件夹里。这种设计假设暂存区只有一个所有者,而且他知道里面有什么。两个智能体并行运行就打破了这个假设。它们都不知道对方的存在,也都把 stash@{0} 当成“我的”。

A building with private rooms on each floor and one shared mailbox in the lobby

HEAD 和索引是独立的房间。分支、标签、配置、钩子和暂存区则位于共享大厅。

根据智能体要做的事情来选择方案。

**在任务分支上提交临时工作。**要暂时搁置工作,就创建提交。其他工作树不能检出该分支:git worktree add“当 是分支名称,且已被另一个工作树检出时,会拒绝创建新的工作树”,除非有人传入 --force。

git add -A
git commit -m "wip(task-142): before refactor"
# later: undo the commit, keep the changes staged
git reset --soft HEAD~1

**为失败测试检查创建一次性工作树。**问题中的两个智能体正在做的就是这项检查:证明没有修复时新测试会失败。先单独提交测试,这样 HEAD 中就有测试而没有修复。在该提交上创建一个分离头指针工作树,其中不会包含任何未提交改动,也不会触及其他人使用的内容。新工作树只包含受跟踪文件,因此要先在那里安装依赖项。

git add path/to/new.test.ts
git commit -m "test(task-142): failing test"
git worktree add --detach ../verify-142 HEAD
(cd ../verify-142 && npm ci && npm test)
git worktree remove ../verify-142

**在 refs/worktree/ 下创建临时引用。**如果你想要暂存区的行为,就把它放在这个命名空间中;根据手册,这里的内容不会共享。git stash create会创建一个暂存提交而不触碰暂存列表,而 git stash apply 接受“任何看起来像由 stash push 或 stash create 创建的提交”。这个做法借鉴了关于工作树共享状态的文章中的模式,该文章测试了创建、update-ref 和应用这些步骤:

sha=$(git stash create "task-142 wip")
[ -n "$sha" ] && git update-ref refs/worktree/wip "$sha" \
  && git reset --hard
# later, in this worktree only
git stash apply refs/worktree/wip
git update-ref -d refs/worktree/wip

有两点需要注意。git stash create只接受一条说明,因此不会记录未跟踪文件;没有内容可保存时也不会打印任何内容([ -n "$sha" ]防护条件会处理这种情况)。其他工作树仍可通过手册中的 worktrees/<name>/ 路径有意访问该引用,但 git stash list 和单独使用的 pop 都看不到它。

最后手段:命名暂存项,再按哈希应用。git stash list接受 git log 选项,因此你可以在每条说明旁打印哈希,再选择自己的那条:

git stash push -m "task-142: before refactor"
# later
git stash list --format='%gd %H %gs' | grep 'task-142:'
git stash apply <hash-from-that-line>

drop需要 stash@{n} 名称;每当另一个工作树推入暂存项,位置就会变化,因此在删除前要立即确认位置。如果 pop 或 drop 出了问题,它打印的“Dropped … (hash)”行就是你的恢复途径:只要提交仍然存在,git stash apply <hash>就能将它恢复。

objectstack 事故的修复记录在PR #6632中,做了两件事:它在仓库的智能体说明中加入警告,还添加了一个 PreToolUse 钩子 guard-shared-stash.sh,并在 .claude/settings.json 中接入。这个钩子会拦截会更改共享暂存栈的 git stash 子命令(push、pop、drop、clear 等),并允许 list、show 和 create,以及带有明确哈希的 apply 和 store。它已知的局限是:它只检查每个 shell 片段的第一个词,因此像 bash -c '…' 这样的包装调用可以绕过它。

说明会解释这条规则,让智能体选择安全的模式,而不是和钩子较劲。钩子则能拦住无视说明的智能体。一个最精简的 AGENTS.md 章节:

## Git in worktrees
- Never run bare `git stash`, `git stash pop` or
  `git stash drop`. The stash is shared by every
  worktree of this repository.
- To set work aside, commit it on your task branch:
  `git commit -m "wip(<task>): <why>"`.
- To test without your fix, commit the test alone,
  then use a detached worktree:
  `git worktree add --detach ../verify HEAD`.

Claude Code将 claude --worktree feature-auth作为并行会话的方案推出,而每增加一个会话,就多一个可以输入 git stash pop 的进程。

我开发了 Hermes IDE,请结合这一点看待上述内容。⌘N(Windows 和 Linux 上为 Ctrl+Shift+N)会在各自的工作树中为每项任务创建自己的 hermes/ 分支。这种隔离由普通 Git 提供,因此能隔离文件、HEAD和索引,而暂存区仍然共享。每个智能体都在真实终端中运行自己的 CLI,和在其他地方一样,因此它输入的 git stash 仍遵循上述规则。AGENTS.md章节仍应放在你的仓库中。

The Review Desk's Worktrees tab listing one Hermes worktree each for orders-api, web-app and orders-types

Review Desk 的 Worktrees 选项卡:在 ~/code 下分别为 orders-api、web-app 和 orders-types 创建一个 Hermes 工作树,并显示每个工作树的 hermes/ 分支、任务、使用时长和磁盘占用,以及可用磁盘空间。

变化在于智能体需要使用暂存区的频率。Hermes 会保存智能体的每一轮操作,因此你可以比较或恢复任意一轮,也可以撤销。“Agent replies”会话栏会列出每条回复及其修改的行;点击一条即可查看对应改动,或将文件恢复到那个时间点。每轮操作本来就有检查点,因此回到较早状态不需要使用暂存区。Review Desk(⌘G,或 Ctrl+Shift+G)会显示每项任务的工作树、分支、任务和占用空间,让你查看有哪些文件夹,以及每个文件夹由哪项任务使用。

Hermes 可免费下载,采用 BSL 1.1 源码可用许可,并可在 macOS、Windows 和 Linux 上运行。它与 Nous Research、Anthropic、OpenAI 或任何智能体供应商均无关联。下载,或在GitHub上阅读代码。关于 git worktree 会写入磁盘的全部内容,我在One .git, Five Checkouts一文中做了介绍。

objectstack 事故的修复一半靠 Git,一半靠说明:在 AGENTS.md 和 CLAUDE.md 中写明规则,告诉智能体为什么不能使用暂存区,以及应该怎么做。如何撰写这类规则,让智能体遵循而又不写成满篇大写字母的长篇说教,是我的 Prompt Engineering Pocket Guide 所涵盖的内容,从系统提示到指令文件,再到结构化输出。

Prompt Engineering Pocket Guide: Techniques for Getting the Most from LLMs