🧩 Git 分支与提交管理规范

本文档用于规范团队 Git 使用方式，确保多人协作时代码提交一致、分支清晰、历史可追踪。

一、仓库与分支策略

采用 Git Flow + 简化版主干模型（Master/Main + Dev + Feature + Hotfix）。
其中，master/main 和 dev 是长期存在（持久）的主分支；feature_* 和 hotfix_* 为临时分支，开发或修复任务完成后需合并并删除。

分支用途来源合并目标分支类型
master/main稳定版本分支，用于生产环境部署无（初始化）release_*、hotfix_*持久
dev开发主线分支，整合功能模块master/mainrelease_*持久
feature_*功能开发分支devdev临时
hotfix_*紧急修复分支master/mainmaster/main、dev临时

二、分支命名规则

类型命名格式示例
功能分支feature_<功能名>feature_user-login
修复分支hotfix_<问题名>hotfix_fix-login-bug
临时测试test_<用途>test_ai-service

✅ 命名规则：

  • 全部小写；
  • 分支与具体内容，使用下划线 _ 连接；
  • 具体内容中使用-连接；
  • 不允许使用空格或特殊字符，尽可能不使用中文。

三、分支创建与管理流程

1️⃣ 创建 dev 分支（仅一次）

项目初始化后，从 master 创建 dev：

git checkout master
git pull origin master
git checkout -b dev
git push -u origin dev

dev 是主要开发分支，所有功能分支均基于它创建。

2️⃣ 创建 feature 功能分支

开发新功能时，从最新 dev 创建：

git checkout dev
git pull origin dev
git checkout -b feature_<功能名>
git push -u origin feature_<功能名>

示例：

git checkout -b feature_user-auth
git push -u origin feature_user-auth

功能完成后合并回 dev：

git checkout dev
git pull origin dev
git merge --squash feature_user-auth -m "[merge]feature_user-auth merged into dev"
git push origin dev
git branch -d feature_user-auth

3️⃣ 创建 hotfix 修复分支（紧急线上问题）

从 master 创建：

git checkout master
git pull origin master
git checkout -b hotfix_<问题名>
git push -u origin hotfix_<问题名>

修复完成后：

git checkout master
git merge --no-ff hotfix_<问题名>
git push origin master

git checkout dev
git merge --no-ff hotfix_<问题名>
git push origin dev

git branch -d hotfix_<问题名>
git push origin --delete hotfix_<问题名>

🧱 分支生命周期表

分支类型创建自合并至是否长期存在删除时机
master初始化—✅ 永久永不删除
devmaster—✅ 永久永不删除
feature_*devdev❌ 临时功能合并后删除
hotfix_*mastermaster、dev❌ 临时修复完成后删除

四、提交信息规范

遵循 Conventional Commits 规范：

提交格式

标准版本

[<type>](<scope>): <subject>

<body>

<footer>

字段说明：

  • type（必填）：提交类型，见下方"常用类型"表格，需用方括号 [] 包裹
  • scope（可选）：影响范围，如模块名、文件名、功能域等
    • 示例：auth、api、ui、core、config、deps 等
    • 如果改动影响全局或无明确范围，可省略
  • subject（必填）：简短描述，建议不超过50字符
  • body（可选）：详细描述修改内容、原因、影响等
  • footer（可选）：关联Issue、Breaking Changes等信息

完整示例：

[feat](auth): add JWT token validation

- Implement JWT middleware for API authentication
- Add token expiration check (24h default)
- Support custom secret key via env variable

Closes #123

Lite 精简版本

适用于小型改动或个人项目，仅需一行，用分号分隔多个修改点：

[<type>](<scope>): <修改1>; <修改2>; <修改3>

精简版示例：

[fix](api): 修复登录接口500错误; 优化错误提示信息; 添加日志记录

[docs]: 更新README安装说明; 补充API使用示例; 修正拼写错误

常用类型

英文类型中文类型含义示例
feat功能新功能[feat](auth): add JWT login
fix修复修复[fix](api): resolve 500 error
docs文档文档[docs]: update API section
style样式样式[style](ui): adjust button spacing
refactor重构重构[refactor](core): simplify config
test测试测试[test]: add auth unit test
chore杂项构建/依赖[chore](deps): upgrade fastapi

🚫 禁止模糊提交，如：

  • update code
  • fix bug
  • modify file

五、分支合并规则

一般合并流程（示例）

# 保留提交记录
git merge --no-ff feature_xxx

约束要求

  • 不允许直接提交至 master；
  • 所有合并必须通过 代码审核；
  • 冲突由分支创建者解决；
  • 合并前通过单元测试与 lint 检查。

六、代码审核规范

项目要求
审核方式所有向 master 的 PR 必须 Review, dev分支merge视项目详细情况规定
工具GitHub / GitLab Pull Request
审核人至少 1 名核心开发者
检查内容功能正确性、性能、可读性、注释、日志、安全性

七、版本与 Tag 管理

遵循 语义化版本（SemVer） 规范：

MAJOR.MINOR.PATCH
示例含义
1.0.0首个稳定版本
1.1.0新功能增加
1.1.1Bug 修复

发布版本命令：

git checkout main
git pull
git tag -a v1.1.0 -m "Release v1.1.0"
git push origin v1.1.0

八、推荐 Git 配置与命令模板

常用别名

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate --all"

创建功能分支函数（可放入 .bashrc）

function gnew() {
  git checkout dev && git pull && git checkout -b feature/$1
}

九、完整示例：开发一个功能

# 1. 克隆仓库
git clone <repo>

# 2. 切换到开发分支
git checkout dev
git pull

# 3. 创建功能分支
git checkout -b feature_voice-detection

# 4.1 开发并提交,发起 PR -> 审核通过 -> 合并 -> 删除分支
git add .
git commit -m "[feat](voice): add emotion recognition model"
git push origin feature_voice-detection

# 4.2 本地合并到dev分支
git add .
git commit -m "[feat](voice): add emotion recognition model"
git switch dev
git merge --no-ff (或--squash) feature_voice-detection
git push origin dev

# 5. 删除本地与远程对应功能分支(若有)
git branch -d feature_voice-detection
git push origin --delete feature_voice-detection

📌 总结

  • main/master：只保存生产版本
  • dev：主开发线
  • feature_*：临时功能分支
  • hotfix_*：紧急修复

所有分支合并均需保留记录（--no-ff），部分feat分支可使用(--squash)精简但需要详细描述提交修改内容，并通过审核流程。