Git 分支与提交命名规范

花言巧语大佩奇

559人浏览 · 2026-07-10 16:20:33

花言巧语大佩奇 · 2026-07-10 16:20:33 发布

版本： 2.0
适用范围： 通用软件工程团队（与具体项目/产品线无关）
参考标准： Conventional Commits、Semantic Versioning、Git Flow、GitHub Flow

1. 总则

1.1 命名基本原则

规则	说明
全小写	分支名、标签名一律使用小写字母与数字
连字符分隔	多词之间用 `-`（kebab-case），不使用 `_` 或驼峰
斜杠分层	短期分支使用 `<类型>/<描述>` 形式，便于分组与权限管理
语义清晰	名称应体现变更类型 + 变更意图，避免 `fix`、`temp`、`test` 等无意义命名
短而准	描述部分建议 2～5 个英文单词，总长不超过 50 字符
ASCII 优先	优先使用英文；若团队统一使用中文拼音，需全团队一致并写入规范

1.2 推荐与禁止示例

1.3 分支策略选型

团队应在以下模型中择一为主，并在规范中明确默认合入目标：

模型	适用场景	核心长期分支
GitHub Flow	持续交付、Web/SaaS、单主干	`main`
Git Flow	版本化发布、需发布冻结期	`main` + `develop`
Trunk-Based Development	高频集成、强 CI/CD	`main`（短期分支 ≤ 2 天）

下文以 Git Flow + Conventional Commits 为默认叙述（业界最常见组合），采用 GitHub Flow 的团队可忽略 develop 相关条目。

2. 长期分支（Long-lived Branches）

长期分支受保护（Protected Branch），禁止直接 force push，仅通过 Pull Request / Merge Request 合入。

分支名	用途	说明
`main`	生产基线	与线上发布版本一致；仅接受 `release/`、`hotfix/` 合入（Git Flow）或所有已评审变更（GitHub Flow）
`master`	生产基线（历史命名）	与 `main` 等价；新仓库优先使用 `main`
`develop`	集成开发主干	日常开发集成分支；功能/fix 分支的默认合入目标（Git Flow）

约束

长期分支禁止 --force 推送
合入前须通过 CI 与 Code Review
不在长期分支上直接开发（紧急 hotfix 除外）

3. 短期分支（Short-lived Branches）

从对应的长期分支拉取，完成工作后通过 PR/MR 合入，合入后删除远程分支。

3.1 功能分支 — `feature/`

用于新功能、需求迭代、非紧急重构。

feature/<简短描述>
feature/<issue-id>-<简短描述>    # 关联 Issue 时推荐

字段	规则	示例
简短描述	动宾或名词短语，kebab-case	`oauth2-login`、`export-csv`
issue-id	可选，与 Tracker 一致	`123`、`PROJ-456`

示例

feature/oauth2-login
feature/123-export-user-report
feature/shopping-cart-checkout

工作流（Git Flow）

develop ──► feature/oauth2-login ──► PR ──► develop

3.2 缺陷修复分支 — `fix/` 或 `bugfix/`

用于开发/测试阶段发现的缺陷修复（非生产紧急问题）。

fix/<简短描述>
fix/<issue-id>-<简短描述>

示例

fix/null-pointer-on-logout
fix/456-email-validation-regex

fix/ 与 bugfix/ 语义相同，团队择一统一；Conventional Commits 中对应类型均为 fix。

与 hotfix/ 的区别见 §3.3。

3.3 热修复分支 — `hotfix/`

用于生产环境紧急修复。从 main（或 master）拉取，修复后合入 main 并回合并入 develop（Git Flow）。

hotfix/<简短描述>
hotfix/<版本号>-<简短描述>    # 多热修并行时可加版本号

示例

hotfix/payment-gateway-timeout
hotfix/1.2.1-session-leak

工作流（Git Flow）

main ──► hotfix/payment-gateway-timeout ──► PR ──► main
                                        └──► PR ──► develop

3.4 发布分支 — `release/`

用于发布前版本冻结、CHANGELOG 整理、版本号 bump、回归测试。从 develop 拉取，完成后合入 main 并打 Tag，再回合并入 develop。

release/<主版本>.<次版本>.<修订号>

遵循 Semantic Versioning：MAJOR.MINOR.PATCH

示例

release/1.4.0
release/2.0.0-rc.1    # 预发布版本（可选）

3.5 重构分支 — `refactor/`

不改变外部可观测行为的大规模结构调整。

refactor/<简短描述>

示例

refactor/extract-payment-service
refactor/migrate-to-vitest

3.6 工程化分支 — `chore/`

构建脚本、依赖升级、CI 配置、工具链变更等非业务代码。

chore/<简短描述>

示例

chore/upgrade-node-20
chore/add-dependabot-config

3.7 文档分支 — `docs/`

仅文档变更（若与功能同 PR 可不必单独建分支）。

docs/<简短描述>

示例

docs/api-authentication-guide
docs/update-contributing

3.8 实验分支 — `experiment/` 或 `spike/`

概念验证、技术调研；不得直接合入 main，结论沉淀后以 feature/ 或 refactor/ 重新提交。

experiment/<简短描述>

3.9 禁止的分支命名模式

模式	原因
`dev-<用户名>`、`tmp-*`	个人临时分支易泄漏、难追溯
纯数字、纯日期	无语义
含空格或特殊字符	跨平台/Git 工具兼容性问题
与长期分支同名前缀混淆	如 `main-backup`、`develop-old`

4. Tag 命名规范

发布 Tag 与 release/* 分支版本号保持一致，遵循 Semantic Versioning。

v<主版本>.<次版本>.<修订号>
v<主版本>.<次版本>.<修订号>-<预发布标识>.<序号>    # 预发布

示例

v1.4.0
v1.4.1              # patch：向后兼容的 bug 修复
v2.0.0              # major：含破坏性变更
v1.5.0-beta.1       # 预发布
v1.5.0+build.20240710   # 构建元数据（可选）

约束

Tag 仅打在 main（或发布 commit）上
禁止移动已推送的 Tag；若需修正，使用新的 patch 版本号
Annotated Tag 优于 Lightweight Tag（含作者、日期、说明）

git tag -a v1.4.0 -m "Release 1.4.0: OAuth2 login, CSV export"

5. Commit Message 规范

采用 Conventional Commits 规范，便于自动生成 CHANGELOG、语义化版本号（semantic-release）及代码审查。

5.1 基本格式

<类型>[可选 作用域]: <描述>

[可选 正文]

[可选 脚注]

单行示例（最常见）

feat(auth): add OAuth2 authorization code flow
fix(cart): prevent duplicate item on rapid click
docs(readme): update local development setup

5.2 类型（Type）

类型	含义	语义化版本影响
`feat`	新功能	MINOR ↑
`fix`	缺陷修复	PATCH ↑
`docs`	仅文档	—
`style`	格式（空格、分号等，不影响逻辑）	—
`refactor`	重构（非 feat/fix）	—
`perf`	性能优化	PATCH ↑（部分工具）
`test`	测试增删改	—
`build`	构建系统或外部依赖	—
`ci`	CI 配置与脚本	—
`chore`	其他不修改 src/test 的维护性工作	—
`revert`	回滚先前提交	视被回滚内容

破坏性变更（Breaking Change）

在类型后加 !，或在脚注写 BREAKING CHANGE:：

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: /api/v1/* routes removed; migrate to /api/v2/*

5.3 作用域（Scope）

可选，表示变更影响的模块/包/层级：

feat(auth): ...
fix(payment/stripe): ...
chore(deps): ...

团队应维护一份推荐 scope 列表（如 auth、api、ui、db），但不强制穷举。

5.4 描述（Subject）约束

规则	说明
祈使语气	英文用 "add" 而非 "added"；中文可用「添加」
首字母	英文描述首字母小写（专有名词除外）
无句号	Subject 末尾不加 `.`
长度	不超过 72 字符（50 字符以内更佳）
语言	全团队统一中文或英文，不混用

5.5 正文（Body）与脚注（Footer）

跨文件、行为变更、架构决策时建议写正文，说明 为什么改（而非重复改了什么）。

脚注常用键：

Refs: #123
Closes: #456
Reviewed-by: Alice <alice@example.com>
Co-authored-by: Bob <bob@example.com>
Signed-off-by: Carol <carol@example.com>    # DCO 场景

完整示例

fix(session): extend idle timeout for mobile clients

Mobile WebView resets activity timestamps inconsistently.
Increase idle timeout from 15m to 30m for mobile user agents only.

Closes: #789

5.6 禁止的 Commit Message

update
fix bug
WIP
temp
misc changes
asdf

5.7 Merge / Squash 策略

策略	适用	主干历史
Squash merge	功能分支多而杂的 WIP 提交	线性，一 PR 一 commit
Rebase merge	提交历史已整洁	线性，保留多个语义 commit
Merge commit	需保留分支拓扑	有 merge 节点

推荐： 短期分支合入 main/develop 时优先 Squash merge；Squash 后的标题应是一条符合 Conventional Commits 的 message，正文可汇总 PR 描述。

6. 分支与 Commit 类型对照

分支前缀	推荐 Commit 类型	典型合入目标
`feature/*`	`feat`	`develop` / `main`
`fix/`、`bugfix/`	`fix`	`develop`
`hotfix/*`	`fix`	`main` + `develop`
`release/*`	`chore`（版本 bump）	`main` + `develop`
`refactor/*`	`refactor`	`develop`
`chore/*`	`chore`、`build`、`ci`	`develop`
`docs/*`	`docs`	`develop`

7. 分支生命周期

创建 ──► 开发（与目标分支同步）──► PR 评审 ──► CI 通过 ──► 合入 ──► 删除远程分支

阶段	要求
创建	从最新的目标长期分支拉取；命名符合 §3
开发	定期 `rebase` 或 `merge` 目标分支，减少冲突；小步提交、语义清晰
评审	PR 标题遵循 Conventional Commits；关联 Issue；描述影响范围与测试方式
合入	CI 绿 + 至少 1 人 Approve（团队可规定 2 人）
清理	合入后 24～48h 内删除远程短期分支

分支存活期建议

分支类型	建议最长存活
`feature/*`	≤ 2 周
`fix/*`	≤ 3 天
`hotfix/*`	≤ 24 小时
`release/*`	至发布完成
`experiment/*`	≤ 1 周（过期即删）

8. 快速对照表

场景	从哪拉	合入哪	分支名示例
新功能（Git Flow）	`develop`	`develop`	`feature/oauth2-login`
新功能（GitHub Flow）	`main`	`main`	`feature/oauth2-login`
开发期 Bug	`develop`	`develop`	`fix/session-expiry`
生产热修	`main`	`main` + `develop`	`hotfix/payment-timeout`
版本发布	`develop`	`main` + Tag	`release/1.4.0`
依赖升级	`develop`	`develop`	`chore/upgrade-deps`
技术验证	`develop`	不合 main，转 feature	`experiment/graphql-poc`

9. Pull Request 标题规范

PR 标题应与合入后的 commit message 一致，推荐直接使用 Conventional Commits 格式：

feat(auth): add OAuth2 authorization code flow
fix(cart): prevent duplicate item on rapid click

关联 Issue 可在 PR 描述或脚注中声明 Closes #123，而非写入分支名。

10. 工具与自动化建议

工具	用途
commitlint	校验 commit message
husky	Git hooks 触发 lint/test
semantic-release	按 commit 自动 bump 版本、发 Tag、生成 CHANGELOG
release-please	Google 风格自动化发布
Branch protection rules	强制 PR、CI、Review

pre-commit 示例（commitlint）

{
  "extends": ["@commitlint/config-conventional"]
}

11. 修订记录

版本	日期	说明
2.0	2026-07-10	重写为业界通用规范：Conventional Commits、SemVer、Git Flow/GitHub Flow，去除项目特定命名
1.0	—	项目定制版（已 supersede）

附录 A：Conventional Commits 完整类型速查

feat     → 新功能
fix      → Bug 修复
docs     → 文档
style    → 代码格式（不影响含义）
refactor → 重构
perf     → 性能
test     → 测试
build    → 构建/依赖
ci       → 持续集成
chore    → 杂项维护
revert   → 回滚

附录 B：SemVer 升级规则摘要

变更性质	版本段	示例
破坏性 API/行为变更	MAJOR	1.4.0 → 2.0.0
向后兼容的新功能	MINOR	1.4.0 → 1.5.0
向后兼容的 Bug 修复	PATCH	1.4.0 → 1.4.1