工作樹

工作樹可讓 Codex 在同一個專案中執行多個彼此獨立的對話，且互不干擾。程式碼庫、工作樹和指令都會保留在包含該專案的電腦或遠端開發環境中。你可以直接使用 ChatGPT 桌面版應用程式，或透過 ChatGPT 行動版應用程式中的遠端功能，在已連線的電腦上開始、引導、核准及審查工作樹對話。

對於 Git 程式碼庫，排程任務可在專用的背景工作樹上執行，避免與進行中的工作衝突。在未納入版本控制的專案中，排程任務會直接在專案目錄中執行。你也可以手動在工作樹中開始對話，並透過移交功能在本機與工作樹之間移動對話。

什麼是工作樹

工作樹僅適用於屬於 Git 程式碼庫的專案，因為其底層採用Git 工作樹。工作樹可讓你建立程式碼庫的第二份副本，也就是「簽出」。每個工作樹都有程式碼庫中所有檔案各自的副本，但所有工作樹共用提交、分支等相关中繼資料（.git 資料夾）。因此，你可以簽出多個分支並平行作業。

術語

• 本機簽出：你建立的程式碼庫。在 ChatGPT 桌面版應用程式中，有時簡稱為 本機 。
• 工作樹：在 ChatGPT 桌面版應用程式中，從本機簽出建立的Git 工作樹。
• 移交：在本機與工作樹之間移動對話的流程。Codex 會處理必要的 Git 作業，確保你的工作能安全地在兩者之間移動。

為什麼要使用工作樹

1. 與 Codex 平行處理工作，而不影響目前的本機設定。
2. 將背景工作排入佇列，同時專注於前景工作。
3. 等你準備好進行更直接的檢查、測試或協作時，再將對話移至本機。

開始使用

工作樹需要 Git 程式碼庫。請確認你選取的專案位於 Git 程式碼庫中。

在本機與工作樹之間作業

工作樹的外觀與操作體驗和本機簽出十分相似，差別在於兩者在工作流程中的定位。你可以把本機視為前景，將工作樹視為背景。移交功能可讓你在兩者之間移動對話。

移交功能會在底層處理必要的 Git 作業，以便在兩個簽出之間安全地移動工作。這一點十分重要，因為 Git 一次只允許在一個位置簽出同一個分支。如果你在工作樹上簽出某個分支，就 無法 同時在本機簽出中簽出該分支，反之亦然。

實務上，常見做法有兩種：

1. 只在工作樹上作業。如果你能直接在工作樹上驗證變更，例如已透過本機環境設定指令碼安裝相依項目與工具，這種做法最合適。
2. 將對話移交至本機。如果你想將對話移到前景，例如在常用的 IDE 中檢查變更，或應用程式一次只能執行一個執行個體，請採用這種做法。

選項 1：在工作樹上作業

如果你只想在工作樹上處理變更，請使用對話標頭中的 在此建立分支 按鈕，將工作樹轉為分支。

接著，你可以提交變更、將分支推送至遠端程式碼庫，並在 GitHub 上開啟 Pull Request。

你可以使用標頭中的「開啟」按鈕，在 IDE 中開啟工作樹；也可以使用整合式終端，或從工作樹目錄執行其他所需操作。

Create branch

Test and edit changes on this worktree

Branch nameSet prefix

codex/

Create

請注意，如果你在工作樹上建立分支，就無法在任何其他工作樹中簽出該分支，包括本機簽出。

選項 2：將對話移交至本機

你也可以反向操作。如果你已在本機作業，並想騰出前景，請使用 移交 將對話移至工作樹。當你想讓 Codex 在背景繼續作業，同時將注意力轉回本機上的其他工作時，這項功能很實用。

由於移交功能使用 Git 作業，任何列在 .gitignore 檔案中的檔案都不會隨對話移動，除非 Codex 使用 .worktreeinclude 將這些檔案複製到本機受管理的工作樹中。

進階資訊

Codex 管理的工作樹與永久工作樹

依預設，對話會使用 Codex 管理的工作樹。這類工作樹設計為輕量且可隨時捨棄。Codex 管理的工作樹通常專供單一對話使用；如果你稍後將對話移交回工作樹，Codex 會將它送回同一個工作樹。

如需長期使用的環境，請透過側邊欄中專案的三點選單建立永久工作樹。這會建立新的永久工作樹，並將其作為獨立專案。永久工作樹不會自動刪除，而且你可以在同一個工作樹中開始多個對話。

Codex 如何為你管理工作樹

Codex 會在 $CODEX_HOME/worktrees 中建立工作樹。起始提交是開始對話時所選分支的 HEAD 提交。如果選擇的分支有本機變更，Codex 也會將未提交的變更套用至工作樹。工作樹不會簽出為分支，而是處於分離的 HEAD 狀態。如此一來，Codex 可以建立多個工作樹，而不會讓你的分支變得雜亂。

將已忽略的本機檔案複製到受管理的工作樹

本機上由 Codex 管理的工作樹以 Git 簽出為起點，因此已包含受追蹤的檔案。如果程式碼庫忽略了新工作樹所需的本機設定檔案，請在程式碼庫根目錄新增 .worktreeinclude 檔案，並列出要複製的已忽略路徑或 .gitignore 格式的比對模式，以便 Codex 建立受管理工作樹時一併複製。

此功能適用於刻意讓 Git 忽略的檔案，例如 .env、.env.local 或 config/secrets.json。Codex 只會複製符合 .worktreeinclude 的已忽略檔案，不會複製 Git 未追蹤的其他本機檔案。請勿列出受追蹤的檔案。

Codex 會自動將已忽略的 AGENTS.override.md 複製到本機受管理的工作樹，因此不需要在 .worktreeinclude 中列出該檔案。

# .worktreeinclude
.env
.env.local
config/secrets.json

Codex 會略過來源中的符號連結，也不會覆寫新簽出中已存在的檔案。這項行為適用於 ChatGPT 桌面版應用程式在本機管理的工作樹，不適用於遠端工作樹，也不適用於你自行透過指令列建立的 Git 工作樹。

分支限制

假設 Codex 在工作樹上完成部分工作後，你選擇透過 在此建立分支在該工作樹上建立 feature/a 分支。現在，你想在本機簽出中試用這個分支。如果嘗試簽出該分支，就會收到以下錯誤：

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

若要解決此問題，你必須在工作樹上改為簽出另一個分支，而不是 feature/a。

如果打算在本機簽出該分支，請使用移交功能將對話移至本機，而不要嘗試在兩個位置同時簽出同一個分支。

工作樹清理

工作樹可能會占用大量磁碟空間。每個工作樹都有各自的程式碼庫檔案、相依套件、建置快取等。因此，ChatGPT 桌面版應用程式會盡量將工作樹數量維持在合理範圍內。

Codex 預設會保留最近的 15 個由 Codex 管理的工作樹。如果您偏好自行管理磁碟用量，可以在設定中變更此上限，或關閉自動刪除功能。

Codex 會盡量避免刪除仍然重要的工作樹。若符合下列情況，由 Codex 管理的工作樹不會自動刪除：

• 有已釘選的對話與該工作樹關聯
• 對話仍在進行中
• 該工作樹是永久工作樹

由 Codex 管理的工作樹會在下列情況下自動刪除：

• 您封存與該工作樹關聯的對話
• Codex 需要刪除較舊的工作樹，才能將數量維持在您設定的上限內

刪除由 Codex 管理的工作樹前，Codex 會儲存其中工作內容的快照。如果您在工作樹刪除後開啟與其關聯的對話，便會看到還原該工作樹的選項。

常見問題