sdlc/references/branch.md

分支規則 — SDLC 各階段動工前的分支確認

分析要讀對分支的程式碼，實作要寫進對的分支。兩件事都不能從「目前 checkout 的分支」推定使用者的意圖。

先確認，再動工

階段	要確認的分支	確認時機
analyze	來源分支——哪條分支的程式碼算現況	讀任何程式碼之前
implement	目標分支——這批工作要合併進哪條分支	寫任何檔案之前

確認方式：

1. 先把事實攤開：目前分支、工作區是否乾淨、遠端有哪些分支（git branch -r）、下節判定出的遠端預設分支。
2. 依 jsc-ask:ask 的決策樹詢問，每個選項都要標明影響範圍。分析錯分支會產出對不上程式碼的工作包；目標分支錯了則 PR 會開到錯的地方。
3. 把確認結果寫進產出（分析頁的來源分支欄、PR 的目標分支），後續步驟一律沿用同一個答案，不再自行改判。
4. 使用者沒回答就不預設 develop／master；預設值只在使用者明確同意後才成立。

判定遠端預設分支

1. 先用 git symbolic-ref --quiet refs/remotes/origin/HEAD，結果形如 refs/remotes/origin/<預設分支>。
2. 取不到時退而用 git remote show origin，找輸出中的 HEAD branch: 那行。
3. 兩者都取不到 → 回報並停止，不臆測 master／main。

需要基準或後備分支時（例如 PR 目標）：origin/develop 存在就用 develop；否則 origin/master 存在就用 master；兩者皆無則回報並停止。

只讀階段不動工作區

analyze 是 logic-only 階段：

• 需要換分支才能讀到正確現況時，停下來請使用者自己切換。
• 不代為 switch、不 stash、不動工作區、不建分支。

實作階段的分支選擇

• 只有來源分支與目標分支同名時才開新的工作分支：同名就不可在該分支上直接 commit，改從已更新到最新的目標分支建立新工作分支，後續操作都以新分支為準。不同名就在目前分支處理。
• 新分支名稱要可讀且不覆蓋既有分支；本地或遠端已存在同名分支時，換一個時間戳或短 hash。
• 切換或建立分支屬不可忽略的狀態變更，要在輸出中講清楚原因與結果分支名稱。

實作一律在 worktree 內進行

implement 動任何程式碼之前，先從分析頁記錄的來源分支建立 git worktree。所有修改都在 worktree 內，主工作目錄的分支與工作區完全不動。

路徑

{工作目錄}/.worktree/{分析頁 HASH}/{repo}

• {分析頁 HASH}：ANALYZE_{HASH} 的 HASH 部分，不含 ANALYZE_ 前綴。
• {repo}：存取庫名稱，不含 owner（HP/WebService.Buy → WebService.Buy）。不同 owner 的同名存取庫同時出現時，才改用 {owner}-{repo} 避免蓋掉，並在輸出中說明。
• 一份分析涉及多個存取庫時，每個存取庫各一個 worktree，並列在同一個 HASH 目錄下。

建立前先問分支怎麼處理

依 jsc-ask:ask 的決策樹詢問，每個選項標明影響範圍。固定兩個選項：

選項	指令	影響
以來源分支為基準開新工作分支	git worktree add -b {工作分支} {路徑} {來源分支}	commit 落在新分支，來源分支不動
直接簽出來源分支	git worktree add {路徑} {來源分支}	commit 直接進來源分支；同一分支不能同時簽出於兩處

不得自行預設，也不得跳過詢問。

建立時的鐵則

• 分支名與路徑一律加引號：來源分支可能含中文、空白或多層斜線（例如 feat/一址通/查地址/完整版/P2），不加引號會被切斷。
• 找不到該存取庫的本地 clone → 停下來問使用者路徑，不自行 clone、不臆測位置。
• 目標路徑已存在 → 不覆蓋。先確認它是不是同一份工作的 worktree（git worktree list），是就沿用，不是就回報並停止。
• 把 .worktree/ 加進該存取庫的 .git/info/exclude（不動使用者的 .gitignore，那是專案共用檔）。
• 建立後在輸出中明確列出：worktree 路徑、簽出的分支、來源分支。

移除時機

PR 建立成功後自動移除：git worktree remove {路徑}。

• 只有 jsc-git:pr 回報 PR 建立成功才移除；PR 失敗就保留，讓使用者能接手處理。
• worktree 內還有未提交變更時不移除，回報並停止——那些變更沒有進 PR，移除等於丟掉。
• 移除後順手 git worktree prune 清掉殘留記錄。
• 同一份分析的多個 worktree 全部移除後，若 .worktree/{HASH}/ 已空就一併刪掉那層目錄。

不破壞既有工作

• 工作區有未提交變更時，先提醒使用者 commit 或備份，絕不強制丟棄。
• 未提交變更導致切換分支或 pull 失敗 → 停止並回報，請使用者處理。
• 絕不 reset --hard／checkout -f／clean。