使用 commitlint 约束项目 Git 代码提交描述信息格式规范

5,409次阅读

共计 4177 个字符，预计需要花费 11 分钟才能阅读完成。

提醒：本文最后更新于2020-12-30 14:09，文中所关联的信息可能已发生改变，请知悉！

Git 提交应当书写 commit message。message 的内容怎么写都行，但如何写比较合理是一个问题。开源社区有很多相关的规范，使用最广泛的则是Angular Git Commit Guidelines 规范，并且有众多相关的工具可以检测提交是否遵循了预定义的规范。

Angular 规范要求的 commit message 格式如下：

 <type>(<scope>): <subject>
<空行>
<body>
<空行>
<footer>

包括三个字段：type(必需)、scope(可选)和subject(必需)。

用于标识 commit 的类别，以便于快速识别本次提交的类型。只允许以下几个种标识：

feat: 新功能
fix: bug 修复
docs: 文档变更
style: 样式变更
refactor: 重构（非新功能也不是bug修复的变动）
perf: 性能优化改进
test: 新增或修订单元测试
chore: 构建过程或辅助工具变更

用于标识 commit 影响的范围，可以省略。

本次修改的简短描述。基本要求为：

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

可省略。详细描述本次提交，比如此次变更的动机、变更后与之前的差异等。

可省略。可以为 Breaking Changes 内容或关闭 issues 的关联语句。Breaking Changes 应当以 BREAKING CHANGE: 开头，然后在空格或两个空行后描述其详情。

2.1 安装与配置 `commitlint`

commitlint 是当前使用最为广泛的 git commit 校验约束工具之一，使用它我们可以很方便的实现约束项目遵循 Angular 提交规范。

安装 commitlint：

 npm i -D @commitlint/cli @commitlint/config-angular
// or
yarn add -D @commitlint/cli @commitlint/config-angular

在项目根目录新建 commitlint 的配置文件 commitlint.config.js，内容参考如下：

 'use strict';
const message = process.env['HUSKY_GIT_PARAMS'];
const fs = require('fs');
 
const types = [
  'build', // 构建执行
  'chore', // 构建工具相关
  'ci', // CI 相关
  'docs', // 文档更新
  'feat', // 新功能
  'fix', // bug 修复
  'perf', // 性能优化
  'refactor', // 功能重构
  'release',
  'revert', // 回滚操作
  'style', // 样式变动
  'test', // 单元测试
];
 
const scopes = ['showcase', 'packaging', 'changelog', 'schematics', 'module:*'];
 
function parseMessage(message) {
  const PATTERN = /^(\w+)(?:\(([^)]+)\))?\: (.+)$/;
  const match = PATTERN.exec(message);
  if (!match) {
    return null;
  }
  return {
    type: match[1] || null,
    scope: match[2] || null,
  };
}
 
function getScopesRule() {
  const messages = fs.readFileSync(message, { encoding: 'utf-8' });
  const parsed = parseMessage(messages.split('\n')[0]);
  if (!parsed) {
    return [2, 'always', scopes];
  }
  const { scope, type } = parsed;
  if (scope && !scopes.includes(scope) && type !== 'release' && !/module:.+/.test(scope)) {
    return [2, 'always', scopes];
  } else {
    return [2, 'always', []];
  }
}
 
module.exports = {
  extends: ['@commitlint/config-angular'],
  rules: {
    'type-enum': [2, 'always', types],
    'scope-enum': getScopesRule,
  },
};

上述示例我们使用了严格遵循 Angular 规范的 @commitlint/config-conventional 扩展，你也可以选择替换使用更为通用的 @commitlint/config-conventional 扩展。

更多配置规则可参考这里：

https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-angular
https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional

2.2 安装与配置 `husky`

这里其实还需借助另外一个工具 husky，以实现 git hooks 注入与脚本配置执行。

安装 husky：

 npm i -D husky
// or
yarn add -D husky

在 package.json 中配置 husky：

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

如果一切操作顺利完成，接下来写个 commit 测试一下效果吧。

在对项目质量有比较高的管控要求时，我们希望任何人不能随意提交未经讨论或评审过的代码。

当使用 gitlab 和 jira 并且将它们关联后，我们希望每次的代码提交都应当是与 jira 任务关联的。当 git 提交说明中包含 jira issues 编号，则 gitlab 会在该 issues 下的自动提交一个注释说明。

我们可以如下配置以借助 commitlint 对该要求实现强制性约束。

 module.exports = {
  'rules': {
    'references-empty': [2, 'never'],
  },
  parserPreset: {
    parserOpts: {
      issuePrefixes: ['PROJ-']
    }
  },
};

其中 PROJ- 为具体的 jira 项目编号前缀。

相关参考：

https://docs.gitlab.com/ee/user/project/integrations/jira.html
https://github.com/conventional-changelog/commitlint/issues/237
https://github.com/conventional-changelog/commitlint/issues/372
https://github.com/Gherciu/commitlint-jira

3 引入 `conventional-changelog` 生成项目变更日志

安装 conventional-changelog：

 npm i -D conventional-changelog-cli
// or
yarn add -D conventional-changelog-cli

在 package.json 的 scripts 下加个脚本：

   "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }

测试一下效果：

npm run chagelog

以上配置的语句默认为追加模式。执行如下语句可以生成完整的 CHANGELOG.md 文件：

npm run chagelog -- -s -r 0

相关参考：

https://docs.gitlab.com/ee/user/project/integrations/jira.html
https://github.com/conventional-changelog/commitlint/issues/237
https://github.com/conventional-changelog/commitlint/issues/372
https://github.com/Gherciu/commitlint-jira

https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit
https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-angular
https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional
https://github.com/NG-ZORRO/ng-zorro-antd/blob/master/commitlint.config.js
https://github.com/conventional-changelog/conventional-changelog
https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli
https://github.com/conventional-changelog/standard-version

正文完

发表至：前端开发

2019-09-24

0

转载说明：除特殊说明外本站文章皆由CC-4.0协议发布，转载请注明出处。

React 17 中根据 DOM 节点获取 React 组件实例

实现基于项目约定的 ajax 通用性封装

那些过目不忘的无线端交互设计

webpack: export ‘Abc’ (imported as ‘style’) was not found in ‘./style.scss’ (possible exports: default)

ES2016、ES2017、ES2018、ES2019、ES2020、ES2021、ES2022、ES2023 新特性概览

H5 活动页之移动端 REM 布局适配方法

Chrome Developer Tools 开发者工具实用调试技巧

vscode: Visual Studio Code 常用快捷键及前端开发常用插件

ES2016、ES2017、ES2018、ES2019、ES2020、ES2021、ES2022、ES2023 新特性概览

使用 commitlint 约束项目 Git 代码提交描述信息格式规范

1 Angular Git Commit Guidelines 规范

1.1 Header

1.1.1 Type

1.1.2 Scope

1.1.3 Subject

1.2 Body

1.3 Footer

2 引入 commitlint 约束前端项目遵循 Angular 规范

2.1 安装与配置 `commitlint`

2.2 安装与配置 `husky`

2.3 约束提交说明必须包含项目 issues 标记

3 引入 `conventional-changelog` 生成项目变更日志

相关参考

安装与配置使用 aria2 加速文件下载参考指南

iOS 开发无证书签名IPA安装真机测试，一种支持iOS应用多开的方法

Iframe 与 SameSite：Iframe 中设置 cookie 失败的原因及解决方案

详细！离线部署大模型：ollama+deepseek+open-webui安装使用方法及常见问题解决

云服务器自建代理服务：基于 3x-ui 面板搭建 xray 代理服务及配置 clash 代理的方法

免费电影网站的另一种打开方式：批量下载、边看边播不卡顿、支持 Docker 部署、永久免费！

使用 RSS 订阅：个人高效阅读知识补充指南

高性能 Python 包管理器 uv 的安装与使用

Dify 工作流执行自定义代码报错：`Run failed: error: operation not permitted`

Python 环境管理工具 Miniconda 的安装、配置与使用

	npm i -D @commitlint/cli @commitlint/config-angular
	// or
	yarn add -D @commitlint/cli @commitlint/config-angular

	'use strict';
	const message = process.env['HUSKY_GIT_PARAMS'];
	const fs = require('fs');

	const types = [
	'build', // 构建执行
	'chore', // 构建工具相关
	'ci', // CI 相关
	'docs', // 文档更新
	'feat', // 新功能
	'fix', // bug 修复
	'perf', // 性能优化
	'refactor', // 功能重构
	'release',
	'revert', // 回滚操作
	'style', // 样式变动
	'test', // 单元测试
	];

	const scopes = ['showcase', 'packaging', 'changelog', 'schematics', 'module:*'];

	function parseMessage(message) {
	const PATTERN = /^(\w+)(?:\(([^)]+)\))?\: (.+)$/;
	const match = PATTERN.exec(message);
	if (!match) {
	return null;
	}
	return {
	type: match[1] \|\| null,
	scope: match[2] \|\| null,
	};
	}

	function getScopesRule() {
	const messages = fs.readFileSync(message, { encoding: 'utf-8' });
	const parsed = parseMessage(messages.split('\n')[0]);
	if (!parsed) {
	return [2, 'always', scopes];
	}
	const { scope, type } = parsed;
	if (scope && !scopes.includes(scope) && type !== 'release' && !/module:.+/.test(scope)) {
	return [2, 'always', scopes];
	} else {
	return [2, 'always', []];
	}
	}

	module.exports = {
	extends: ['@commitlint/config-angular'],
	rules: {
	'type-enum': [2, 'always', types],
	'scope-enum': getScopesRule,
	},
	};

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

	module.exports = {
	'rules': {
	'references-empty': [2, 'never'],
	},
	parserPreset: {
	parserOpts: {
	issuePrefixes: ['PROJ-']
	}
	},
	};

	npm i -D conventional-changelog-cli
	// or
	yarn add -D conventional-changelog-cli

	"scripts": {
	"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
	}

使用 commitlint 约束项目 Git 代码提交描述信息格式规范

1 Angular Git Commit Guidelines 规范

1.1 Header

1.1.1 Type

1.1.2 Scope

1.1.3 Subject

1.2 Body

1.3 Footer

2 引入 commitlint 约束前端项目遵循 Angular 规范

2.1 安装与配置 commitlint

2.2 安装与配置 husky

2.3 约束提交说明必须包含项目 issues 标记

3 引入 conventional-changelog 生成项目变更日志

相关参考

2.1 安装与配置 `commitlint`

2.2 安装与配置 `husky`

3 引入 `conventional-changelog` 生成项目变更日志