git-worktree

Git Worktree

沒有 worktree 是在使用者不知道其位置、來源與離開方式的情況下產生的。沒有 worktree 是在使用者未要求的情況下被刪除的。

此技能在三個方面優先於其他建立 worktree 的技能（例如 superpowers:using-git-worktrees）：位置、名稱和核准。其他技能的其餘流程仍然有效。

依代理程式區分的工具

動作	Claude Code	Codex
建立	git worktree add + EnterWorktree(path: ...) 以移動會話	git worktree add 並使用 git -C/workdir 在 worktree 內工作
隔離的子代理程式	使用 isolation: "worktree" 的 Agent（建立在 .claude/worktrees/ 中）	不適用
離開	ExitWorktree(action: "keep")	返回原始目錄
報告	pwsh -NoProfile -File "<此技能所在資料夾>/scripts/worktrees-report.ps1"	相同

<此技能所在資料夾> 是此 SKILL.md 檔案所在的目錄。此指令碼需要 PowerShell 7+ (pwsh)。

1. 建立之前

1. 檢查您是否已在 worktree 中（git rev-parse --git-dir 與 git rev-parse --git-common-dir 不同，且不在子模組中）。如果是，未經使用者要求請勿建立其他 worktree。
2. 在相關的儲存庫上執行報告，並儲存結果以備步驟 4 使用：

   pwsh -NoProfile -File "<此技能所在資料夾>/scripts/worktrees-report.ps1" -Path "<repo1>;<repo2>"
   

3. 使用以下模板建構計劃，並為每個 worktree 呈現一個區塊：

   Worktree 計劃
   - 儲存庫:     C:\repos\loja
   - 基礎分支:     origin/main @ 3f2a9c1 (git fetch 已執行)
   - 新分支:     claude/feat-login-google
   - 名稱:            feat-login-google
   - 絕對路徑：  C:\repos\loja\.worktrees\feat-login-google
   - 相對路徑：  .worktrees\feat-login-google
   - 指令：            git -C "C:\repos\loja" worktree add "C:\repos\loja\.worktrees\feat-login-google" -b claude/feat-login-google origin/main
   - 刪除方式：         git -C "C:\repos\loja" worktree remove "C:\repos\loja\.worktrees\feat-login-google"
                      git -C "C:\repos\loja" branch -d claude/feat-login-google
   

   如果儲存庫有子模組（.gitmodules），請在計劃中告知刪除時需要 --force 以及原因。
4. 緊接著在其下方，顯示這些儲存庫中已開啟的 worktree 之報告表格（Worktree、Tamanho、Branch、O que eu perco）。如果沒有任何 worktree，請用一行說明。
5. 等待使用者明確確認。 然後才進行建立。在 Claude Code 中，外掛程式的掛勾會在指令執行時要求額外確認。在 Codex 中，codex/rules/git-worktree.rules 規則對 git worktree add 執行相同操作。

對於並行的多個子代理程式，請呈現一個包含所有 worktree 的單一計劃，並僅要求一次確認。

標準

• 位置： <儲存庫根目錄>/.worktrees/<名稱>，適用於兩個代理程式。唯一的例外是 Claude Code 中使用 isolation: "worktree" 的子代理程式，它始終建立在 .claude/worktrees/ 中；在這種情況下，請在計劃中報告該路徑。
• 忽略資料夾而不提交： 在建立之前，執行 git -C <repo> check-ignore -q .worktrees/x。如果資料夾未被忽略，請將 .worktrees/ 新增至儲存庫的 info/exclude 檔案（路徑在 git -C <repo> rev-parse --git-path info/exclude）。此檔案是本地檔案，不會產生提交。告知您已執行此操作。
• 名稱： <類型>-<簡短描述>，使用 kebab-case，最多 40 個字元。範例：feat-login-google、fix-timeout-pagamento。
• 新分支： <代理程式>/<名稱>，即 claude/feat-login-google 或 codex/feat-login-google。如果儲存庫有自己的分支慣例（掛勾、CONTRIBUTING、歷史紀錄），請遵循儲存庫的慣例並說明是哪一種。
• 基礎： 預設情況下，使用使用者在主要 checkout 所在的 branch。如果任務與其無關，則使用 origin/<預設分支>。請先執行 git fetch 並顯示基礎分支的短哈希值。

2. Worktree 報告

當使用者要求列出或清理 worktree 時，以及在上述步驟 1.2 中使用。

pwsh -NoProfile -File "<此技能所在資料夾>/scripts/worktrees-report.ps1" [-Path "<根目錄或儲存庫>;..."] [-Json] [-SkipSize] [-Depth 6]

• 如果沒有 -Path，指令碼會使用 GIT_WORKTREE_ROOTS 變數，如果沒有則使用目前目錄。如果使用者的指示（CLAUDE.md、AGENTS.md）定義了一個儲存庫根資料夾，請傳遞該資料夾。
• 此指令碼為 read-only。它會尋找儲存庫、子模組以及儲存庫資料夾外部的孤立 worktree。
• 如果使用者想要速度，請使用 -SkipSize。當需要詳細資訊時（領先/落後的提交數、遠端狀態、合併情況、最後提交日期、裁決和刪除指令），請使用 -Json。

顯示指令碼輸出的表格，並精確地使用這四個欄位，順序如下：

欄位	內容
Worktree	絕對路徑
Tamanho	磁碟空間
Branch	worktree 的分支，或 (detached @ <hash>)
O que eu perco	Nada，或刪除時會遺失的項目清單：未提交的檔案、僅存在於該處的提交、被 git 忽略的檔案（例如 .env）。建置資料夾（node_modules、bin、obj...）不計入

請勿新增欄位。詳細資訊顯示在表格下方，僅在有助於決策時才顯示。

被視為遺失的項目：

• 已修改或新增但未提交的檔案。
• 不存在於任何遠端、目前分支或預設分支中的提交。
• 非建置用途的已忽略檔案。
• 在已初始化的子模組中：未提交的檔案以及僅存在於其中的提交。
• 被鎖定的 worktree（git worktree lock）會顯示 (travado...)，且未經確認不會被刪除。
• 如果資料夾已不存在，該欄位會顯示 Nada (a pasta já não existe...)。使用 git worktree prune 解決。
• 限制：squash 或 rebase 合併不會被偵測到，因此這些提交會顯示為遺失。如果使用者表示 PR 已合併，請在遠端確認。

報告結尾應提供刪除不會遺失任何項目的 worktree 時可釋放的空間。

刪除指令

當使用者要求刪除，或要求提供指令時，請使用 -Json 中的 ComandosRemocao 欄位。精確地按順序複製指令，並放在一個區塊中。不要憑記憶撰寫指令。該欄位已處理三個陷阱：

1. 被忽略的檔案： 如果存在會遺失的已忽略檔案（例如 .env、.superpowers/），前幾個指令會將它們複製到 ~/worktree-backup/<repo>/<worktree>。複製必須在刪除之前進行：刪除後，就沒有東西可以複製了。
2. 子模組： 如果 worktree 有已初始化的子模組，刪除時會使用 --force，因為沒有它 git 會拒絕 git worktree remove。在提供此指令之前，請確認「O que eu perco」欄位顯示子模組沒有遺失任何內容，或者使用者已接受遺失。
3. 分支： 最後，git branch -d 會刪除分支，但僅在分支已整合的情況下才會成功。

如果您要親自執行，請一次執行一個指令，並在第一個錯誤時停止。

3. 任務結束時

• 如果 worktree 的工作已整合（已合併或推送到遠端），請使用準備好的指令提議刪除。
• 如果尚未整合，請說明缺少什麼：提交、推送、PR。
• 在 Claude Code 中，使用 ExitWorktree(action: "keep") 離開，並僅在使用者確認後才透過 git 刪除。ExitWorktree(action: "remove") 僅適用於該會話中由 EnterWorktree 建立的 worktree。

不變的規則

• 未經使用者要求，絕不刪除 worktree 或 branch。一次刪除一個，並在最後再次執行報告。
• 未經對該 worktree 的明確確認，絕不使用 git branch -D 或 ExitWorktree(discard_changes: true)。僅當 worktree 有子模組（請參閱「刪除指令」）且使用者已看到遺失的內容時，才使用 git worktree remove --force。
• 絕不在未呈現計劃並獲得確認的情況下建立 worktree。