管理 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

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

  — 从功能分支创建 PR

• resolve-git-conflicts

  — 处理同步过程中的冲突

• configure-git-repository

  — 仓库设置与分支策略