Git提交规范

概述

使用 Conventional Commits 规范管理提交信息，确保提交历史清晰可读，便于自动生成变更日志和语义化版本管理。

:::tip Conventional Commits 格式

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

<body>

<footer>

:::

提交类型（type）

类型	说明	示例
`feat`	新功能	`feat(user): 添加用户导入功能`
`fix`	修复 bug	`fix(auth): 修复 token 过期后未刷新的问题`
`docs`	文档变更	`docs: 更新部署文档`
`style`	代码格式（不影响逻辑）	`style: 格式化代码缩进`
`refactor`	重构（非新功能非修复）	`refactor(repo): 统一查询方法封装`
`perf`	性能优化	`perf(query): 优化分页查询性能`
`test`	测试相关	`test(unit): 添加岗位模块单元测试`
`chore`	构建/工具变更	`chore: 更新依赖版本`
`ci`	CI/CD 变更	`ci: 添加 GitHub Actions 配置`
`revert`	回滚提交	`revert: 回滚 feat(user) 提交`

范围（scope）

可选，用于说明影响的模块或组件：

feat(user): 用户模块
fix(auth): 认证模块
refactor(repo): Repository 层
feat(api): API 层
docs(deploy): 部署文档

提交信息示例

简单提交

feat(position): 添加岗位状态切换接口
fix(captcha): 修复验证码过期时间计算错误
docs: 更新 README 安装说明

带正文的提交

fix(auth): 修复 token 刷新后旧 token 仍有效的问题

旧 token 在刷新后未加入黑名单，导致短时间内可同时使用新旧两个 token。
修复方案：刷新时将旧 token 加入 Redis 黑名单。

Closes #123

破坏性变更

feat(api)!: 统一响应格式，移除 data.code 字段

BREAKING CHANGE: 响应格式从 {data: {code, data}} 变为 {code, data, msg, ok}
前端需同步更新响应处理逻辑。

:::warning 破坏性变更破坏性变更使用 ! 后缀标记，并在正文或 footer 中说明 BREAKING CHANGE。此类变更需在版本号中体现（主版本号 +1）。 :::

分支策略

分支	用途	命名格式	说明
`main`	主分支（生产）	`main`	始终保持可发布状态
`master`	开发主分支	`master`	日常开发合并目标
`feature/*`	功能分支	`feature/功能名`	从 master 拉取
`fix/*`	修复分支	`fix/问题描述`	从 master 拉取
`hotfix/*`	紧急修复	`hotfix/问题描述`	从 main 拉取

分支工作流

1. 从 master 创建功能分支
 git checkout -b feature/position-import master

2. 开发完成后提交
 git commit -m "feat(position): 添加岗位 Excel 导入功能"

3. 合并到 master
 git checkout master
 git merge feature/position-import

4. 推送到远程
 git push origin master

5. 生产发布时合并到 main
 git checkout main
 git merge master
 git tag v1.2.0

版本标签

使用语义化版本号（Semantic Versioning）：

v主版本号.次版本号.修订号
v1.2.3

主版本号：破坏性变更
次版本号：新功能（向后兼容）
修订号：Bug 修复

# 创建标签
git tag -a v1.2.0 -m "feat: 添加岗位导入功能"

# 推送标签
git push origin v1.2.0

# 查看标签
git tag -l

.gitignore 配置

# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
venv/

# 环境配置
.env

# IDE
.idea/
.vscode/
*.swp

# 上传文件
uploads/

# 日志
logs/

# 数据库
*.sqlite3

:::tip .env 安全 .env 文件包含敏感信息（数据库密码、JWT 密钥等），必须在 .gitignore 中排除。各环境的 .env 独立管理，不提交到仓库。 :::

常用 Git 命令

# 查看提交历史
git log --oneline -20

# 查看某次提交的变更
git show <commit-hash>

# 撤销工作区修改
git checkout -- <file>

# 撤销暂存
git reset HEAD <file>

# 暂存当前工作
git stash
git stash pop

# 查看分支图
git log --graph --oneline --all

总结

Git 提交规范采用 Conventional Commits 格式：type(scope): subject。常用类型包括 feat/fix/docs/refactor/test/chore。分支策略：main（生产）、master（开发）、feature/fix/hotfix（临时分支）。版本使用语义化标签（v1.2.0）。.env 等敏感文件必须排除在仓库之外。

4.3 KiB Raw Blame History Unescape Escape