Git Commit 提交规范

本项目以目前使用较多的 Angular 团队规范 Conventional Commits specification（约定式提交） 为例. git hook 官方文档

git 提交时，主要分为三部分

• commitizen：生成 commit message
• commitlint：校验 commit message
• conventional-changelog：生成 changelog

如何将这几步串联起来？使用全新项目来演示。示例项目

第一步，新建全新项目

> npm create vite my-vue-app -- --template vue
1

第二步，制定 eslint 代码规范。

创建 .eslintrc.js 和 .eslintignore 文件
这里四步走：

1. 安装
2. 添加指令
3. 执行指令
4. 打开文件，查看效果

# 1.安装
> npm i -D eslint eslint-plugin-vue @typescript-eslint/eslint-plugin eslint-plugin-prettier @typescript-eslint/parser eslint-config-prettier
1
2

添加指令。 在 package.json 中添加一条 script 中的指令**"lint": "eslint src --fix --ext .ts,.tsx,.vue,.js,.jsx"**

{
  "scripts": {
    ...,
    "lint": "eslint src --fix --ext .ts,.tsx,.vue,.js,.jsx",
    ...,
  },

}
1
2
3
4
5
6
7
8

接下来执行命令

> npm run lint
1

执行完成后，打开文件查看效果。（你可以将双引号改为单引号，并执行指令后 对比指令前后的文件内容）
你会发现代码已经按照 eslint 规则被格式化。

第三步，制定 prettier 代码规范。

创建 .prettier.js 和 .prettierignore 文件.与上一步同样流程

# 安装
> npm i -D prettier

# 执行命令后，打开文件查看对比效果
> npm run prettier
1
2
3
4
5

第四步，制定 git commit 规范

1. 安装使用包 Commitizen 帮助规范化提交代码 ( 这一步的目的是安装完成后，直接使用指令 git cz 来取代 git commit 进行代码提交)

# 安装
> npm i -g commitizen cz-conventional-changelog
1
2

安装完成后，接下来在 package.json 中添加两部分内容

1. 添加一条 script 中的指令 "commit": "git-cz"
2. 添加 config 中内容

{
  "script": {
      ...,
      "commit": "git-cz",
  },
  "config": {
    "commitizen": {
      "path": "node_modules/cz-conventional-changelog"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11

到这里，已经完成了 git 提交规范制定

执行命令，查看效果吧

> git add .

# 提交方式一： 使用 `git cz`
> git cz
# 或者提交方式二： 使用 `npm run commit`
> npm run commit
1
2
3
4
5
6

tips：到了这里需要注意，以后 git 提交代码时不要使用 git commit 去提交而要使用git cz

---

在上一步使用 git cz 进行提交时，提示语都是英文，难以理解，转换为我们自定义的 Adapter中文选项。这里使用包 cz-custionizable 定制：

# 安装
> npm i -g cz-customizable
1
2

修改 package.json 中的 config 为:

  "config": {
    "commitizen": {
      "path": "node_modules/cz-customizable"
    }
  },
1
2
3
4
5

修改完成后，在项目目录下创建一个配置文件 .cz-config.js

module.exports = {
  // 可选类型
  types: [
    { value: "feat", name: "feat:     新功能" },
    { value: "fix", name: "fix:      修复" },
    { value: "docs", name: "docs:     文档变更" },
    { value: "style", name: "style:    代码格式(不影响代码运行的变动)" },
    {
      value: "refactor",
      name: "refactor: 重构(既不是增加feature，也不是修复bug)",
    },
    { value: "perf", name: "perf:     性能优化" },
    { value: "test", name: "test:     增加测试" },
    { value: "chore", name: "chore:    构建过程或辅助工具的变动" },
    { value: "revert", name: "revert:   回退" },
    { value: "build", name: "build:    打包" },
  ],
  // 消息步骤
  messages: {
    type: "请选择提交类型:",
    customScope: "请输入修改范围(可选):",
    subject: "请简要描述提交(必填):",
    body: "请输入详细描述(可选):",
    footer: "请输入要关闭的issue(可选):",
    confirmCommit: "确认使用以上信息提交？(y/n/e/h)",
  },
  // 跳过问题
  skipQuestions: ["body", "footer"],
  // subject文字长度默认是72
  subjectLimit: 72,
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

OK, 这里已经完成了我们自定义的 Adapter, 我们测试一下

> git cz
1

针对自定义的 Adapter 进行 Lint

很多时候，我们会忘记了应该使用git cz， 一不小心就用 git commit 提交了代码，上面的所有限制就都没用了， 所以此时需要 针对自定义的 Adapter 进行 Lint。 限制一下，要求所有的提交内容都必须要按照规则来，否则拒绝提交。

1. commitlint: 帮助我们 限制 git 提交时的信息, 如果我们提交的不符合指向的规范, 直接拒绝提交

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

创建 .commitlintrc.js并写入以下内容

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {},
};
1
2
3
4

2. 我们使用了自定义的 Apadter，那么针对自定义的 Adapter 进行 限制

> npm i -D commitlint-config-cz @commitlint/cli
1

接下来 在 .commitlintrc.js 中写入:

module.exports = {
  extends: ["cz"],
  rules: {},
};
1
2
3
4

3. 校验 commit message 的最佳方式是结合 git hook, 所以需要使用到工具 Husky 和 lint-staged(只检查 git 提交到缓存区中的内容)

> npm i -D husky
> npx mrm@2 lint-staged

# 添加钩子
> npx husky add .husky/pre-commit "npx lint-staged"
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'
1
2
3
4
5
6

package.json 中添加

{
  "scripts": {
    "prepare": "husky install"
  }
}
1
2
3
4
5

然后执行

> npm run prepare
1

此时，husky 会在目录 .husky下生成两个没有后缀的文件 pre-commit 和 commit-msg, 如果没有则手动创建

pre-commit文件内容

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

npx lint-staged

1
2
3
4
5

commit-msg文件内容

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

npx --no-install commitlint --edit "$1"
1
2
3
4

接下来在 package.json 中添加

  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS,",
      "pre-commit": "lint-staged"
    }
  }
1
2
3
4
5
6

然后创建一个配置文件 .lintstagedrc.json

{
  "*.{js,jsx,vue,ts,tsx}": ["prettier --write .", "eslint  --fix"],
  "*.md": ["prettier --write"]
}
1
2
3
4

接下来就可以测试了, 只有当你 输入 git commit -m "test: XXX"这样的信息时才允许提交

> git add .
> git commit -m "sss"
> git commit -m "test: XXX
1
2
3

什么是 husky？

husky 继承了 Git 下所有的钩子，在触发钩子的时候，husky 可以阻止不合法的 commit,push 等等。注意使用 husky 之前，必须先将代码放到 git 仓库中，否则本地没有.git 文件，就没有地方去继承钩子了。

在 package.json 文件通过字段直接添加 git 钩子

{
  "husky": {
    "hooks": {
      //commitlint检测
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS,",
      //js、css检测，这两个检测需要自己配置，pre-commit会优先于commit-msg执行
      "pre-commit": "npm run stylelint && npm run eslint"
    }
  }
}
1
2
3
4
5
6
7
8
9
10

什么是 conventional-changelog ？

conventional-changelog 是一款可以根据项目的 commit 和 metadata 信息自动生成 changelogs 和 release notes的系列工具，并且在辅助包 standard-version 工具的情况下，可以自动帮你完成生成 version、打 tag, 生成 CHANGELOG 等系列过程。

• conventional-changelog 生态主要模块
• conventional-changelog-cli - conventional-changelog 核心命令行工具
• standard-changelog - 针对 angular commit 格式的命令行工具
• conventional-github-releaser - 利用 git metadata 针对 Github 的发布工具
• conventional-commits-detector - commit message 规范引用检测
• commitizen - 针对开发者简单的 commit 规范
• commitlint - commit Lint 工具

为了方便使用，在 package.json 文件添加命令

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
  }
}
1
2
3
4
5

以后，直接运行下面的命令即可生成提交日志

> npm run changelog
1

git 标识

• feat：新功能（feature）
• fix：修补 bug
• docs：文档（documentation）
• style： 格式（不影响代码运行的变动）
• refactor：重构（即不是新增功能，也不是修改 bug 的代码变动）
• perf: 性能提升（提高性能的代码改动）
• test：测试
• build：构建过程或辅助工具的变动（webpack 等）
• ci：更改 CI 配置文件和脚本
• chore：不修改 src 或测试文件的其他更改
• revert：撤退之前的 commit

常见问题

1. windows 用户需要使用 npm 包管理器安装，不然 git hooks 会失效

参考资料

vite2+vue3+Ts
vite 中文网