规范 Git 分支开发流程（Git 团队协作指南）
适用于：团队成员对 Git 仓库具有直接写权限的协作场景
文档类型：正式规范（企业内部使用风格）
版本：v1.0
修订日期：2025-11-22
1. 目的
本指南旨在统一团队在 Git 项目开发过程中的 Git 分支使用规范，确保代码协作有序开展、历史记录清晰、避免冲突与冗余分支，提高开发效率与交付质量。
2. 基本概念
| 名称 | 说明 |
|---|---|
| 主干分支（main/master） | 项目稳定分支，仅用于发布稳定版本和受控合并 |
| 功能分支（feature/*） | 用于开发新功能，完成后通过 PR 合并主干 |
| 修复分支（fix/*） | 用于修复非紧急类缺陷 |
| 紧急修复分支（hotfix/*） | 用于紧急修复生产环境问题 |
| 提交（Commit） | 记录代码变更的基础单位，应保持小步提交、信息规范 |
| 推送（Push） | 将本地分支提交同步到远程仓库 |
| 重基（Rebase） | 将当前分支提交移到最新主干提交之后，以保持历史线性 |
| 上游关系（Upstream） | 本地分支与远程分支建立的追踪关系 |
备注：本文档主要包含 feature 分支工作模式，不含 Fork 工作流。
3. 分支策略与命名规范
3.1 分支分类
| 分支类别 | 用途 | 示例 |
|---|---|---|
main |
稳定主干分支，禁止直接开发与提交 | main |
feature/* |
新功能开发，完成后通过 PR 合并 | feature/user-login |
fix/* |
修复一般问题 | fix/password-reset |
hotfix/* |
修复紧急线上问题 | hotfix/null-pointer |
chore/* |
杂项工作、依赖升级、构建配置 | chore/upgrade-deps |
docs/* |
文档相关工作 | docs/api-guide |
3.2 功能分支命名要求
- 使用短横线
-分隔单词 - 命名应表达该分支对应的功能内容
✅feature/user-comment
❌feature/dev1、test_branch
4. 标准开发流程（适用于有写权限的团队协作）
以下流程为规范操作步骤，所有开发工作应遵循：
步骤 1：从主干创建功能分支
git switch main
git pull --ff-only
git switch -c feature/<feature-name>
步骤 2：本地开发与提交
git add -p
git commit -m "feat(<scope>): <description>"
提交信息建议遵循 Conventional Commits（见附录 7）。
步骤 3：定期与主干同步（避免冲突）
在功能开发周期中，如主干有更新，需同步：
git fetch origin
git rebase origin/main
说明：
git fetch origin获取远程所有更新（不改变本地当前分支）git rebase origin/main将当前分支的提交移动到最新 main 之后，提前解决冲突
步骤 4：首次推送并建立上游关系
git push -u origin feature/<feature-name>
说明：
-u用于为当前分支建立 upstream 追踪关系- 建立后后续可直接使用
git push/git pull无需再指定远端和分支名
步骤 5：发起合并请求（PR/MR）
在远程仓库创建 PR，说明变更内容、测试情况及影响范围，等待评审与 CI 测试通过。
开发期间如需继续更新，只需继续
commit+push即可更新 PR。
步骤 6：PR 合并后清理分支
远程 PR 合并后，需删除本地与远程分支：
# 删除本地分支
git switch main
git pull --ff-only
git branch -d feature/<feature-name>
# 删除远程分支
git push origin -d feature/<feature-name>
# 清理已不存在的远程分支引用
git fetch -p
5. 各关键操作说明（含原问题解答）
5.1 为什么需要在本地新建分支进行开发？
- 保持主干稳定，避免出现不可控问题
- 每个功能独立开发，方便测试、审查与回滚
- 避免多人开发相互影响
5.2 为什么需要推送功能分支到远端？
- 便于团队协作、代码审查、CI 检查
- 不会造成仓库混乱，因为合并后会删除
- 推送分支是规范流程，而不是将开发留在本地
5.3 git push -u 的意义
- 建立本地分支与远程分支的追踪关系
- 之后可直接执行
git pull/git push而无需带参数
若忘记添加，可补救：
git branch --set-upstream-to=origin/feature/<feature-name>
5.4 git fetch origin 的作用
- 更新远程状态到本地（包括所有远端分支）
- 不影响当前开发分支
- 为后续
rebase提供最新的主干指针
5.5 git rebase origin/main 的作用
- 将当前分支基于最新
main更新，减少合并冲突 - 使提交历史更清晰（线性）
- 在本地提前解决冲突，更利于 PR 合并
5.6 是否必须推送开发分支到远程？
是的。推送远程后：
- 可创建 PR，接受评审
- 避免因本地损坏丢失代码
- 合并后删除即可，不会污染仓库
5.7 错误说明：refs/remotes/origin/HEAD cannot be resolved
出现原因：命令写法错误，例如：
git push origin -u origin feature/test-api # 错误示例
正确命令应为：
git push -u origin feature/test-api
或当前分支下：
git push -u origin HEAD
6. 分支清理与维护规范
- 所有
feature/*分支必须在合并后删除 - 本地与远端均需删除
- 定期清理本地与远程跟踪引用
7. 提交信息规范（建议）
推荐使用 Conventional Commits 格式：
<type>(<scope>): <description>
常用类型：
| 类型 | 用途 |
|---|---|
| feat | 新功能 |
| fix | 修复缺陷 |
| docs | 文档变更 |
| style | 格式变动（不影响逻辑） |
| refactor | 重构代码 |
| test | 测试相关 |
| chore | 构建、工具、依赖升级 |
示例：
feat(auth): add JWT login endpoint
fix(api): resolve null pointer on user info fetch
8. 常用命令清单（按阶段）
初始化
git clone <repo-url>
git switch main
git pull --ff-only
创建分支
git switch -c feature/<name>
开发期间
git add -p
git commit -m "feat: xxx"
git fetch origin
git rebase origin/main
推送与更新
git push -u origin feature/<name>
git push --force-with-lease # 若有 rebase
合并后清理
git switch main
git pull --ff-only
git branch -d feature/<name>
git push origin -d feature/<name>
git fetch -p
9. 总结
- 所有开发必须基于
feature/*分支进行 - 主干代码禁止直接开发与提交
- 推送功能分支到远端是规范流程，不会造成混乱
- 合并后应删除远端与本地分支，保持仓库整洁
- 使用
fetch+rebase减少冲突，保持历史线性 -u用于建立上游关系，推荐使用
（完）