Git commit message规范

参考文档:https://mp.weixin.qq.com/s/mAUqTPCqcYjoNDqAxktyfA

使用工具简介:commitizen、cz-conventional-changelog、commitlint、husky

commitizen:Commitizen是一款提升GIT提交过程效率的小工具。它会提示你提供任何必要字段,还会恰当地格式化提交信息。Commitizen内置了对多种提交规范的支持,同时还允许你定制自己的提交规则。这个简单的工具能够节约时间,而不必等待提交钩子运行检查再驳回提交。

cz-conventional-changelog:是commitizen的适配器,使commitizen支持 Angular 的 Commit message 格式

commitlint:设置message的规范

husky:husky 其实就是一个为 git 客户端增加 hook 的工具。将其安装到所在仓库的过程中它会自动在 .git/ 目录下增加相应的钩子实现在 pre-commit 阶段就执行一系列流程保证每一个 commit 的正确性。

一、背景:

团队对提交的commit message格式有约定俗称的要求,但是没有一个统一的规范,导致大家提交的commit message或多或少不太一样。因此,需要一个工具来帮助大家统一commit message的格式,也方便后续的分析和拓展。
现在市面上比较流行的方案是约定式提交规范,它的message 格式如下:

(): 
// 空一行

// 空一行

二、Commit message 的格式介绍(Angular 团队的 commit 规范)

每次提交,Commit message 都包括三个部分:Header,Body 和 Footer。

其中,Header 是必需的,Body 和 Footer 可以省略。

不管是哪一个部分,任何一行都不得超过72个字符(或100个字符-自定义)。这是为了避免自动换行影响美观。

(1)header

   Header部分只有一行,包括三个字段:type(必需)、scope(可选)和subject(必需)。

  • type用于说明commit的类型,主要包括一下几种

    feat:新功能(feature)

    fix:修补bug

    docs:文档(documentation)

    style: 格式(不影响代码运行的变动)

    refactor:重构(即不是新增功能,也不是修改bug的代码变动)

    test:增加测试

    chore:构建过程或辅助工具的变动

  • scope用于说明commit的影响范围,可以随便填写任何东西,commitizen也给出了几个 如:location 、browser、compile;或者可以约定为:

     all :表示影响面大 ,如修改了网络框架  会对真个程序产生影响

    loation: 表示影响小,某个小小的功能

     module:表示会影响某个模块 如登录模块、首页模块 、用户管理模块等等

  • subject是commit的简短描述

(2)Body

   Body 部分是对本次 commit 的详细描述,可以分成多行。

   注意:

  • 使用第一人称现在时,比如使用change而不是changedchanges
  • 应该说明代码变动的动机,以及与以前行为的对比。

(3)Footer

       可以描写备注;如果是 bug ,可以把bug id放入

  1. 不兼容变动
    如果当前代码与上一个版本不兼容,则 Footer 部分以BREAKING CHANGE开头,后面是对变动的描述、以及变动理由和迁移方法。
  2. Revert
    如果当前 commit 用于撤销以前的 commit,则必须以revert:开头,后面跟着被撤销 Commit 的 Header。

三、Quick Start

1. 全局安装commitizen & cz-conventional-changelog

注:Commitizen是一个撰写合格 Commit message 的工具,用于代替git commit 指令;cz-conventional-changelog 是AngularJS的规范 (还有其他规范,如cz-customizable(支持一定程度上的自定义,都是commitizen的adapter,有兴趣可以了解一下)

       1、全局安装commitizen和cz-conventional-changelog

   npm install -g commitizen cz-conventional-changelog

   2、创建.czrc文件,在文件中设置:'{ "path": "cz-conventional-changelog" }' ,该步骤的作用是为commitizen指定Adapter

   echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

   查看.czrc是否创建成功,可以使用命令:cat ~/.czrc查看文件内容,展示{ "path": "cz-conventional-changelog" }即表示创建成功。

2、项目内安装commitlint & husky

commitlint负责用于对commit message进行格式校验,husky负责提供更易用的git hook。

   1、安装

   npm i husky @commitlint/config-conventional @commitlint/cli

   2、设置配置文件--创建commitlint.config.js到项目根目录,定义规范

   echo 'module.exports = {extends: ["@commitlint/config-conventional"]};' > ./commitlint.config.js

   也可以使用angular规则:

   在文件中直接配置:module.exports = {extends: ['@commitlint/config-angular']};

   3、配置钩子

    vue-cli3项目:设置package.json:

    "gitHooks": { "commit-msg": "commitlint -e $HUSKY_GIT_PARAMS" },

        非vue-cli3项目:设置package.json:

{
"hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
   }
}

3、使用

使用git cz代替git commit,执行过程如下图所示:

Git commit message规范_第1张图片

 

填写完毕后,husky会调用commitlint对message进行格式校验,默认规定type及subject为必填项。

push之后,项目中展示格式为:

Git commit message规范_第2张图片

 

 

4、自定义规则

参考文档:https://www.npmjs.com/package/@commitlint/config-angular

message的规范可以根据实际需要自定义,设置参看文献:https://commitlint.js.org/#/reference-rules

对commitlint.config.js设置规则为:

Git commit message规范_第3张图片

 

执行git cz,当message不符合规范时,commit日志会提示报错!例如当提交代码时,type选择错误并且subject结尾不添加’;‘时,会报如下错误:

Git commit message规范_第4张图片

 

四、总结

好处:

1、团队形成一致的代码提交风格,更好的提高工作效率

2、规范的 commit message 有助于团队其它人员 review, 还可以有效的输出 CHANGELOG(借助其他插件可实现), 对项目十分重要

缺点:

1、提交过程比较麻烦

结论:

在多人共同开发的大型项目中比较适用

五、其他(添加change log)

1、使用commit message规范可以:

(1)提供更多的历史信息,方便快速浏览--git log  HEAD --pretty=format:%s

(2)可以过滤某些 commit(比如文档改动),便于快速查找信息--git log  HEAD --grep feature

(3)可以直接从 commit 生成 Change log。

其中生成log文件需要借助插件:conventional-changelog-cli

conventional-changelog-cli 默认推荐的 commit 标准是来自angular项目,除了 angular 标准以外,目前集成了包括 atom, codemirror, ember, eslint, express, jquery 等项目的标准,具体可以根据具体要求来选用。

安装

npm install -g conventional-changelog-cli

使用(标准为angular,可修改)

conventional-changelog -p angular -i CHANGELOG.md -s

这条命令产生的 changelog 是基于上次 tag 版本之后的变更(Feature、Fix、Breaking Changes等等)所产生的,所以如果你想生成之前所有 commit 信息产生的 changelog 则需要使用这条命令:

conventional-changelog -p angular -i CHANGELOG.md -s -r 0  (r- 默认1,全部0)

效果如下图:

Git commit message规范_第5张图片

 

   


你可能感兴趣的:(Git commit message规范)