跳到主要内容

Git Worktrees

Hermes Agent 通常用于大型且长期存在的代码仓库。当你希望：

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

使用 Git worktrees 是最安全的方式，为每个代理提供独立的检出，而无需复制整个仓库。

本页将展示如何将 worktrees 与 Hermes 结合使用，确保每个会话都拥有一个干净、隔离的工作目录。

为什么在 Hermes 中使用 Worktrees？​

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

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

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

  • 一个代理可能删除或重写另一个代理正在使用的文件。
  • 更难判断哪些更改属于哪个实验。

使用 worktrees 后，每个代理将获得：

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

另请参阅：检查点与 /rollback。

快速入门：创建一个 Worktree​

在你的主仓库（包含 .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，在该目录中检出

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

cd ../repo-feature

# Start Hermes in the worktree
hermes

Hermes 将：

  • 将 ../repo-feature 视为项目根目录。
  • 使用该目录存放上下文文件、代码编辑和工具。
  • 使用一个独立的检查点历史记录，用于 /rollback，作用域限定于该 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）。
  • 将检查点写入不同的影子仓库哈希（由 worktree 路径推导得出）。
  • 可以独立使用 /rollback，而不会影响其他代理。

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

  • 批量重构。
  • 尝试同一任务的不同方法。
  • 将 CLI 会话与网关会话并行运行，针对同一上游仓库。

安全清理 Worktree​

当实验完成时：

  1. 决定是否保留该工作。
  2. 如果要保留：
    • 像往常一样将分支合并到主分支。
  3. 删除 worktree：
cd /path/to/your/repo

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

注意事项：

  • git worktree remove 会拒绝删除包含未提交更改的 worktree，除非强制执行。
  • 删除 worktree 不会自动删除分支；你可以使用正常的 git branch 命令来删除或保留该分支。
  • Hermes 的检查点数据位于 ~/.hermes/checkpoints/，在删除 worktree 时不会自动清理，但通常体积很小。

最佳实践​

  • 每个 Hermes 实验对应一个 worktree
    • 为每个重大变更创建专用的分支或 worktree。
    • 保持差异聚焦，使 PR 更小、更易审查。
  • 以实验名称命名分支
    • 例如：feature/hermes-checkpoints-docs、feature/hermes-refactor-tests。
  • 频繁提交
    • 使用 git 提交记录高层次里程碑。
    • 在工具驱动的编辑之间，使用 检查点与 /rollback 作为安全网。
  • 在使用 worktrees 时避免从裸仓库根目录运行 Hermes
    • 优先使用 worktree 目录，以确保每个代理都有明确的作用范围。

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

Hermes 内置了 -w 标志，可自动创建一个可丢弃的 Git worktree，并拥有自己的分支。你无需手动设置 worktrees —— 只需 cd 到你的仓库并运行：

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

Hermes 将：

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

这是获得 worktree 隔离的最简单方式。你还可以将其与单个查询结合使用：

hermes -w -q "Fix issue #123"

对于并行代理，打开多个终端并在每个终端中运行 hermes -w —— 每次调用都会自动获得自己的 worktree 和分支。

综合应用​

  • 使用 Git worktrees 为每个 Hermes 会话提供独立的干净检出。
  • 使用 分支 记录实验的高层次历史。
  • 使用 检查点 + /rollback 在每个 worktree 内部恢复错误。

这种组合为你提供：

  • 强有力的保证：不同代理和实验之间不会相互干扰。
  • 快速迭代周期，且能轻松恢复错误编辑。
  • 干净、可审查的拉取请求。