finishing-a-development-branch

完成開發分支

概述

透過提供明確選項並處理所選工作流程，引導開發工作的完成。

核心原則： 驗證測試 → 偵測環境 → 呈現選項 → 執行選擇 → 清理。

開始時宣告： 「我正在使用 finishing-a-development-branch 技能來完成這項工作。」

流程

步驟 1：驗證測試

在呈現選項之前，先驗證測試是否通過：

# 執行專案的測試套件
npm test / cargo test / pytest / go test ./...

如果測試失敗：

測試失敗（<N> 個失敗）。必須先修正才能完成：

[顯示失敗]

在測試通過之前，無法繼續進行合併/PR。

停止。不要繼續到步驟 2。

如果測試通過： 繼續到步驟 2。

步驟 2：偵測環境

在呈現選項之前，先判斷工作區狀態：

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)

這決定了要顯示哪個選單以及清理方式：

狀態	選單	清理
GIT_DIR == GIT_COMMON（一般儲存庫）	標準 4 個選項	無需清理工作樹
GIT_DIR != GIT_COMMON，具名分支	標準 4 個選項	基於來源（見步驟 6）
GIT_DIR != GIT_COMMON，detached HEAD	精簡 3 個選項（無合併）	無需清理（外部管理）

步驟 3：決定基礎分支

# 嘗試常見的基礎分支
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

或詢問：「這個分支是從 main 分支出來的——對嗎？」

步驟 4：呈現選項

一般儲存庫與具名分支工作樹——呈現以下 4 個選項：

實作完成。您想做什麼？

1. 合併回 <base-branch>（本機）
2. 推送並建立 Pull Request
3. 保留分支現狀（我之後再處理）
4. 捨棄這個工作

請選擇？

Detached HEAD——呈現以下 3 個選項：

實作完成。您處於 detached HEAD（外部管理工作區）。

1. 推送為新分支並建立 Pull Request
2. 保留現狀（我之後再處理）
3. 捨棄這個工作

請選擇？

不要加入說明——保持選項簡潔。

步驟 5：執行選擇

選項 1：本機合併

# 取得主要儲存庫根目錄以確保 CWD 安全
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# 先合併——在移除任何東西之前確認成功
git checkout <base-branch>
git pull
git merge <feature-branch>

# 驗證合併結果的測試
<test command>

# 只有在合併成功後：清理工作樹（步驟 6），然後刪除分支

然後：清理工作樹（步驟 6），再刪除分支：

git branch -d <feature-branch>

選項 2：推送並建立 PR

# 推送分支
git push -u origin <feature-branch>

不要清理工作樹——使用者需要它存活以根據 PR 回饋進行迭代。

選項 3：保留現狀

回報：「保留分支 <name>。工作樹保留在 <path>。」

不要清理工作樹。

選項 4：捨棄

先確認：

這將永久刪除：
- 分支 <name>
- 所有提交：<commit-list>
- 位於 <path> 的工作樹

請輸入 'discard' 確認。

等待確切的確認。

如果確認：

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

然後：清理工作樹（步驟 6），再強制刪除分支：

git branch -D <feature-branch>

步驟 6：清理工作區

僅在選項 1 和 4 時執行。 選項 2 和 3 一律保留工作樹。

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
WORKTREE_PATH=$(git rev-parse --show-toplevel)

如果 GIT_DIR == GIT_COMMON： 一般儲存庫，無需清理工作樹。完成。

如果工作樹路徑位於 .worktrees/ 或 worktrees/ 下： Superpowers 建立了這個工作樹——我們負責清理。

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git worktree remove "$WORKTREE_PATH"
git worktree prune  # 自我修復：清理任何過時的註冊

否則： 主機環境（harness）擁有這個工作區。不要移除它。如果您的平台提供了工作區退出工具，請使用它。否則，將工作區留在原地。

快速參考

選項	合併	推送	保留工作樹	清理分支
1. 本機合併	是	-	-	是
2. 建立 PR	-	是	是	-
3. 保留現狀	-	-	是	-
4. 捨棄	-	-	-	是（強制）

常見錯誤

跳過測試驗證

• 問題： 合併有問題的程式碼，建立失敗的 PR
• 修正： 在提供選項之前務必驗證測試

開放式問題

• 問題： 「接下來該做什麼？」過於模糊
• 修正： 呈現恰好 4 個結構化選項（或 detached HEAD 時 3 個）

為選項 2 清理工作樹

• 問題： 移除了使用者需要迭代 PR 的工作樹
• 修正： 僅在選項 1 和 4 時清理

在移除工作樹之前刪除分支

• 問題： git branch -d 失敗，因為工作樹仍參考該分支
• 修正： 先合併，移除工作樹，再刪除分支

從工作樹內部執行 git worktree remove

• 問題： 當 CWD 位於要移除的工作樹內部時，指令會靜默失敗
• 修正： 在 git worktree remove 之前，一律 cd 到主要儲存庫根目錄

清理 harness 擁有的工作樹

• 問題： 移除 harness 建立的工作樹會導致幽靈狀態
• 修正： 僅清理位於 .worktrees/ 或 worktrees/ 下的工作樹

捨棄時未確認

• 問題： 意外刪除工作
• 修正： 要求輸入 "discard" 確認

紅旗

絕對不要：

• 在測試失敗時繼續
• 未驗證結果測試就合併
• 未經確認就刪除工作
• 未經明確要求就強制推送
• 在確認合併成功之前移除工作樹
• 清理非您建立的工作樹（來源檢查）
• 從工作樹內部執行 git worktree remove

務必：

• 在提供選項之前驗證測試
• 在呈現選單之前偵測環境
• 呈現恰好 4 個選項（或 detached HEAD 時 3 個）
• 對選項 4 取得輸入確認
• 僅在選項 1 和 4 時清理工作樹
• 在移除工作樹前 cd 到主要儲存庫根目錄
• 移除後執行 git worktree prune