Git Commit 规范

发布于 2023-05-03 21:51:34 字数 7103 浏览 96 评论 0

本文是对前面系列文章的补充与完善。前面的介绍，利用了 husky 与 lint-staged 使得在提交之前做一些 ESLint 和 Prettier 的操作，今天来补充完 Commit Message 提交说明规范。

Git 是目前最先进的分布式版本控制系统，Git 每次提交代码时，都需要写 Commit Message（提交说明），否则不允许提交。

# 单行（亦可多行输入，输入一个双引号，按 Enter 键即可，最后补全一个双引号）
$ git commit -m "xxx"

# 多行输入，输入命令进入编辑模式
$ git commit

在团队多人协作中，一份清晰简明的 Commit Message 很重要，它可以让我们清楚了解本次代码提交的目的以及解决了具体什么问题。也可能让后续 Code Review、信息查找、版本回退都更加高效可靠。

目前，社区有多种 Commit Message 的写法规范。本文介绍 Angular 规范，这是目前使用最广的写法，比较合理和系统化，并且有配套的工具。

Commit Message 规范

每次提交，Header 是必需的，而 Body 和 Footer 可以省略。

不管哪一部分，任何一行都不得超过 72 个字符（或 100 个字符）。这是为了避免自动换行影响美观。

<Header>
<空行>
<Body>
<空行>
<Footer>

Header 部分

它包括 type、scope、subject 三部分，其中 type、subject 是必须的，而 scope 是可选的。

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

type 用于说明 commit 的类型，只允许使用下面几个标识：

feat 新功能
A new feature
fix 修复 bug
A bug fix
docs 仅包含文档的修改
Documentation only changes
style 格式化变动，不影响代码逻辑。比如删除多余的空白，删除分号等
Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor 重构，既不是新增功能，也不是修改 bug 的代码变动
A code change that neither fixes a bug nor adds a feature
perf 性能优化
A code change that improves performance
test 增加测试
Adding missing tests or correcting existing tests
build 构建工具或外部依赖包的修改，比如更新依赖包的版本等
Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci 持续集成的配置文件或脚本的修改
Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
chore 杂项，其他不修改源代码与测试代码的修改
Other changes that don't modify src or test files
revert 撤销某次提交
Reverts a previous commit

如果 type 为 feat 和 fix，则该 commit 将肯定会出现在 Change Log 中。其他情况（docs、chore、style、refactor、test）由你决定，要不要放入 Change Log 中，建议是不要。

scope 用于说明 commit 影响的范围，比如数据层、控制层、视图层等。根据项目本身情况处理，如: views, components, utils, test...

subject 是 commit 目的的简短描述，不超过 50 个字符。

以动词开头，使用第一个人称现在时，比如 change，而不是 changed 或者 changes
第一字母小写
结尾不加句号（.）

Body 部分

Body 部分是对本次 commit 的详细描述，可以分成多行。下面是一个范例：

More detailed explanatory text, if necessary.  Wrap it to 
about 72 characters or so. 

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Use a hanging indent

注意两点：

使用第一人称现在时，比如使用 change 而不是 changed 或者 changes。
应该说明代码变动的动机，以及与之前行为的对比。

Footer 部分

Footer 部分只用于两种情况。

不兼容的变动

如果当前代码与上一个版本不兼容，则 Footer 部分以 BREAKING CHANGE 开头，后面是对变动的描述以及变动理由和迁移方法。

BREAKING CHANGE: isolate scope bindings definition has changed.

    To migrate the code follow the example below:

    Before:

    scope: {
      myAttr: 'attribute',
    }

    After:

    scope: {
      myAttr: '@',
    }

    The removed `inject` wasn't generaly useful for directives so there should be no code using it.

关闭 Issue

如果当前 commit 针对某个 issue，那么旧可以在 Footer 部分关闭这个 issue。

# 关闭单个
Closes #123

# 关闭多个
Closes #123, #234, #345

Revert

还有一种特殊情况，如果当前 commit 用于撤销以前的 commit，则必须以 revert: 开头，后面跟着被撤销 Commit 的 Header。

Body 部分格式是固定的，必须写成 This reverts commit <hash>.，其中的 hash 是被撤销 commit 的 SHA 标识符。

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

如果当前 commit 与被撤销的 commit 在同一个发布（release）里面，那么它都不会出现在 Change Log 里面。如果两者在不同的发布，那么当前 commit，会出现在 Change Log 的 Reverts 小标题下面。

Commitizen

Commitizen 是一个撰写符合上面 Commit Message 标准的一款工具。

可以全局安装或者项目本地安装，我采用后者，但都会介绍一下。

全局安装

# 全局安装方法

# 下载
$ yarn global add commitizen cz-conventional-changelog

# 创建 .czrc 文件
$ vi ~/.czrc

# 写入如下内容并保存
{ "path": "cz-conventional-changelog" }

# 完了之后，可以使用 git cz 来代替 git commit 了。

项目局部安装

$ yarn add --dev commitizen cz-conventional-changelog

接着往 package.json 添加配置：

{
  "scripts": {
    "commit": "git-cz",
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }
}

commitizen 与 cz-conventional-changelog 的关系？

commitizen 根据不同的 Adapter 配置 Commit Message。比如，要使用 Angular 的 Commit Message 格式，可以安装 cz-conventional-changelog。还有很多其他的 Adapter...

实践

其中 scope、breaking changes、issue 等非必需项可回车跳过。

生成 Change Log

如果你的所有 Commit 都符合 Angular 格式，那么发布新版本时， Change Log 就可以用脚本自动生成。

生成的文档包括以下三个部分。

New features
Bug fixes
Breaking changes.

conventional-changelog 就是生成 Change Log 的工具，此前已安装并配置

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md"
  }
}

运行以下命令生成 CHANGELOG 文件，其中 feat 和 fix 类型的变动会生成在里面。

$ yarn run changelog

每个部分都会罗列相关的 commit ，并且有指向这些 commit 的链接。当然，生成的文档允许手动修改，所以发布前，你还可以添加其他内容。

文章的示例 Demo 在这里 GitHub: wechat_applet_demo，欢迎 Star 。

参考

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

列表为空，暂无数据

关于作者

迟到的我

暂无简介

0 文章

0 评论

24 人气

关注发私信

友情链接

文江博客

Git Commit 规范

Commit Message 规范

Header 部分

Body 部分

Footer 部分

不兼容的变动

关闭 Issue

Revert

Commitizen

全局安装

项目局部安装

实践

生成 Change Log

参考

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

你可能也喜欢

创建 Docker Swarm 集群

重建 CentOS 或 RHEL 上被损坏的 RPM 数据库

修复 passwd:Authentication token manipulation error 的步骤

如何退出无响应的 ssh 会话

electron-builder 打包错误 cannot find module fs/promises

Maven 中 optional 关键字

WordPress 数据库结构全解析

固定静态化 WordPress 搜索结果链接

发布评论

关于作者

热门标签

推荐作者

wanghao

蓝天

handsomedeng

仙女

石海龙

dianjvnan

友情链接

Git Commit 规范

Commit Message 规范

Header 部分

Body 部分

Footer 部分

不兼容的变动

关闭 Issue

Revert

Commitizen

全局安装

项目局部安装

实践

生成 Change Log

参考

如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

你可能也喜欢

发布评论

关于作者

热门标签

推荐作者

友情链接

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。