跳到主要内容

Git Worktrees

Hermes Agent 常用于大型、长期存在的仓库。当你想：

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

Git worktrees 是给每个 Agent 自己的干净检出的最安全方式，而无需复制整个仓库。

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

为什么将 Worktrees 与 Hermes 一起使用？​

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

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

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

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

使用 worktrees，每个 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 在该目录中检出

现在你可以进入新的 worktree 并在那里运行 Hermes：

cd ../repo-feature

# 在 worktree 中启动 Hermes
hermes

Hermes 会：

  • 将 ../repo-feature 视为项目根目录。
  • 使用该目录进行上下文文件、代码编辑和工具。
  • 使用独立的检查点历史，作用域到这个 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）。
  • 在不同的 shadow repo 哈希下写入检查点（从 worktree 路径派生）。
  • 可以独立使用 /rollback 而不影响另一个。

这在以下情况下特别有用：

  • 运行批量重构。
  • 尝试同一任务的不同方法。
  • 在相同上游仓库上配对 CLI + 网关会话。

安全清理 Worktrees​

当你完成一个实验时：

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

# 移除 worktree 目录及其引用
git worktree remove ../repo-feature

注意：

  • git worktree remove 除非你强制它，否则会拒绝移除有未提交更改的 worktree。
  • 移除 worktree 不会自动删除分支；你可以使用正常的 git branch 命令删除或保留分支。
  • 当你移除 worktree 时，Hermes 检查点数据 ~/.hermes/checkpoints/ 不会自动清理，但它通常非常小。

最佳实践​

  • 每个 Hermes 实验一个 worktree
    • 为每个实质性更改创建专用分支/worktree。
    • 这保持差异集中，PR 小而可审查。
  • 用实验名称命名分支
    • 例如 feature/hermes-checkpoints-docs、feature/hermes-refactor-tests。
  • 频繁提交
    • 使用 git 提交作为高层里程碑。
    • 使用检查点和 /rollback 作为工具驱动编辑之间的安全网。
  • 使用 worktrees 时避免从裸仓库根目录运行 Hermes
    • 优先使用 worktree 目录，这样每个 Agent 都有清晰的范围。

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

Hermes 有一个内置的 -w 标志，自动创建一个可丢弃的 git worktree，它有自己的分支。你不需要手动设置 worktrees — 只需进入你的仓库并运行：

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 会话自己的干净检出。
  • 使用分支捕获实验的高层历史。
  • 使用检查点 + /rollback 在每个 worktree 中从错误编辑中恢复。

这种组合给你：

  • 强有力的保证，不同 Agent 和实验不会相互干扰。
  • 快速迭代周期，轻松从错误编辑中恢复。
  • 干净、可审查的 pull requests。