1647 字
8 分钟
Git用法

在使用Git管理版本的过程中,总是难以撰写提交消息

为了标准化提交内容,通常建议使用 Conventional Commits 约定提交格式
以统一乱七八糟的提交,方便检索查询版本历史

小声明

Git 本身不内置 commit type,也不强制任何格式 以下“类型”是 Conventional Commits/Angular 生态中的标准类型与常见扩展类型。团队应统一约定,并让 commitlint 等工具校验


Git提交格式#

基本格式#

从最基础的提交格式开始:

<类型>(<范围>): <描述>
  • 类型:这次改动的性质,比如 feat、fix
  • 范围(可选):影响哪个模块,比如 auth、user
  • 描述:简短的概述说明做了什么

让我们把内容写的更详细些:

<类型>(<范围>): <描述>
<正文>
<脚注:关联 issue、破坏性变更等>

新增的两个内容:

  • 正文:详述改动内容/解释为什么这么改
  • 脚注:关联相关 issue、说明破坏性变更等等

举一个栗子:

feat(auth): 支持手机号验证码登录
新增手机号验证码登录流程,兼容原有密码登录。
Closes #123

破坏性变更#

对于破坏性变更,有些改动会破坏原有功能或接口
因此这类提交需要额外标记,提醒其他开发者注意

feat!: 移除旧版登录接口

或者是

feat: 移除旧版登录接口
BREAKING CHANGE: 旧版 /login 已删除,请迁移到 /v2/login。
国际化

此处使用中文作为提交内容不太合适,仅演示作用
对于:

  • 公开仓库:最好还是使用英语提交,提交内容使用祈使句
  • 私人仓库:后续不公开使用中文问题不大,但还是建议使用英文养成好习惯

提交注意事项#

很重要的注意事项!千万千万不要把api密钥一类的东西推送上去裸奔啊喂…

  1. 不提交敏感信息:密钥、令牌、密码、证书、个人配置
  2. 不提交生成产物:dist、build、缓存、日志、依赖目录
    • 如果拷贝下来他人的仓库包含各种乱七八糟的生成产物,大部分完全用不上还占空间…是什么感觉呢
  3. 不提交无关文件:提交前检查 git diff --cached
  4. 提交前运行测试、lint、格式化
  5. 重构与功能/修复分开提交
  6. 格式化与逻辑修改分开提交
  7. 不在主分支保留 wip 提交,合并前 squash
  8. 不写无信息提交:如 update、fix bug、修改
  9. 不把 BREAKING CHANGE 当作 type
  10. 不把 merge 当作 Conventional type
  11. 一个提交应可编译、可测试、可回滚
  12. 提交信息应能让 reviewer 快速判断影响范围

提交类型#

这些是常见的提交类型,由 Conventional Commits/Angular 规定
编写提交描述时,如果想不起来该使用哪种提交类型,可以在下列表格中查询
(如果都难以作为合适的提交类型,可以使用万能的 chore)

类型含义使用时机版本影响示例
feat新功能新增用户可见功能、接口、页面、配置项MINORfeat(user): 增加头像上传
fix修复缺陷修复 bug、异常、错误逻辑PATCHfix(order): 修复优惠券重复计算
docs文档只改文档,不影响代码运行无直接docs(api): 补充接口说明
style格式空格、缩进、分号、格式化,不改变逻辑无直接style: 统一缩进为 2 空格
refactor重构调整结构、重命名、提取函数,外部行为不变无直接refactor(order): 提取金额计算逻辑
perf性能优化提升速度、减少内存、优化渲染无直接perf(list): 虚拟滚动减少节点
test测试新增或修改测试代码无直接test(user): 补充注册边界测试
build构建/依赖构建工具、打包配置、依赖版本变更无直接build: 升级 Vite 到 5.0
ci持续集成CI/CD 配置、流水线脚本无直接ci: 增加 PR 自动检查
chore杂项不影响 src/test 的日常事务无直接chore: 更新 .gitignore
revert回滚撤销之前的提交视被回滚内容revert: feat(user): 增加头像上传

其他常见扩展类型#

扩展类型说明建议归属
deps依赖更新可归 build 或 chore
security安全修复可归 fix
release发布相关可归 chore
wip工作进行中不建议进入主分支,合并前 squash
hotfix紧急修复可归 fix
improvement改进可归 feat/refactor/perf
config配置调整可归 chore/build
init初始化可归 chore
examples示例可归 docs
merge合并提交Git 自动生成,不纳入 Conventional 规范
必须要声明的点

以上这些不是标准提交类型 只不过在社区中其他开发者经常使用的到,因此请酌情使用
原则上:扩展类型宜少不宜多,要做到团队统一,并让 commitlint 等工具支持


“我们的约定”#

这些是写提交时常见的社区约定,不管是给自己还是他人的仓库提交,都最好遵循以下约定:

  1. 一个提交只完成一件事:保证原子提交,可独立理解、测试、回滚
  2. 描述用祈使句、现在时:如“修复登录超时”,不要“修复了一些问题” (绝对不是在内涵某软件的更新日志)
  3. 英文约定:首字母小写,结尾不加句号;中文项目可统一中文,但 type 保持英文
  4. 长度控制:subject 建议不超过 50 字符,正文每行约 72 字符
  5. scope 可选:建议写模块名,如 auth、order、user,小写、无空格
  6. body 解释为什么:不是重复“怎么改”,而是说明背景、原因、影响
  7. footer 放关联信息:如 Closes #123、Fixes #456、Refs #789
  8. 破坏性变更必须显式说明:写清影响范围和迁移方式
  9. 关联 issue:推荐使用 Closes、Fixes、Refs
  10. 签名与协作:需要时使用 Signed-off-by、Co-authored-by
  11. 语言统一:中英文不要混用随意;术语保持一致
  12. 不重写公共历史:已推送的公共分支谨慎 rebase/force push
  13. 回滚用 revert:不要直接删除历史
  14. 合并策略统一:rebase、squash、merge 按团队规范执行

工具链与自动化#

想批量处理规范,以下几个工具相当实用

  • commitlint:校验提交信息是否符合规范
  • husky:Git hooks,提交前触发校验
  • lint-staged:只检查暂存文件
  • commitizen:交互式生成规范提交
  • semantic-release / standard-version:自动生成 CHANGELOG 和版本号
  • 版本映射关系:
    • fix → PATCH
    • feat → MINOR
    • BREAKING CHANGE → MAJOR

Git用法
https://fuwari.vercel.app/posts/notes/git-usage/
作者
Acer
发布于
2026-09-28
许可协议
CC BY-NC-SA 4.0