从HTML活动页面到 Vue、React 大型项目都通用的 git hooks 配置

2024-09-10

1969 字约 7 分钟

...

git提交时不加审核，团队内的git规范很容易被一次次的样式拉扯修改、小bug调整等git提交给冲得稀烂。这时候可以使用 git 原生的 hooks，在 commit 之前监听一下 commit 内容。但是原生 git hooks 的配置默认是不同步到仓库的，这样一来，配置好的 hooks 事件其实就是本地单机事件，无法很好的团队共享。而 Husky+commitlint 刚好能处理这个场景。

Husky

Husky 是一个 Git Hook 工具，它允许开发者在 Git 工作流程的各个阶段（如提交、推送、合并等）触发自定义的脚本。这些脚本可以执行各种任务，例如代码检查、测试、格式化等。

主要作用

保证代码质量
- 在提交代码前，可以运行 ESLint、Prettier 等工具来检查代码格式是否符合规范，避免格式混乱的代码被提交到仓库。
- 例如，在提交前自动检查 JavaScript 代码是否符合 ESLint 配置的规则，如果有不符合规则的代码，则阻止提交，并提示开发者进行修改。
自动化测试
- 可以在推送代码前触发测试脚本，确保只有通过测试的代码才会被推送到远程仓库。
- 比如，在执行git push操作时，自动运行项目中的单元测试，如果测试失败，则推送操作被中断，开发者可以及时发现并修复问题。

工作原理

Husky 通过在项目的.git/hooks目录下创建一系列的 Hook 脚本，这些脚本在相应的 Git 操作发生时被触发。当开发者在项目中配置 Husky 后，Husky 会管理这些 Hook 脚本的创建、更新和删除，使得开发者可以方便地定义和维护在 Git 操作中执行的自定义任务。

commitlint

commitlint 是一个用于规范 Git 提交信息格式的工具。它可以对提交的消息进行检查，确保其符合预先定义的规则。

主要作用

统一提交信息格式
- 它强制要求团队成员在提交代码时遵循一致的提交信息格式，使得提交历史清晰、可读且易于理解。
- 例如，定义一个格式如<type>(<scope>): <subject>，其中type可以是feat（新功能）、fix（修复 bug）等，scope表示影响的范围，subject是简洁的描述。
提高协作效率
- 规范的提交信息有助于在代码审查和项目维护过程中快速了解每个提交的目的和影响范围。
- 比如，当查看提交历史时，能够根据清晰的提交信息快速定位到相关的功能添加或 bug 修复的提交。
与其他工具集成
- commitlint 可以与 Husky 等工具集成，在执行git commit操作时自动检查提交信息的格式是否符合规范。
- 这样，如果提交信息不符合规则，提交操作将被阻止，并提示开发者按照正确的格式修改提交信息。

配置规则

可以在项目中通过配置文件（如.commitlintrc.js）来定义具体的提交信息规则，包括type的可选值、scope的格式、subject的长度限制等。
例如：

    module.exports = {
      extends: ['@commitlint/config - conventional'],
      rules: {
        'type - case': [0, 'always', 'lower - case'],
        'subject - min - length': [2, 'always'],
      }
    };

一、初始化git

需要在项目中先初始化好git，才能进行后续的 git hooks 配置

git init

二、安装 Husky

这里采用自动安装 npx husky-init

npm install

安装完成后，项目结构下多出.husky目录

此目录就是包装暴露出来的git hooks 脚本，此时已经安装了关键的一个hook脚本，pre-commit，这个脚本管理git commit 前调用的方法，可以在此时调用 eslint和pretty做代码审核

而另一个关键脚本，需要通过以下命令安装

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

安装后生成commit-msg脚本

并且生成对应的校验命令

但是此时还不能执行该命令，我们还需要安装另一个关键配置

三、安装 commitlint

通过以下两个命令可以完成 commitlint 的安装 npm install @commitlint/cli和npm install @commitlint/config-conventional

安装完成后再在 package.json同层级新建.commitlintrc.js配置文件

配置内容如下

module.exports = {
  extents: ['@commitlint/config-conventional'],
  rules: {
    'body-leading-blank': [1, 'always'],
    'footer-leading-blank': [1, 'always'],
    'header-max-length': [2, 'always', 72],
    'scope-case': [2, 'always', 'lower-case'],
    'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'type-enum': [
      2,
      'always',
      ['build', 'chore', 'ci', 'docs', 'feat', 'fix', 'improvement', 'perf', 'refactor', 'revert', 'style', 'test']
    ]
  }
}

配置完后即可使用。

四、测试

在命令行输入git commit -m 'test'，如果报以下错误就是配置成功了。

正确提交格式返回如下

五、常用的commit 提交形式

Conventional Commits 格式
- 格式：<type>(<scope>): <description>
- Type（类型）
  - feat：用于表示新功能（feature）的添加。例如，feat: add user authentication module表示添加了用户认证模块。
  - fix：用于修复 bug。如fix: resolve login page crash issue表示修复了登录页面崩溃的问题。
  - docs：对文档（documentation）的修改。例如docs: update API reference documentation是对 API 参考文档进行了更新。
  - style：代码格式（空格、分号等）的修改，但不影响代码逻辑。比如style: format code according to style guide。
  - refactor：代码重构，既不添加新功能，也不修复 bug。如refactor: optimize database query logic是对数据库查询逻辑进行了优化重构。
  - test：添加或修改测试用例。例如test: add unit tests for user service是为用户服务添加了单元测试。
  - chore：其他不修改 src 或者 test 文件的修改，如构建过程或辅助工具的变动。像chore: update build scripts就是更新了构建脚本。
- Scope（范围）
  - 可选项，用于指定改动的范围，可以是某个文件、模块、组件等。例如feat(userService): add new user registration method中，userService就是范围，表示新功能添加在用户服务相关的部分。
- Description（描述）
  - 是对提交的简短描述，清晰地说明改动的内容。

六、各个插件的版本号

避免因版本不同而出现刻舟求剑问题，还是贴一下版本号。最新版本插件安装后，无法按本文期待结果执行的话，可以安装指定版本获得效果。

"dependencies": { "@commitlint/cli": "^19.4.1", "@commitlint/config-conventional": "^19.4.1", "vue": "^3.4.37" }, "devDependencies": { "@vitejs/plugin-vue": "^5.1.2", "typescript": "^5.5.3", "vite": "^5.4.1", "vue-tsc": "^2.0.29", "husky": "^8.0.0" }