跳到主要内容

Git 工作树

Hermes Agent 经常被用于大型、长期维护的仓库。当你需要：

  • 在同一个项目上并行运行多个 agent，或者
  • 让实验性的重构与主分支保持隔离

那么 Git worktree 是为每个 agent 提供独立检出副本、同时又不必复制整个仓库的最安全方式。

本页介绍如何将 worktree 与 Hermes 结合使用，让每个会话都拥有干净、隔离的工作目录。

为什么要把 Git 工作树和 Hermes 搭配使用？​

Hermes 会把当前工作目录视为项目根目录：

  • CLI：你运行 hermes 或 hermes chat 时所在的目录
  • 消息网关：由 MESSAGING_CWD 指定的目录

如果你在同一个检出目录里运行多个 agent，它们的更改可能会互相干扰：

  • 一个 agent 可能会删除或重写另一个 agent 正在使用的文件
  • 很难判断哪些改动属于哪个实验

使用 worktree 后，每个 agent 都会得到：

  • 自己独立的分支和工作目录
  • 自己独立的 Checkpoint Manager 历史，供 /rollback 使用

另见：检查点与 /rollback。

快速开始：创建 Git 工作树​

在主仓库（包含 .git/）中，为某个功能分支创建一个新的 worktree：

# From the main repo root
cd /path/to/your/repo

# Create a new branch and worktree in ../repo-feature
git worktree add ../repo-feature feature/hermes-experiment

这会创建：

  • 一个新目录：../repo-feature
  • 一个新分支：feature/hermes-experiment，并在该目录中检出

现在你就可以进入这个新的 worktree 并在其中运行 Hermes：

cd ../repo-feature

# Start Hermes in the worktree
hermes

此时 Hermes 会：

  • 把 ../repo-feature 视为项目根目录
  • 在该目录中处理上下文文件、代码编辑和工具调用
  • 为这个 worktree 使用独立的检查点历史，供 /rollback 使用

并行运行多个 agent​

你可以创建多个 worktree，每个 worktree 使用自己的分支：

cd /path/to/your/repo

git worktree add ../repo-experiment-a feature/hermes-a
git worktree add ../repo-experiment-b feature/hermes-b

然后在不同终端中分别运行：

# Terminal 1
cd ../repo-experiment-a
hermes

# Terminal 2
cd ../repo-experiment-b
hermes

每个 Hermes 进程都会：

  • 在自己的分支上工作（feature/hermes-a 与 feature/hermes-b）
  • 将检查点写入不同的 shadow repo hash（由 worktree 路径派生）
  • 可以彼此独立地使用 /rollback，互不影响

这在以下场景中特别有用：

  • 运行批量重构
  • 针对同一任务尝试不同实现方案
  • 让 CLI 和网关会话同时面向同一个上游仓库工作

安全清理 Git 工作树​

当你完成某个实验后：

  1. 先决定是保留还是丢弃这部分工作。
  2. 如果要保留：
    • 像平常一样把该分支合并回主分支。
  3. 然后移除 worktree：
cd /path/to/your/repo

# Remove the worktree directory and its reference
git worktree remove ../repo-feature

注意：

  • 如果 worktree 里还有未提交更改，git worktree remove 会拒绝删除，除非你强制执行。
  • 删除 worktree 不会自动删除分支；你可以像平常一样用 git branch 命令保留或删除该分支。
  • 存放在 ~/.hermes/checkpoints/ 下的 Hermes 检查点数据不会在删除 worktree 时自动清理，不过它通常都很小。

最佳实践​

  • 每个 Hermes 实验都使用一个独立 worktree
    • 对每项重要改动创建专属分支和 worktree
    • 这样可以让 diff 更聚焦，PR 更小、更容易审查
  • 按实验内容命名分支
    • 例如 feature/hermes-checkpoints-docs、feature/hermes-refactor-tests
  • 频繁提交
    • 用 git commit 记录高层级里程碑
    • 中间工具驱动的编辑则使用 检查点与 /rollback 作为安全网
  • 在使用 worktree 时，不要从裸仓库根目录运行 Hermes
    • 优先在各自的 worktree 目录中运行，这样每个 agent 的作用范围都更明确

使用 hermes -w（自动 Git 工作树模式）​

Hermes 内置了 -w 标志，会自动创建一个一次性的 git worktree，并为其分配独立分支。你不需要手动设置 worktree，只需要进入仓库并运行：

cd /path/to/your/repo
hermes -w

Hermes 会：

  • 在仓库中的 .worktrees/ 下创建一个临时 worktree
  • 检出一个隔离分支（例如 hermes/hermes-<hash>）
  • 在该 worktree 中运行完整的 CLI 会话

这是获得 worktree 隔离最简单的方式。你也可以把它和单次查询结合起来：

hermes -w -q "Fix issue #123"

如果你想并行运行多个 agent，只需打开多个终端并分别运行 hermes -w，每次调用都会自动获得自己的 worktree 和分支。

串起来看​

  • 使用 git worktrees 给每个 Hermes 会话提供独立、干净的检出目录
  • 使用 branches 记录实验的高层历史
  • 使用 checkpoints + /rollback 在每个 worktree 内恢复误操作

这种组合会带来：

  • 强有力的隔离保证，不同 agent 和实验不会互相踩踏
  • 快速迭代，并且能方便地从错误编辑中恢复
  • 干净、易审查的 pull request