工作樹
工作樹
在 ChatGPT 桌面應用的 Codex 中使用 Git 工作樹並行執行聊天
工作樹讓 Codex 能夠在同一專案中執行多個相互獨立、互不干擾的聊天。儲存庫、工作樹和命令都保留在包含該專案的計算機或遠端開發環境中。你可以直接在 ChatGPT 桌面應用中工作，也可以在 ChatGPT 移動應用中使用 Remote，在連線的計算機上啟動、指導、核准和審查工作樹聊天。
對於 Git 儲存庫，計劃任務可以在專用的後臺工作樹上執行，避免與你正在進行的工作衝突。在未使用版本控制的專案中，計劃任務會直接在專案目錄中執行。你也可以手動在工作樹中啟動聊天，並使用 Handoff 在 Local 和 Worktree 之間移動聊天。
什麼是工作樹
工作樹僅適用於 Git 儲存庫中的專案，因為它們在底層使用 Git 工作樹。工作樹可讓你建立儲存庫的第二個副本（“檢出”）。每個工作樹都有儲存庫中每個檔案的獨立副本，但它們共享有關提交、分支等的相同後設資料（.git 資料夾）。因此，你可以並行檢出和處理多個分支。
術語
- 本機檢出：你建立的儲存庫。在 ChatGPT 桌面應用中有時簡稱為 Local。
- 工作樹：在 ChatGPT 桌面應用中從本機檢出建立的 Git 工作樹。
- Handoff：在 Local 和 Worktree 之間移動聊天的流程。Codex 會處理在二者之間安全移動工作所需的 Git 操作。
為什麼使用工作樹
- 與 Codex 並行工作，而不干擾當前的 Local 設定。
- 將工作排入後臺佇列，同時專注於前臺任務。
- 準備好檢查、測試或開展更直接的協作時，再將聊天移入 Local。
開始使用
工作樹需要 Git 儲存庫。請確保所選專案位於 Git 儲存庫中。
選擇“Worktree”
在新聊天檢視中，選擇編輯框下方的 Worktree。 你也可以選擇一個本機環境，為工作樹執行設定指令碼。
選擇起始分支
在編輯框下方，選擇工作樹所基於的 Git 分支。它可以是你的
main/master分支、功能分支，或包含未暫存本機更改的當前分支。提交提示詞
提交提示詞後，Codex 會基於所選分支建立 Git 工作樹。預設情況下，Codex 在“分離 HEAD”狀態下工作。
選擇繼續工作的位置
準備好後，你可以繼續直接在工作樹上工作，也可以將聊天移交給本機檢出。移交到 Local 或從 Local 移出時，會同時移動聊天和程式碼，以便你在另一個檢出中繼續工作。
在 Local 和 Worktree 之間工作
工作樹的外觀和使用體驗與本機檢出非常相似，區別在於它們在工作流程中的位置。你可以將 Local 視為前臺，將 Worktree 視為後臺。Handoff 可讓你在二者之間移動聊天。
在底層，Handoff 會處理在兩個檢出之間安全移動工作所需的 Git 操作。這一點很重要，因為 Git 只允許一個分支同時在一個位置被檢出。如果你在工作樹中檢出某個分支，就無法同時在本機檢出中檢出該分支，反之亦然。
實際使用中有兩種常見方式：
- 僅在工作樹上工作。如果你能直接在工作樹上驗證更改，例如已通過本機環境設定指令碼安裝依賴項和工具，那麼這種方式最合適。
- 將聊天移交給 Local。當你想將聊天移到前臺時可使用此方式，例如，你想在常用 IDE 中檢查更改，或只能執行一個應用執行個體。
選項 1：在工作樹上工作
如果你想帶著更改始終在工作樹上工作，請使用聊天標題欄中的 Create branch here 按鈕，將工作樹轉換為分支。
之後，你可以提交更改、將分支推送到遠端儲存庫，並在 GitHub 上建立拉取請求。
你可以使用標題欄中的“Open”按鈕在 IDE 中開啟工作樹，也可以使用整合終端，或在工作樹目錄中使用所需的任何其他工具。
選項 2：將聊天移交給 Local
如果你想將聊天移到前臺，請在聊天標題欄中選擇 Hand off，然後將其移動到 Local。
當你想在常用 IDE 視窗中檢視更改、執行現有開發伺服器，或在日常使用的同一環境中驗證工作時，這種方式非常合適。
Codex 會處理在工作樹和本機檢出之間安全移動聊天所需的 Git 步驟。
每個聊天會始終保留與同一個工作樹的關聯。如果之後將聊天交回工作樹，Codex 會讓它傳回同一個後臺環境，以便你從上次中斷的位置繼續。
由於 Handoff 使用 Git 操作，屬於 .gitignore 檔案的任何檔案都不會隨聊天移動，除非 Codex 使用 .worktreeinclude 將它們複製到本機託管工作樹中。
高階詳情
Codex 託管工作樹和永久工作樹
預設情況下，聊天使用 Codex 託管工作樹。它們旨在提供輕量且可隨時棄用的體驗。Codex 託管工作樹通常專用於一個聊天；如果你之後將該聊天交回工作樹，Codex 會讓它傳回同一個工作樹。
如果你需要長期存在的環境，請從側邊欄中專案的三點選單建立永久工作樹。這會將新的永久工作樹建立為獨立專案。永久工作樹不會被自動刪除，你可以從同一個工作樹啟動多個聊天。
Codex 如何為你管理工作樹
Codex 在 $CODEX_HOME/worktrees 中建立工作樹。起始提交是你啟動聊天時所選分支的 HEAD 提交。如果所選分支包含本機更改，Codex 也會將未提交的更改應用到工作樹。工作樹不會作為分支被檢出，而是處於分離 HEAD 狀態。這樣，Codex 無需讓你的分支變得雜亂，就能建立多個工作樹。
將忽略的本機檔案複製到託管工作樹
本機 Codex 託管工作樹從 Git 檢出開始，因此跟蹤的檔案已存在。如果儲存庫忽略了新工作樹所需的本機設定檔案，請將 .worktreeinclude 檔案新增到儲存庫根目錄，並列出 Codex 建立託管工作樹時要複製的忽略路徑或 .gitignore 風格的模式。
此功能適用於 Git 有意忽略的檔案，例如 .env、.env.local 或 config/secrets.json。Codex 只複製與 .worktreeinclude 匹配的忽略檔案；它不會複製 Git 未跟蹤的其他本機檔案。請勿列出已跟蹤的檔案。
Codex 會自動將忽略的 AGENTS.override.md 複製到本機託管工作樹，因此無需在 .worktreeinclude 中列出它。
# .worktreeinclude
.env
.env.local
config/secrets.jsonCodex 會跳過源符號連結，並且不會覆蓋新檢出中已存在的檔案。此行為適用於 ChatGPT 桌面應用在本機託管的工作樹，不適用於遠端工作樹或你自行從命令列建立的 Git 工作樹。
分支限制
假設 Codex 在某個工作樹上完成了一些工作，而你使用 Create branch here 在其上建立了 feature/a 分支。現在，你想在本機檢出中嘗試該分支。如果嘗試檢出該分支，將收到以下錯誤：
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'若要解決此問題，你需要在工作樹上檢出 feature/a 以外的其他分支。
如果你打算在本機檢出該分支，請使用 Handoff 將聊天移入 Local，不要嘗試讓同一個分支同時在兩個位置保持檢出狀態。
為什麼存在此限制
Git 不允許同一個分支同時在多個工作樹中檢出，因為分支代表單個可變引用（`refs/heads/檢出分支後，Git 會將其 HEAD 視為由該工作樹所有，並要求提交、重置、變基和合並等操作以定義明確的序列方式推進該引用。如果允許多個工作樹同時檢出同一個分支，就無法明確哪個工作樹的操作應更新分支引用，並會產生競態條件，可能導致提交丟失、索引不一致或衝突解決方式不明確。
通過強制實施每個工作樹一個分支的規則，Git 可保證每個分支只有一個權威工作副本，同時仍允許其他工作樹通過分離 HEAD 或獨立分支安全地引用相同提交。
工作樹清理
工作樹可能佔用大量磁碟空間。每個工作樹都有自己的一套儲存庫檔案、依賴項、建置快取等。因此，ChatGPT 桌面應用會嘗試將工作樹數量控制在合理範圍內。
預設情況下，Codex 會保留最近使用的 15 個 Codex 託管工作樹。如果你希望自行管理磁碟用量，可以在設定中更改此限制或關閉自動刪除。
Codex 會盡量避免刪除仍然重要的工作樹。在以下情況下，Codex 託管工作樹不會被自動刪除：
- 有置頂聊天與其關聯
- 聊天仍在進行中
- 該工作樹是永久工作樹
在以下情況下，Codex 託管工作樹會被自動刪除：
- 你歸檔了關聯的聊天
- Codex 需要刪除較舊的工作樹，以保持在你設定的限制以內
刪除 Codex 託管工作樹之前，Codex 會儲存其中工作的快照。如果你在工作樹被刪除後開啟聊天，將看到恢復該工作樹的選項。