H繁中版
文件user-guidegit worktrees
<!-- Source: https://hermesbible.com/docs/user-guide/git-worktrees -->

章節：使用 Hermes · 網址：https://hermesbible.com/docs/user-guide/git-worktrees

Hermes Agent 通常用於大型、長時間維護的軟體倉庫。當你想要：

  • 在同一專案中並行執行多個 Agent，或
  • 將實驗性的重構工作與主分支隔離，

Git worktree 是最安全的方式，讓每個 Agent 擁有自己的工作副本，而無需複製整個倉庫。

本頁說明如何將 worktree 與 Hermes 結合使用，讓每個工作階段都有一個乾淨、隔離的工作目錄。

為什麼要搭配 Hermes 使用 Worktree？

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

  • CLI：執行 hermes 或 hermes chat 的目錄
  • 訊息閘道：透過 ~/.hermes/config.yaml 中 terminal.cwd 設定的目錄

如果你在同一個工作副本中執行多個 Agent，它們的變更可能會互相干擾：

  • 某個 Agent 可能會刪除或覆寫另一個 Agent 正在使用的檔案。
  • 更難以分辨哪些變更屬於哪個實驗。

使用 worktree 後，每個 Agent 都能獲得：

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

另請參閱：Checkpoints 與 /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 使用獨立的 checkpoint 歷史記錄，範圍限於此 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）。
  • 在不同的 shadow repo 雜湊值下寫入 checkpoint（由 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/checkpoints/ 下的 Hermes checkpoint 資料在移除 worktree 時不會自動被清理，但通常體積很小。

最佳實踐

  • 每個 Hermes 實驗使用一個 worktree
    • 為每個重要的變更建立專屬的分支/worktree。
    • 這樣可以讓 diff 保持聚焦，PR 保持小型且易於審查。
  • 以實驗名稱為分支命名
    • 例如 feature/hermes-checkpoints-docs、feature/hermes-refactor-tests。
  • 頻繁提交
    • 使用 git commits 記錄高層級的里程碑。
    • 使用 checkpoints 與 /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 -z "Fix issue #123"

若要並行執行多個 Agent，開啟多個終端機並在每個終端機中執行 hermes -w —— 每次呼叫都會自動獲得自己的 worktree 和分支。

綜合運用

  • 使用 git worktrees 讓每個 Hermes 工作階段都有乾淨的工作副本。
  • 使用分支記錄實驗的高層級歷史。
  • 使用 checkpoints + /rollback 從每個 worktree 內的錯誤中恢復。

這種組合為你提供：

  • 強而有力的保證，確保不同的 Agent 和實驗不會互相干擾。
  • 快速的迭代週期，輕鬆從錯誤編輯中恢復。
  • 乾淨、可審查的 Pull Request。

Docker

x searchbluebubbles