Git worktree 怎麼用？隔離多個 AI coding agent 的工作目錄

worktree 和 clone、branch 差在哪裡#

branch 是版本線；worktree 是讓多個版本線同時有實體工作目錄；clone 則是另一份 repository。對多個 agent 的工作流來說，可以先用這張表判斷：

Git 會管理 linked worktree 的 metadata，因此不要手動刪除 .git/worktrees/ 下的內容來「清理」工作目錄。建立、移動、移除與修復都應透過 git worktree 指令完成。

建立一個 agent 專用工作目錄#

先在主要 repository 確認目前沒有未預期的修改，再用一個新的路徑和新分支建立工作目錄。下面的 ../zeroone-agent-auth 只是示例，main 要換成你實際要作為基準的 branch：

1
git status --short
2
git worktree add ../zeroone-agent-auth -b agent/auth main

建立成功後，agent 應該只在新目錄裡工作：

1
cd ../zeroone-agent-auth
2
git status --short
3
git branch --show-current

另一個任務使用不同路徑與分支：

1
git worktree add ../zeroone-agent-tests -b agent/tests main

分支名稱不是安全邊界，但明確命名能讓 agent handoff、PR 與清理紀錄更容易對上。不要讓兩個 agent 共用同一個工作目錄，也不要讓它們同時 checkout 同一個 branch；Git 會阻止部分重複 checkout，但工作流不應把這個阻擋當成協調機制。

先列出所有工作目錄，再交給 agent#

在任何 agent 開始前，從主要 repository 執行：

1
git worktree list --porcelain

--porcelain 適合保存到 log 或交給腳本解析。每個工作目錄至少確認三件事：路徑、目前 branch、HEAD。交接任務時可把這些資訊和任務說明放在一起：

1
工作目錄：../zeroone-agent-auth
2
分支：agent/auth
3
任務：只修改登入流程與測試，完成後執行 pnpm check
4
完成條件：列出變更檔案、測試輸出與尚未處理的風險

這種完成條件和 AI coding agent 的可驗證完成狀態 是同一個原則：agent 不只要說「完成」，還要留下可以檢查的檔案、指令與結果。

合併前先在各自目錄檢查#

agent 完成後，不要直接在主要工作目錄猜哪些檔案可以合併。先在 agent worktree 留下可重現的檢查：

1
git status --short
2
git diff --stat
3
git diff --check

如果 worktree 裡有未追蹤檔案，先確認它們是否屬於任務。不要讓 agent 為了「清空狀態」直接刪除未知檔案；要嘛加入正確的 commit，要嘛把未完成原因交給下一個人。

回到主要工作目錄後，先更新基準 branch，再合併 agent branch：

1
cd ../ZeroOne
2
git switch main
3
git pull --ff-only
4
git merge --no-ff agent/auth

如果 merge 有衝突，先停下來標記衝突檔與決策，不要讓另一個 agent 在同一個 worktree 裡繼續覆寫。多個 agent 的價值是把工作檔案分開，不是消除設計衝突或 review。

完成後安全移除與 prune#

合併並確認 branch 不再需要後，先移除 linked worktree，再刪除已合併的 branch：

1
git worktree remove ../zeroone-agent-auth
2
git branch -d agent/auth
3
git worktree prune --dry-run
4
git worktree prune

git worktree remove 會針對工作目錄執行 Git 的清理檢查；若裡面還有未提交的工作，先保存或交接，不要習慣性加上 --force。prune --dry-run 可以先查看 Git 認為已遺失的 metadata，確認後才執行真正的 prune。

若工作目錄曾被手動搬到別的路徑，先用 git worktree repair 修復連結，再判斷是否要移除：

1
git worktree repair ../zeroone-agent-auth

這些命令處理的是 Git metadata，不會替你清理 agent 產生的外部服務、Docker volume、暫存資料或 secrets。那些資源要依專案自己的生命週期另外回收。

worktree 不會隔離哪些東西#

這是多 agent 工作流最容易被誤解的邊界。worktree 會把不同 branch 的檔案狀態分開，但下面這些資源可能仍然共用：

• .env、shell 環境變數、SSH agent 與登入憑證。
• 固定的 localhost port、共用的 Docker Compose project name 與 named volume。
• 同一個本機資料庫、測試 bucket、queue 或外部 API 帳號。
• 工作目錄之外的快取、全域套件與 editor 設定。

因此讓 agent 同時跑測試時，為每個 worktree 分配不同 port、測試資料庫或 Compose project name；敏感資料則使用最小範圍的測試 secret。若任務需要真正的檔案系統或網路隔離，應再加上容器、sandbox 或不同帳號，不能只靠 git worktree。

結論：一個任務、一個 worktree、一個完成證據#

Git worktree 最適合處理「同一 repository 同時有多個分支工作」的檔案隔離問題。建立時分配獨立路徑與 branch，交接前用 git worktree list --porcelain 和 git status 驗證，合併前保存 diff 與測試結果，完成後用 worktree remove 和 prune 清理。它能降低 agent 互相覆蓋檔案的風險，但不會替你隔離 port、資料庫或 secrets；那些邊界要在工作流中明確寫出來。

常見問題#