git commit 的一些执行规范

发表于 | 分类于 ，
Git是一个开源的分布式版本控制系统，可以有效、高速地处理从很小到非常大的项目版本管理。

相关材料

官方文档
官方文档-中文

背景

git commit message 是我们使用 git 进行代码提交时的日常操作。写好 log 不仅有助于他人 review, 还可以有效的输出 CHANGELOG, 对项目的管理实际至关重要, 但是实际工作中却常常被大家忽略。尤其是对于大型协作项目，commit的内容对于项目的维护非常重要。

commit

目前，社区有多种 Commit message 的写法规范。这里介绍Angular 规范，这是目前使用最广的写法，比较合理和系统化，并且有配套的工具。每次提交，Commit message 都包括三个部分：Header，Body 和 Footer。

commit
1
2
3
4
5
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

其中，Header 是必需的，Body 和 Footer 可以省略。
不管是哪一个部分，任何一行都不得超过72个字符（或100个字符）。这是为了避免自动换行影响美观。

Header部分只有一行，包括三个字段：type（必需）、scope（可选）和subject（必需）。

type

type用于说明 commit 的类别，不同规范中可能会略有差异，但是整体上应该只允许有限且界定鲜明的几个标识。比如相对常用的有：

  • feat：新功能（feature）
  • fix：修补bug
  • docs：仅仅修改了文档，比如README, CHANGELOG, CONTRIBUTE等等
  • style： 仅仅修改了空格、格式缩进等等，不改变代码运行逻辑
  • refactor：重构（即不是新增功能，也不是修改bug的代码变动）
  • perf: 优化相关，比如提升性能、体验。
  • chore：构建过程的变更，改变构建工具、或者增加依赖库、工具等
  • test：测试用例的调整，包括单元测试、集成测试等
  • revert: 回滚到上一个版本

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

scope

scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

subject

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

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

Body

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

1
2
3
4
5
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

有两个注意点。

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

Footer 部分只用于两种情况。

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    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.

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

    1
    2
    3
    Closes #234
    # 也可以一次关闭多个 issue 。
    Closes #123, #245, #992

生成Change log

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

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

1
2
3
New features
Bug fixes
Breaking changes.

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

conventional-changelog 就是生成 Change log 的工具，运行下面的命令即可。

1
2
3
$ npm install -g conventional-changelog
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -w

上面命令不会覆盖以前的 Change log，只会在CHANGELOG.md的头部加上自从上次发布以来的变动。

如果你想生成所有发布的 Change log，要改为运行下面的命令。

1
$ conventional-changelog -p angular -i CHANGELOG.md -w -r 0

一些工具

commitizen

终端工具commitizen是一个基于npm的版本控制工具集，仓库内包含多个提交工具，cz-cli是commit提交的命令行程序；cz-conventional-changelog 提供了日志的生成标准。

1
2
# 安装
npm install -g commitizen # 基于npm进行安装

commitizen-tools

是一个基于python的发布管理工具。提供了一套标准版本管理和提交的规范，同时用户可以进行一定的自定义设置。
说明文档
示例
image

1
2
3
# 安装
conda install -c conda-forge commitizen  #基于conda进行安装
pip install --user -U Commitizen #基于pip 进行安装

conventional-changelog/standard-version 一步解决提交信息和版本发布。

一些moji标记

https://gitmoji.dev/

##
commit规范

参考资料

知乎

-------------本文结束感谢您的阅读-------------