关于git:书写友好的提交信息

在书写提交信息时，让其变得人机可读是十分重要的。标准的提交信息对代码 CR 和问题定位等都很有帮忙，尤其是在团队合作中，显得更为重要。

标准

开源社区曾经为咱们总结出了一种用于给提交信息减少人机可读含意的标准，其名 Conventional Commits。

标准中举荐提交音讯的构造应如下所示：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

其中结尾局部表明了本次提交的类型（是增加性能还是修复谬误等），范畴则形容了批改的影响面，而后是一段简要的形容，更多具体的信息则能够在注释中进行形容。

最初在可选的脚注中还能够增加额定的内容，比方指明是否是一次破坏性变更，关联的工作卡片等。

交互式提交

刚开始遵循标准提交信息时，咱们对要求可能会比拟生疏，不晓得存在哪些选项，应该怎么抉择，因而提供交互式的提交形式是有必要的。

编写合乎提交标准的提交音讯的罕用交互式工具包是 commitizen，当你应用它进行提交时零碎将提醒你须要填写的所有必须提交字段。

yarn add -D commitizen

它提供了一个 git-cz 命令，用于代替 git commit 进行提交。

// package.json
{
  "scripts": {"commit": "npx git-cz"}
}

默认状况下它会将 streamich/git-cz 作为 Adapter 进行询问，你能够通过配置指定你须要的 Adapter，以 AngularJS’s commit message convention 为例：

yarn add -D cz-conventional-changelog

配置：

// package.json
{
  "config": {
    "commitizen": {"path": "cz-conventional-changelog"}
  }
}

指定的 commitizen.path 将通过 require.resolve 加载，同时反对：

• Npm 模块；
• 绝对于 process.cwd() 蕴含 index.js 文件的目录；
• 绝对于 process.cwd() 的 .js 文件；
• 残缺的绝对文件名；
• 绝对路径。

更多配置可点击查看更多。

校验

和 ESLint 一样的是，commitlint 本身只提供了检测的性能和一些最根底的规定。使用者须要依据这些规定配置出本人的标准。

# Install commitlint cli and conventional config
# @commitlint/config-conventional 规定了遵循上述的 Conventional Commits 标准
yarn add -D @commitlint/cli @commitlint/config-conventional

装置实现后须要在配置文件中（commitlint.config.js 或 .commitlintrc.js 或 .commitlintrc.json 或 .commitlintrc.yml）或 package.json 文件中的 commitlint 字段进行配置。

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

同时它也提供了 @commitlint/prompt-cli 包以便疾速疾速编写提交音讯，并确保它们合乎配置中的提交约定。

npm i -D @commitlint/prompt-cli

@commitlint/prompt-cli 的应用也很简略，装置它并应用它提供的 commit 命令进行提交即可。

{
  "scripts": {"commit": "commit"}
}

不过相对而言 commitizen 体现更优，反对自定义不同的 Adapter，所以更多时候大家会应用后者。commitlint 官网也基于 cz-conventional-changelog 提供一个名为 @commitlint/cz-commitlint 的 Adapter。

Git Hooks

有时候咱们可能会遗记校验提交信息，因而能够将其自动化，当咱们提交时主动校验，husky 能够很好的做到这点。

# 安装包
yarn add -D husky

# 开启 Git hooks
npx husky install

为了让其它同学在开发时也可能主动校验，同时在 package.json 文件中配置装置后主动启用 Git 挂钩：

npm pkg set scripts.prepare "husky install"

通过 husky 咱们能够很容易的应用 Git hooks 对咱们的提交信息进行校验。

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

对于 Windows 用户，如果在运行 npx husky add ... 时看到帮忙音讯，请尝试 node node_modules/.bin/husky add ... 代替。

CHANGELOG

应用约定式提交的一个益处就是能够自动化生成 CHANGELOG，standard-version 罕用于实现此项工作。

yarn add -D standard-version

接着在 package.json 中配置一个脚本命令：

{
  "scripts": {"release": "standard-version"}
}

当你第一次生成 CHANGELOG 时能够增加 --first-release 选项，这将会标记以后版本，而不会扭转 package.json 文件中的版本字段。

更多命令或选项：

# 假如你的我的项目的以后版本是 1.0.0
# 应用 --pre-releases 生成 pre-release 标记
yarn run release --prerelease # 1.0.0 -> 1.0.1-0; one more time: 1.0.1-0 -> 1.0.1-1

# 如果要命名预发行版，能够通过 --prerelease <name> 指定名称
yarn run release --prerelease alpha # 1.0.0 -> 1.0.1-alpha.0

# 通过 --release-as 选项降级指定位的版本号
# 你也能够同时 -prerelease 选项一起应用
yarn run release --release-as major # 1.0.0 -> 2.0.0
yarn run release --release-as minor # 1.0.0 -> 1.1.0
yarn run release --release-as patch # 1.0.0 -> 1.0.1

看起来和 npm version 的性能很像吧？是的，你齐全能够应用 standard-version 代替 npm version 命令了。

另外，你还能够通过配置文件（.versionrc, .versionrc.json 或 .versionrc.js）对其进行配置，配置标准能够参考 conventional-changelog-config-spec。

总结

以上咱们介绍了提交信息的标准，以及怎样才能不便大家进行书写和校验，上面总结了根底配置的命令清单：

# 反对交互式提交
yarn add -D commitizen @commitlint/cz-commitlint
npm pkg set config.commitizen.path "@commitlint/cz-commitlint"

# 反对标准校验
yarn add -D @commitlint/cli @commitlint/config-conventional
npm pkg set config.commitlint.extends "@commitlint/config-conventional"

# 配合 Git hooks 主动校验
yarn add -D husky
npx husky install
npm pkg set scripts.prepare "husky install"
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit"$1"'

# CHANGELOG
yarn add -D standard-version
npm pkg set scripts.release "standard-version"

留神下面的命令须要在 Node.js 16+ 行运行，不过你也能够依据下面的介绍手动进行装置。

最初，书写敌对的提交信息很重要，能够帮忙大家进行代码 CR 和定位问题，倡议大家可能在日常开发中遵循标准。

其它

勘误

若文中有误或有待欠缺，欢送在 GitHub 提交 ISSUE 或 编辑 此文。

参考

• Conventional Commits
• angular.js/CONTRIBUTING.md at master · angular/angular.js
• npm version 常用命令及用法示例
• Cz 工具集应用介绍 – 标准 Git 提交阐明 – 掘金
• 优雅的提交你的 Git Commit Message – 掘金