---
title: "Git worktree 共享 stash：并行代理可能取走彼此的改动"
canonical: "https://siyuanailab.com/curation/translations/ce68d41dc0c7b8f6586edcd7619b68fd-f9bf28384bbf79c0d4e9a44145b47d5bcf2e3892eaac9db11db549af7e2884a6/"
dateModified: "2026-11-06"
datePublished: "2026-11-06"
---

[返回日报条目](https://siyuanailab.com/curation/#entry/ce68d41dc0c7b8f6586edcd7619b68fd)

 

资料节译

 

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

 

[阅读原文](https://dev.to/gabrielanhaia/git-stash-is-shared-across-worktrees-two-parallel-agents-popped-each-others-work-19m2)

 

现有资料无法确认原文完整，本页只翻译已取得的材料。

 

现有原件无法确认图片是否齐全。

 

-

 

## **书籍：**[Prompt Engineering Pocket Guide](https://www.amazon.com/dp/B0GX38N645)

 

## **我还写了：***Thinking in Go*（2 册系列）—[Complete Guide to Go Programming](https://xgabriel.com/go-book) +[Hexagonal Architecture in Go](https://xgabriel.com/hexagonal-go)

 

## **我的项目：**[Hermes IDE](https://hermes-ide.com/) |[GitHub](https://github.com/hermes-hq/hermes-ide) — 为使用 Claude Code 和其他 AI 编程工具交付代码的开发者打造的 IDE

 

**我：**[xgabriel.com](https://xgabriel.com/) |[GitHub](https://github.com/gabrielanhaia)

 

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

 

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

 

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

 

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

 

再看[git-stash 手册](https://git-scm.com/docs/git-stash)：“你最近创建的暂存保存在 `refs/stash` 中；更早的暂存可在该引用的 reflog 中找到。”

 

`refs/stash`以 `refs/` 开头，且不在例外列表中。因此，每个仓库只有一个暂存区，而不是每个工作树各有一个。较早的条目位于该引用的 reflog 中，而[gitrepository-layout](https://git-scm.com/docs/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](/curation/media/d0a2c0ef8fb590ba388e1ecb7c4f6db0f037558be920438776169859689541cf.webp)

 

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

 

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

 

```
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/rewritten` | `config`（除非选择启用`config.worktree` ） |
| `config.worktree`，启用`extensions.worktreeConfig` | `hooks/`和`info/` |

 

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

 

共享暂存区是一个有意为之的设计选择。2015 年 7 月，在审阅一组关于将 `CHERRY_PICK_HEAD` 作为引用处理的补丁时，Junio Hamano 在 Git 邮件列表中写道：“[我认为我们希望暂存区像 HEAD 一样，在所有工作树间共享](https://lore.kernel.org/git/?q=%22we+want+stash%2C+unlike+HEAD%2C+to+be+shared+across+worktrees%22)，而 contrib/workdir 正是这样处理的。”

 

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

 

![A building with private rooms on each floor and one shared mailbox in the lobby](/curation/media/c3873f486afaed6efd015c5cf4ed8342f25554a8df6b529aafc993e11d7d13bc.webp)

 

*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` 创建的提交”。这个做法借鉴了[关于工作树共享状态的文章](https://amitkoth.com/git-worktree-shared-state/)中的模式，该文章测试了创建、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](https://github.com/objectstack-ai/objectstack/pull/6632/files)中，做了两件事：它在仓库的智能体说明中加入警告，还添加了一个 `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](https://code.claude.com/docs/en/common-workflows#run-parallel-sessions-with-worktrees)将 `claude --worktree feature-auth`作为并行会话的方案推出，而每增加一个会话，就多一个可以输入 `git stash pop` 的进程。

 

我开发了 [Hermes IDE](https://hermes-ide.com/)，请结合这一点看待上述内容。⌘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](/curation/media/7e2448e84e15a53a990bc93bbec1b4920e2bf57fa64ae2803fa7b2f581524f83.webp)

 

*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 或任何智能体供应商均无关联。[下载](https://hermes-ide.com/download)，或在[GitHub](https://github.com/hermes-hq/hermes-ide)上阅读代码。关于 `git worktree` 会写入磁盘的全部内容，我在[One .git, Five Checkouts](https://dev.to/gabrielanhaia/one-git-five-checkouts-how-git-worktree-works-under-your-parallel-agents-34bp)一文中做了介绍。

 

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

 

![Prompt Engineering Pocket Guide: Techniques for Getting the Most from LLMs](/curation/media/672261d6a9921518c4c2a1d0d013de98226a0a21fe111a7221cf8a4be8daba50.webp)

 

AI 翻译；具体表述请与原文对照。
