---

name: manage-git-branches locale: wenyan-lite source_locale: en source_commit: aa73494d fence_basis_commit: aa73494d translator: "Julius Brussee homage — caveman" translation_date: "2026-04-24" description: > Create, track, switch, sync, and clean up Git branches. Covers naming conventions, safe branch switching with stash, upstream synchronization, and pruning merged branches. Use when starting work on a new feature or bug fix, switching between tasks on different branches, keeping a feature branch up to date with main, or cleaning up branches after merging pull requests. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.1" domain: git complexity: intermediate language: multi tags: git, branches, branching-strategy, stash, remote-tracking

管 Git 分支

創、追、換、同步，並清分支，循一致命名慣。

適用時機

• 始新功能或錯修之工作
• 於異分支之任間切換
• 保功能分支與 main 同步
• 合並拉取請求後清分支
• 列並察分支

輸入

• 必要：至少有一提交之倉
• 選擇性：分支命名慣（默認：type/description）
• 選擇性：新分支之基分支（默認：main）
• 選擇性：遠程名（默認：origin）

步驟

步驟一：創功能分支

用一致命名慣：

Prefix	Purpose	Example
feature/	New functionality	feature/add-weighted-mean
fix/	Bug fix	fix/null-pointer-in-parser
docs/	Documentation	docs/update-api-reference
refactor/	Code restructuring	refactor/extract-validation
chore/	Maintenance	chore/update-dependencies
test/	Test additions	test/add-edge-case-coverage

# Create and switch to a new branch from main
git checkout -b feature/add-weighted-mean main

# Or using the newer switch command
git switch -c feature/add-weighted-mean main

預期： 新分支已創並檢出。git branch 示新分支附星號。

失敗時： 若基分支於本地不存，先取：git fetch origin main && git checkout -b feature/name origin/main。

步驟二：追遠程分支

首次推新分支時設追蹤：

# Push and set upstream tracking
git push -u origin feature/add-weighted-mean

# Check tracking relationship
git branch -vv

檢出他人所創之遠程分支：

git fetch origin
git checkout feature/their-branch
# Git auto-creates a local tracking branch

預期： 本地分支追對應遠程分支。git branch -vv 示上游。

失敗時： 若自動追蹤敗，手設之：git branch --set-upstream-to=origin/feature/name feature/name。

步驟三：安全切換分支

換前確工作樹淨：

# Check for uncommitted changes
git status

若變存，提或暫之：

# Option 1: Commit work in progress
git add <files>
git commit -m "wip: save progress on validation logic"

# Option 2: Stash changes temporarily
git stash push -m "validation work in progress"

# Switch branches
git checkout main

# Later, restore stashed changes
git checkout feature/add-weighted-mean
git stash pop

列並管暫：

# List all stashes
git stash list

# Apply a specific stash (without removing it)
git stash apply stash@{1}

# Drop a stash
git stash drop stash@{0}

預期： 分支切換成。工作樹反映目標分支之態。暫變可復。

失敗時： 若切換被未提會遭覆之變阻，先暫或提。git stash 不能暫未追文件除非用 git stash push -u。

步驟四：與上游同步

保功能分支與基分支同步：

# Fetch latest changes
git fetch origin

# Rebase onto latest main (preferred — keeps linear history)
git rebase origin/main

# Or merge main into your branch (creates merge commit)
git merge origin/main

預期： 分支今含 main 之最新變。無衝突，或衝突已解（見 resolve-git-conflicts）。

失敗時： 若 rebase 致衝突，解每一並 git rebase --continue。若衝突過複，以 git rebase --abort 中止而試 git merge origin/main。

步驟五：清合並之分支

拉取請求合並後，除陳分支。先確每分支之工作已達 main，因 git branch -d 不答此問（見下文「失敗時」）。二事須並立。其一，代碼託管平台須報 PR 已合入 main：gh pr view <n> --json state,baseRefName,headRefOid,mergeCommit 示 MERGED 與 main。其二，本地分支不得含 PR 所無之提交：git merge-base --is-ancestor <branch> <headRefOid> 以 0 退出。headRefOid 乃平台所合之 PR 頭，故此一驗於合並提交、squash 合並與 rebase 合並皆適用。僅憑 PR 之態不足，因其不見 PR 從未有之本地提交。

退出碼 1 謂分支含此類提交（末次推送後所作者，或遠程分支因強推而失者）：留其分支。退出碼 128 謂 PR 頭不存於本地，如分支刪前他人曾推至該 PR：以 git fetch origin refs/pull/<n>/head 取之（分支刪後 GitHub 仍存此引用），再行此驗。若為合並提交，以合並提交驗祖先（同一 gh 輸出之 mergeCommit.oid，須先行 git fetch origin main）亦答同一問。squash 合並，及改寫提交之 rebase 合並，依其構造必不過此合並提交之驗，因其提交皆新，不含分支之提交；然仍過 headRefOid 之驗。唯 MERGED 與退出碼 0 並具，方許刪。下方代碼塊列諸刪除之式以備參。驗過之後，git branch -D 乃安；其 -d 行若被拒，即「失敗時」所述之情。

# Delete a local branch that has been merged
git branch -d feature/add-weighted-mean

# Delete a local branch (force, even if not merged)
git branch -D feature/abandoned-experiment

# Delete a remote branch
git push origin --delete feature/add-weighted-mean

# Prune remote-tracking references for deleted remote branches
git fetch --prune

預期： 合並分支於本地與遠程已除。git branch 僅示活分支。

失敗時： git branch -d 非合並之驗（#865、#900）。據 git help branch，分支須已全合入其上游，若未設上游則須全合入 HEAD；經實測（git 2.43），示為 gone 之上游視同無上游，故查 HEAD。是故以 -u 推送（步驟二）且已全推之分支，無論曾否達 main 皆過此查：-d 刪之，以 0 退出，僅於 stderr 印一警告（deleting branch … that has been merged to 'refs/remotes/origin/…', but not yet merged to HEAD）。若再依序行上方代碼塊，遠程分支亦被刪，無一引用存其工作。無上游之分支，則對執行命令之工作樹之 HEAD 而查，故若 HEAD 為含此分支之堆疊分支，-d 刪之而 stderr 全無一字。反之，凡所查之引用缺分支之末端，-d 即拒刪確已合並之分支：一為遠程分支刪後、上游既去之 HEAD（如尚未更新之本地 main），一為落後於末端之上游，因末端自他處克隆推出而尚未取。末端因某提交從未推送而超前其上游者，非此情：該提交不在任何 PR，拒之乃正。squash 合並之分支，唯所查之引用缺其末端時方被拒，如上游既去後之 HEAD；其自推之上游尚存時，-d 刪之。無論何向，其答皆同：行本步驟開首之驗，唯驗過方以 git branch -D 刪之。

步驟六：列並察分支

# List local branches
git branch

# List all branches (local and remote)
git branch -a

# List branches with last commit info
git branch -v

# List branches merged into main
git branch --merged main

# List branches NOT yet merged
git branch --no-merged main

# See which remote branch each local branch tracks
git branch -vv

預期： 所有分支、其態與追關係之清視。

失敗時： 若遠程分支顯陳，行 git fetch --prune 以清已刪遠程分支之引用。

驗證

• 分支名循已議之命名慣
• 功能分支自正確基分支創
• 本地分支追其遠程對應
• 合並分支已清（本地與遠程）
• 切換分支前工作樹淨
• 暫變未遺孤

常見陷阱

• 於 main 直工作：恒創功能分支。直提於 main 難開 PR 與協作
• 分支前忘取：自陳本地 main 創分支謂始即落後。恒先 git fetch origin
• 長存分支：存數周之功能分支累衝突。常同步並保分支短存
• 孤暫：git stash 為臨存。勿依之作長期工作。提或分支代之
• 刪未合工作：二刪除旗標皆不可單恃。git branch -D 不論合並與否皆刪；git branch -d 則刪已全推至自身上游之未合分支，或於無上游時，刪當前 HEAD 所含而 main 未含之分支（無任何警告）。用任一前，先行步驟五開首之驗：PR 已 MERGED 入 main，且 git merge-base --is-ancestor <branch> <headRefOid> 以 0 退出
• 未修剪：GitHub 上已刪之遠程分支於本地仍顯直至 git fetch --prune

相關技能

• commit-changes - 提分支上之工作
• create-pull-request - 自功能分支開 PR
• resolve-git-conflicts - 同步中之衝突處理
• configure-git-repository - 倉設與分支策略