实现自定义git提交规范

5,661 阅读6分钟

提交规范环境搭建

为什么要规范 Git 提交

好的提交记录,会将每次提交内容的范围,内容,以及涉及到的 bug 都能清晰的展示出来,且格式一致,便于查找找提交记录,对查看代码提交记录或者审核的人更友好,能够更好地了解项目的生命周期以及中间出现的问题。

规范 Git 提交会用到以下依赖的插件,下面是我使用的插件以及对应的版本号

  • "commitizen": "^4.2.3", // Commitizen 是一个帮助撰写规范 commit messages 的工具
  • "cz-conventional-changelog": "^3.3.0", // 适配器,用来提供约定提交格式,不同的需求,可以使用不同的适配器
  • "@commitlint/config-conventional": "^12.1.1", // 社区定义的提交规范
  • "@commitlint/cli": "^12.1.1", // 校验提交信息的命令行工具 文档
  • "commitlint-config-cz": "^0.13.2", // 用于自定义提交格式
  • "cz-customizable": "^6.3.0", // 自定义提交规范 提示文案
  • "husky": "^6.0.0", // husky是一个Git Hook工具。husky是一个为 git客户端增加 hook 的工具

下面会介绍两种方式:

  • 全局安装,使用第三方提供约定规范 的提交格式
  • 项目依赖安装,使用自定义规范约定 的提交方式

第一种:全局安装

  • 安装依赖

npm i -g commitizen cz-conventional-changelog
  • 生成.czrc文件

    运行echo '{"path":"cz-conventional-changelog"}' > ~/.czrc 在根路径下生成.czrc 文件,为 commitizen 指定 Adapter。

    注意:如果是全局安装

    • mac OS 下可以直接执行 echo '{"path":"cz-conventional-changelog"}' > ~/.czrc 会在跟路径下生成.czrc文件
    • window 下如果直接执行 echo '{"path":"cz-conventional-changelog"}' > ~/.czrc 这个命令,则会报错,因为 ~/Linux 的命令,代表的是根路径,至于怎么在 window根路径下生成.czrc这个文件的命令,我还不太清楚,也不知道在window下个跟路径指的是那个路径
  • 配置 package.json

"scripts":{
    commit:"git-cz"
},
"config":{
    "commitizen":{
        "path":"node_modules/cz-conventional-changelog"
    }
}

完成以上配置,就能使用 git cz 命令了,也可以使用配置 packge.json 以后运行 npm run commit进行提交

第二种:项目依赖安装

  • 安装依赖

npm i -D commitizen cz-conventional-changelog

运行echo '{"path":"cz-conventional-changelog"}' > .czrc 在当前路径下生成.czrc 文件,为 commitizen 指定 Adapter。

注意:需要去掉 .czrc 文件中的 单引号

package.json文件添加如下配置

"scripts":{
    commit:"git-cz"
},
"config":{
    "commitizen":{
        "path":"node_modules/cz-conventional-changelog"
    }
}

如果是全局安装,完成以上配置,就能使用 git cz 命令了,也可以 packge.json配置 的命令 npm run commit进行提交

下面是对提交规范做了进一步约束

  • 使用Husky生成Git Hooks

husky 负责提供更易用的 git hook。 结合 git hook 来检验 commit message,这样当你的提交不符合规范时就会阻止你提交

npm i -D husky

注意,因为 husky4.0 和 husky6.0 的版本差异较大,配置方式也不同,所以区分介绍

  1. husky4.0 版本配置 package.json添加如下配置
"husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
}

git hooks 是为了在项目中执行 git -commit -m "xxx" 是触发 commit-msg时间钩子,并通知 husky, 从而执行commitlint -E HUSKY_GIT_PARAMS命令,它会读取commitlint.config.js配置,并对我们提交的信息进行校验,如果校验失败,则commit终止

  1. husky6.0 版本不在配置package.json文件,改为使用命令生成.husky文件夹

安装并初始化husky

npx husky-init

会在当前项目根路径下生成.husky文件夹以及pre-commit文件,同时package.json会增加下代码

"scripts": {
    "prepare": "husky install"
}

启用 Git 挂钩

npx husky install
或者
pm run prepare

只有全局安装 husky 才能运行以下命令生成commit-msg文件

husky add .husky/commit-msg "npm test"

否则在.husky下手动创建commit-msg文件

生成或添加commit-msg文件后,并修改内容为以下内容

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

yarn commitlint --config commitlint.config.js --edit $1 // 只有这一句需要修改

安装其他 git 钩子只需要执行husky add .husky/钩子名字 "npm test"就行了

然后运行

git add .
git commit -m "test commit" // 提交不规范,就能验证了
  • 自定义规范

如果想自己定义提交规范也是可以的,首先要下载自定义规范约束的包替换第三方规范。

npm i -D commitlint-config-cz cz-customizable

在项目根目录创建.cz-config.js,可以再这个文件里自定义规范(下面这是我自定义的配置)

module.exports = {
	types: [
		{ value: 'init', name: 'init:     初始提交' },
		{ value: 'feat', name: 'feat:     增加新功能' },
		{ value: 'fix', name: 'fix:      修复bug' },
		{ value: 'ui', name: 'ui:       更新UI' },
		{ value: 'refactor', name: 'refactor: 代码重构' },
		{ value: 'release', name: 'release:  发布' },
		{ value: 'deploy', name: 'deploy:   部署' },
		{ value: 'docs', name: 'docs:     修改文档' },
		{ value: 'test', name: 'test:     增删测试' },
		{ value: 'chore', name: 'chore:    更改配置文件' },
		{ value: 'style', name: 'style:    样式修改不影响逻辑' },
		{ value: 'revert', name: 'revert:   版本回退' },
		{ value: 'add', name: 'add:      添加依赖' },
		{ value: 'minus', name: 'minus:    版本回退' },
		{ value: 'del', name: 'del:      删除代码/文件' }
	],
	scopes: [
		{ name: 'components' },
		{ name: 'utils' },
		{ name: 'styles' },
		{ name: 'deps' },
		{ name: 'other' }
	],
	messages: {
		type: '选择更改类型:\n',
		// 如果allowcustomscopes为true,则使用
		scope: '选择一个 scope(可选):\n',
		customScope: '请输入自定义的 scope:',
		subject: '简短描述:\n',
		body: '详细描述. 使用"|"换行:\n',
		breaking: 'Breaking Changes列表:\n',
		footer: '关闭的issues列表. E.g.: #31, #34:\n',
		confirmCommit: '确认提交?'
	},
	allowCustomScopes: true,
	allowBreakingChanges: ['feat', 'fix']
}

package.json 修改改为,自定义规范

// 使用自定义规范则使用
"config": {
    "commitizen": {
      "path": "node_modules/cz-customizable"
    }
}
// 或者
"config": {
    "cz-customizable": { // 可以对.cz-config.js 进行重命名
        "config": "config/config.js"
    }
}

cz-customizable 首先会在项目根目录中查找一个名为.cz-config.js 或者.config/cz-config.js 的文件如果找不到配置,它将在主目录中查找.cz-config.js.config/cz-config.js 或者 package.json。 (参考官网翻译的。。。)

commitizen: 默认是用上面的.cz-config.js 文件,如果想对.cz-config.js 文件进行重命名则使用 cz-customizable配置

  • 最后别忘了修改.czrc 文件内容为自定义规范

{"path":"cz-customizable"}
  • 补充:对`git commit -m "xxx" message 内容的校验

如果想使用``git commit -m "xxx"`,且对这个名的内容进行校验,则需要进行以下操作

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

commitlint 负责用于对 commit message 进行格式校验。

  • 配置commitlint.config.js文件

在项目跟路径下新建commitlint.config.js文件 rules 为了自定义的规则,这里同时使用了两个规范,可以只要 cz@commitlint/config-conventional其中一个

  • cz: 自定规范
  • @commitlint/config-conventional: Angular 团队使用的规范
  • extends: [规范列表] 可以同时使用多个规范

这个文件是对git commit -m "xxx"内容xxx的校验,

module.exports = {
	extends: ['@commitlint/config-conventional', 'cz'],
	rules: {
		// Header
		'header-max-length': [2, 'always', 200],
		// <type>枚举
		'type-enum': [
			2,
			'always',
			[
				'add', // 添加依赖
				'delete', // 删除代码/文件
				'feat', // 增加新功能
				'fix', // 修复bug
				'style', // 样式修改不影响逻辑
				'merge', // 合并分支
				'perfect', // 功能完善
				'docs', // 修改文档
				'refactor', // 代码重构
				'test', // 单元测试修改
				'ci', // 持续继承
				'release', // 发布
				'deploy', // 部署
				'chore', // 更改配置文件
				'revert' // 版本回退
			]
		],
		// <type> 不能为空
		'type-empty': [2, 'never'],
		// <type> 格式 小写
		'type-case': [2, 'always', 'lower-case'],
		// <scope> 不能为空
		'scope-empty': [2, 'never'],
		// <scope> 格式 小写
		'scope-case': [2, 'always', 'lower-case'],
		// <subject> 不能为空
		'subject-empty': [2, 'never'],
		// <subject> 以.为结束标志
		'subject-full-stop': [2, 'never', '.'],
		// <subject> 格式
		// 可选值
		// 'lower-case' 小写 lowercase
		// 'upper-case' 大写 UPPERCASE
		// 'camel-case' 小驼峰 camelCase
		// 'kebab-case' 短横线 kebab-case
		// 'pascal-case' 大驼峰 PascalCase
		// 'sentence-case' 首字母大写 Sentence case
		// 'snake-case' 下划线 snake_case
		// 'start-case' 所有首字母大写 start-case
		'subject-case': [2, 'never', []],
		// <body> 以空行开头
		'body-leading-blank': [1, 'always'],
		// <footer> 以空行开头
		'footer-leading-blank': [1, 'always']
	}
}

以上是一份比较全的校验,也可以对以上几种进行组合,用于不同场景的校验,请参考这篇博客,在此也谢谢这位博友!

参考资料:
husky
cz-customizable
博客
Cz工具集使用介绍 – 规范Git提交说明