管理 Git 分支
按照一致的命名规范创建、切换、同步并清理分支。
适用场景
- 开始开发新功能或修复问题
- 在不同分支上的任务之间切换
- 将功能分支与 main 保持同步
- 合并 PR 后清理分支
- 列出和检查分支
输入
- 必需:至少有一个提交的仓库
- 可选:分支命名规范(默认:
type/description) - 可选:新分支的基础分支(默认:
main) - 可选:远程名称(默认:
origin)
步骤
第 1 步:创建功能分支
使用一致的命名规范:
| 前缀 | 用途 | 示例 |
|---|---|---|
feature/ |
新功能 | feature/add-weighted-mean |
fix/ |
问题修复 | fix/null-pointer-in-parser |
docs/ |
文档 | docs/update-api-reference |
refactor/ |
代码重构 | refactor/extract-validation |
chore/ |
维护性工作 | chore/update-dependencies |
test/ |
测试补充 | 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。
第 2 步:跟踪远程分支
首次推送新分支时设置跟踪关系:
# 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。
第 3 步:安全切换分支
切换前确保工作区干净:
# 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。
第 4 步:与上游同步
保持功能分支与基础分支的同步:
# 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。
第 5 步:清理已合并分支
PR 合并后,删除陈旧分支:
# 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 拒绝删除未合并的分支。若分支通过 GitHub 上的 squash merge 合并,Git 可能无法识别为已合并状态,确认工作已保存后可使用 git branch -D 强制删除。
第 6 步:列出并检查分支
# 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 log branch-name核实。 - 未清理远程引用:GitHub 上删除的远程分支在本地仍会显示,直到执行
git fetch --prune。
相关技能
commit-changes— 在分支上提交工作create-pull-request— 从功能分支创建 PRresolve-git-conflicts— 处理同步过程中的冲突configure-git-repository— 仓库设置与分支策略