ce-worktree

Worktree 隔離

確保當前工作在隔離的工作空間中進行，不影響使用者的主 checkout。大多數程式碼 Harness 現在會在 Session 啟動時預設建立 worktree，因此常見情況是隔離環境已經存在 — 請先偵測此情況，不要建立重複的 worktree。

操作順序：偵測已有隔離 -> 優先使用原生 worktree 工具 -> 降級回原生 git 命令。 切勿建立 Harness 無法識別的 worktree。

兩種模式（根據呼叫方需求設定）：

• 新工作（預設）。 未指定具體的 ref — 從基底（trunk）建立全新分支。這也是 ce-work 使用的方式。
• 隔離既存 ref。 呼叫方指定要隔離工作的 ref — PR 的 head、既存分支或 commit。將 worktree 附加到該 ref，而非建立新分支。此模式受一條 Git 鐵律約束：同一個分支在同一時間只能被 checkout 到一個 worktree 中。 若指定的 ref 已經被 checkout 到某處（最常見的情況是它為主 checkout 的當前分支），請不要為其建立第二個 worktree — 直接回報它已在 <path> 處被 checkout，交由呼叫方決定後續操作（就地在此工作；或者僅在必須使用乾淨獨立 tree 的情況下，在相同的 commit 上建立 detached 抽離狀態的 worktree）。切勿將同一個分支同時放入兩個 worktree 中。

以下步驟（偵測 -> 原生工具 -> git 降級）適用於兩種模式；模式僅改變被 checkout 的內容以及回報給呼叫方的資訊。

步驟 0：偵測已有隔離

在建立任何內容之前，先檢查當前目錄是否已經是連結的 worktree。比較解析後的絕對路徑 git dir 與解析後的絕對路徑 common git dir — 先將各自解析為絕對路徑再行比較，而不是直接對比 git rev-parse 的原始輸出。Git 會根據當前目錄混合使用絕對與相對路徑格式（例如在一般 checkout 的子目錄中，--git-dir 會傳回絕對路徑，而 --git-common-dir 可能是相對路徑），因此直接進行字串比較會導致誤判為「已隔離」：

git rev-parse --absolute-git-dir                     # 此 worktree 的絕對 git dir
(cd "$(git rev-parse --git-common-dir)" && pwd -P)   # 共享 (common) 的絕對 git dir

若這兩個絕對路徑相同，表示這是一般 checkout — 繼續執行步驟 1。

若兩者不同，代表你目前處於連結的 worktree 或 submodule 中。區分方式如下：

git rev-parse --show-superproject-working-tree

• 非空輸出 -> 你處於 submodule 中；請將其視為一般 checkout 並繼續執行步驟 1。
• 空白輸出 -> 你已經在隔離的 worktree 中。請回報 worktree 的路徑（git rev-parse --show-toplevel）與當前分支。不要再建立另一個 worktree — 從 worktree 中再建立 worktree 會導致落入錯誤的 tree，且建立當前 worktree 的 Harness 也無法感知到它。接著直接就地工作：在「新工作」模式下，直接在此繼續；在「隔離既存 ref」模式下，直接在此 checkout 該 ref（除非它已經是當前分支），而不是嵌套建立 worktree。

步驟 1：優先使用 Harness 的原生 worktree 工具

如果 Harness 提供了原生的 worktree 基礎工具（例如 EnterWorktree / WorktreeCreate 工具、/worktree 指令或 --worktree 旗標），請直接使用它並結束流程。原生工具會自動放置、追蹤與清理 worktree，以便 Harness 進行管理。私下直接執行 git worktree add 會產生 Harness 無法視察、導覽或清理的幽靈狀態。

步驟 2：Git 降級方案

僅在沒有原生工具且步驟 0 未偵測到既存隔離環境時使用。

1. 在儲存庫根目錄執行。 下方的 .worktrees/ 與 .gitignore 路徑都是相對於儲存庫根目錄的，但 Skill 會從使用者的當前目錄執行（可能是一個子目錄）— 因此請先切到根目錄：cd "$(git rev-parse --show-toplevel)"。若不這麼做，.worktrees/<branch> 與 .gitignore 的修改會落入子目錄中（例如 src/.worktrees/...、src/.gitignore），而非儲存庫根目錄。
2. 根據工作描述選擇具有明確意義的分支名稱（例如 feat/login、fix/email-validation）— 避免使用難懂的自動生成名稱。選擇一個基底分支（預設：origin 的預設分支，否則為 main）。
3. 在建立任何內容前，確保 .worktrees/ 已被納入 gitignore，使 worktree 內容絕不會被 commit：檢查 git check-ignore -q .worktrees/ — 務必加上末尾斜線 /，這樣即使目錄尚未建立，也能符合已有的純目錄 .worktrees/ 規則（若使用沒有斜線的 git check-ignore .worktrees 會遺漏此規則，進而污染原本設定正確的儲存庫）。如果尚未被忽略，請在 .gitignore 中新增一行 .worktrees/。
4. 盡力更新基底分支，且不干擾當前的 checkout：git fetch origin <from-branch>。此操作非致命性 — 若發生錯誤（無 origin 遠端、遠端名稱不同或屬於純本地分支），請勿中斷，直接繼續下一步並使用本地 ref。
5. 建立 worktree — 指令取決於所選模式：
   • 新工作： git worktree add -b <branch-name> .worktrees/<branch-name> origin/<from-branch>（若 origin/<from-branch> 不存在則使用本地的 <from-branch> ref）。這會從基底建立一個新分支。
   • 隔離既存 ref： 附加到該 ref 而非建立分支 — 針對既存分支或 tag，使用 git worktree add .worktrees/<slug> <target-ref>。針對 PR，請將其 checkout 到本地分支上（切勿使用 detached FETCH_HEAD — 那會讓修正循環中的 commit 孤立，而無法更新 PR）：執行 git fetch origin pull/<n>/head:pr-<n> 接著執行 git worktree add .worktrees/pr-<n> pr-<n>。（若要恢復將 push 追蹤回 PR 的功能，可以先建立 detached 狀態的 worktree — git worktree add --detach .worktrees/pr-<n> — 再 cd 進去執行 gh pr checkout <n>，這對 fork 儲存庫很安全。）若 git 提示該 ref 已在其他地方 checkout，請遵循兩種模式中的「已 checkout」規則 — 切勿強行建立第二個 worktree。
6. 切換進去：cd .worktrees/<branch-name>（或 .worktrees/<slug>）。

若 git worktree add 因沙盒或權限錯誤而失敗，代表無法建立要求的隔離環境。在觸及當前 checkout 之前，這需要使用者做出阻塞式的決定 — 切勿在此處靜默繼續執行（使用者專門選擇隔離就是為了避免動到當前環境，尤其是當 ce-work / ce-code-review 是為了 worktree 選項而路由到此處時）。回報失敗原因，並透過平台的阻塞式詢問工具提出詢問：Claude Code 中的 AskUserQuestion（若其 Schema 未載入，請先使用 select:AskUserQuestion 呼叫 ToolSearch）、Codex 中的 request_user_input、Antigravity CLI (agy) 中的 ask_question、Pi 中的 ask_user（透過 pi-ask-user 擴充功能）— 提供選項如「在當前 checkout 中工作」與「停止並解決權限問題」。若 Harness 中不存在阻塞式工具或呼叫出錯，請在對話中列出編號選項並等待回覆；絕不要跳過確認步驟。只有在獲得明確確認後，才可在當前 checkout 中工作，且不要自動重試替代路徑。

其他 Worktree 操作

直接使用 git — 不需要封裝包裝器：

git worktree list                          # 列出 worktree
git worktree remove .worktrees/<branch>    # 移除 worktree
cd .worktrees/<branch>                     # 切換到 worktree
cd "$(git rev-parse --show-toplevel)"      # 返回當前 checkout 的根目錄

何時建立 Worktree

僅在尚未處於隔離環境，且需要獨立工作空間時才建立（步驟 1/2）：

• 在審閱 PR 的同時，保持當前 checkout 清空以進行其他工作
• 並行開發多個 Feature，省去分支切換的開銷

如果是可以在當前 checkout 分支上進行的單項任務，請勿建立 worktree — 若步驟 0 顯示你已處於 worktree 中，也絕不要建立。

整合機制

ce-work 與 ce-code-review 將此 Skill 作為備選選項提供。當使用者在這些流程中選擇「worktree」時，請先執行步驟 0：若工作已被隔離，請直接就地進行；否則請建立一個 worktree（優先使用原生工具），並根據工作描述賦予明確的分支名稱。

疑難排解

"Worktree already exists"：代表該路徑已被佔用。在重新建立前，請先切換過去（cd .worktrees/<branch>）或將其移除（git worktree remove .worktrees/<branch>）。

"Cannot remove worktree: it is the current worktree"：請先 cd 離開該 worktree，然後再執行 git worktree remove。