跳到主要内容

Git Worktrees

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

  • 在同一个项目上并行运行多个 Agent，或者
  • 将实验性重构与主分支隔离

时，Git worktree 是在不复制整个仓库的前提下，为每个 Agent 提供独立检出的最安全方式。

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

为什么要将 Worktrees 与 Hermes 结合使用？​

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

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

如果你在同一个检出中运行多个 Agent，它们的变更可能会相互干扰：

  • 一个 Agent 可能删除或重写另一个 Agent 正在使用的文件。
  • 难以分辨哪些变更属于哪个实验。

使用 worktree 后，每个 Agent 都拥有：

  • 各自独立的分支和工作目录
  • 各自独立的检查点管理器历史，用于 /rollback

另见：检查点与 /rollback。

快速开始：创建 Worktree​

从主仓库（包含 .git/ 的目录）为功能分支创建新的 worktree：

# 从主仓库根目录
cd /path/to/your/repo

# 创建新分支并在 ../repo-feature 目录下创建 worktree
git worktree add ../repo-feature feature/hermes-experiment

这将创建：

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

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

cd ../repo-feature

# 在 worktree 中启动 Hermes
hermes

Hermes 将：

  • 将 ../repo-feature 视为项目根目录。
  • 使用该目录进行上下文文件、代码编辑和工具操作。
  • 使用独立的检查点历史，/rollback 的范围限定在此 worktree 中。

并行运行多个 Agent​

你可以创建多个 worktree，每个拥有各自的分支：

cd /path/to/your/repo

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

在不同的终端中：

# 终端 1
cd ../repo-experiment-a
hermes

# 终端 2
cd ../repo-experiment-b
hermes

每个 Hermes 进程：

  • 在各自的分支上工作（feature/hermes-a vs feature/hermes-b）。
  • 在不同的影子仓库哈希下写入检查点（由 worktree 路径派生）。
  • 可以独立使用 /rollback，不影响另一个进程。

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

  • 运行批量重构。
  • 对同一任务尝试不同的方案。
  • 将 CLI + 网关会话同时作用于同一上游仓库。

安全清理 Worktrees​

完成实验后：

  1. 决定是否保留相关工作。
  2. 如果想保留：
    • 按常规将分支合并到主分支。
  3. 删除 worktree：
cd /path/to/your/repo

# 删除 worktree 目录及其引用
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 提交来记录高层级里程碑。
    • 在此过程中使用检查点与 /rollback 作为工具驱动编辑的安全网。
  • 使用 worktree 时避免从裸仓库根目录运行 Hermes
    • 优先在 worktree 目录中运行，这样每个 Agent 的范围更清晰。

使用 hermes -w（自动 Worktree 模式）​

Hermes 内置 -w 标志，可自动创建一个一次性 git worktree 及其专属分支。无需手动设置 worktree — 只需 cd 进入你的仓库并运行：

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 worktree 为每个 Hermes 会话提供独立的干净检出。
  • 使用分支记录实验的高层级历史。
  • 使用检查点 + /rollback 在每个 worktree 内从错误中恢复。

这种组合带来：

  • 对不同 Agent 和实验互不影响的强有力保障。
  • 快速的迭代周期以及从错误编辑中轻松恢复的能力。
  • 干净、易于审查的 Pull Request。