跳到主要內容

Git Worktrees

Hermes Agent 通常用於大型且長期存在的代碼倉庫。當你希望：

  • 在同一項目上並行運行多個 Agent，或
  • 將實驗性重構與主分支隔離，

使用 Git worktrees 是最安全的方式，為每個 Agent 提供獨立的檢出，而無需複製整個倉庫。

本頁將展示如何將 worktrees 與 Hermes 結合使用，確保每個會話都擁有一個乾淨、隔離的工作目錄。

為什麼在 Hermes 中使用 Worktrees？​

Hermes 將 當前工作目錄 視為項目根目錄：

  • CLI：你運行 hermes 或 hermes chat 的目錄
  • 消息網關：由 MESSAGING_CWD 設置的目錄

如果你在同一個檢出中運行多個 Agent，它們的更改可能會相互干擾：

  • 一個 Agent 可能刪除或重寫另一個 Agent 正在使用的文件。
  • 更難判斷哪些更改屬於哪個實驗。

使用 worktrees 後，每個 Agent 將獲得：

  • 自己的分支和工作目錄
  • 獨立的 Checkpoint Manager 歷史記錄，用於 /rollback

另請參閱：檢查點與 /rollback。

快速入門：創建一個 Worktree​

在你的主倉庫（包含 .git/）中，為一個特性分支創建一個新的 worktree：

# 從主倉庫根
cd /path/to/your/repo

# 創建一個新分支並在“0”中創建“1”
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 與 feature/hermes-b）。
  • 將檢查點寫入不同的影子倉庫哈希（由 worktree 路徑推導得出）。
  • 可以獨立使用 /rollback，而不會影響其他 Agent。

這在以下場景中特別有用：

  • 批量重構。
  • 嘗試同一任務的不同方法。
  • 將 CLI 會話與網關會話並行運行，針對同一上游倉庫。

安全清理 Worktree​

當實驗完成時：

  1. 決定是否保留該工作。
  2. 如果要保留：
    • 像往常一樣將分支合併到主分支。
  3. 刪除 worktree：
cd /path/to/your/repo

# 刪除worktree目錄及其引用
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 目錄，以確保每個 Agent 都有明確的作用範圍。

使用 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"

對於並行 Agent，打開多個終端並在每個終端中運行 hermes -w —— 每次調用都會自動獲得自己的 worktree 和分支。

綜合應用​

  • 使用 Git worktrees 為每個 Hermes 會話提供獨立的乾淨檢出。
  • 使用 分支 記錄實驗的高層次歷史。
  • 使用 檢查點 + /rollback 在每個 worktree 內部恢復錯誤。

這種組合為你提供：

  • 強有力的保證：不同 Agent 和實驗之間不會相互干擾。
  • 快速迭代週期，且能輕鬆恢復錯誤編輯。
  • 乾淨、可審查的拉取請求。