Commitizen

Name: Commitizen
Author: commitizen

官方

github.com开发者工具17.5kcz8 周前更新

代码仓库访问官网

关于 Commitizen

Commitizen 通过交互式命令行提示引导开发者创建符合 Conventional Commits 规范的提交信息。它确保整个团队的提交格式一致，便于后续的自动化工具处理和日志生成。

主要功能

01使用交互式提示创建结构化提交信息
02初始化项目并配置 Conventional Commits 规范
03强制执行一致的提交消息格式
04支持通过 git cz 命令替代标准 git commit

适用场景

01确保团队遵循统一的提交消息规范
02为自动化变更日志和版本管理提供结构化数据
03在代码审查中减少提交消息格式不一致的问题

安装

选择你的系统或包管理器，复制命令到终端运行。

npm install -g commitizen

安装完成后运行cz --version确认安装成功。

命令示例

常用命令按使用顺序排列。

cz init cz-conventional-changelog --save-dev

git cz

详细介绍

供贡献者使用的 Commitizen

使用 Commitizen 提交时，系统会在提交时提示你填写所有必填的提交字段。无需再等到稍后由 git 提交钩子运行并拒绝你的提交（不过，那个钩子仍可能有所帮助）。无需再翻阅 CONTRIBUTING.md 来查找首选格式。即时获取提交消息格式的反馈，并按提示填写必填字段。

安装命令行工具

Commitizen 目前已针对 Node.js 12、14 和 16 进行测试，不过在较旧版本的 Node.js 中也可能正常运行。你还需要安装 npm 6 或更高版本。

安装非常简单，只需运行以下命令即可（如果看到 EACCES 错误，阅读修复 npm 权限问题或许会有帮助）：

npm install -g commitizen

使用命令行工具

如果你的仓库兼容 Commitizen：

提交时，只需使用 git cz 或 cz 代替 git commit。你也可以使用 git-cz，它是 cz 的别名。

或者，如果你使用 npm 5.2+，可以使用 npx，而无需全局安装：

npx cz

也可以将其用作 npm 脚本：

  ...
  "scripts": {
    "commit": "cz"
  }

在兼容 Commitizen 的仓库中工作时，系统会提示你填写所有必填字段，并根据项目维护者定义的规范格式化提交消息。

如果你的仓库不兼容 Commitizen：

如果你在不兼容 Commitizen 的仓库中工作，那么 git cz 的效果与 git commit 完全相同，但 npx cz 会使用 streamich/git-cz 适配器。要解决此问题，你需要先让仓库兼容 Commitizen

让你的仓库支持 Commitizen

在本示例中，我们将设置仓库，以使用 AngularJS 的提交消息约定，也称为 conventional-changelog。

首先，安装 Commitizen CLI 工具：

npm install commitizen -g

接下来，输入以下命令，初始化项目以使用 cz-conventional-changelog 适配器：

# npm
commitizen init cz-conventional-changelog --save-dev --save-exact

# yarn
commitizen init cz-conventional-changelog --yarn --dev --exact

# pnpm
commitizen init cz-conventional-changelog --pnpm --save-dev --save-exact

请注意，如果你想强制覆盖旧适配器进行安装，可以添加 --force 参数。有关详情，请运行 commitizen help。

以上命令会为你完成以下三件事：

安装 cz-conventional-changelog 适配器 npm 模块
将其保存到 package.json 的 dependencies 或 devDependencies 中
在 package.json 文件的根目录中添加 config.commitizen 键，如下所示：

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

或者，也可以将 Commitizen 配置添加到 .czrc 文件中：

{
  "path": "cz-conventional-changelog"
}

这只是在告诉 Commitizen，当贡献者尝试向此仓库提交代码时，我们希望他们使用哪个适配器。

commitizen.path 通过 require.resolve 解析，并支持：

npm 模块
相对于 process.cwd() 且包含 index.js 文件的目录
相对于 process.cwd() 且带有 .js 扩展名的文件基本名称
完整的相对文件名
绝对路径

请注意，在以前版本的 Commitizen 中，我们使用的是 czConfig。czConfig 已弃用，你应在 Commitizen 3.0.0 发布前迁移到新格式。

可选：在本地安装并运行 Commitizen

在本地安装并运行 Commitizen，可以确保开发者在每台机器上运行的都是完全相同版本的 Commitizen。

使用 npm install --save-dev commitizen 安装 Commitizen。

在 npm 5.2+ 中，你可以使用 npx 初始化 conventional changelog 适配器：

npx commitizen init cz-conventional-changelog --save-dev --save-exact

对于 较早版本的 npm（< 5.2），你可以执行 ./node_modules/.bin/commitizen 或 ./node_modules/.bin/cz 来使用这些命令。

然后，你可以使用以下命令初始化 conventional changelog 适配器：./node_modules/.bin/commitizen init cz-conventional-changelog --save-dev --save-exact

接着，你可以在 package.json 文件中添加一些方便的 npm 脚本，指向本地版本的 Commitizen：

  ...
  "scripts": {
    "commit": "cz"
  }

这样对用户来说会更方便，因为他们想要提交代码时，只需运行 npm run commit，就会看到开始提交所需的提示！

注意： 如果你使用了类似 husky 的工具设置 precommit 钩子，就需要将脚本命名为 "commit" 以外的名称（例如，"cm": "cz"）。这是因为 npm 脚本有一项“特性”：它会自动运行名称为 prexxx 的脚本，其中 xxx 是另一个脚本的名称。也就是说，如果你将脚本命名为 "commit"，npm 和 husky 就会运行两次 "precommit" 脚本。解决方法是避免运行由 npm 触发的 precommit 脚本。

可选：在 `git commit` 时运行 Commitizen

本示例展示了如何通过使用 git 钩子和 --hook 命令行选项，将 Commitizen 集成到现有的 git commit 工作流中。这对于希望确保不熟悉 Commitizen 的贡献者也能遵循正确提交格式的项目维护者很有用。

实现上述任一方法后，运行 git commit 的用户都会看到一个交互式 Commitizen 会话，帮助他们编写有用的提交消息。

注意： 本示例假设项目已设置为在本地使用 Commitizen。

传统 Git 钩子

使用以下代码更新 .git/hooks/prepare-commit-msg：

#!/bin/bash
exec < /dev/tty && node_modules/.bin/cz --hook || true

Husky

对于 husky 用户，请将以下配置添加到项目的 package.json 文件中：

"husky": {
  "hooks": {
    "prepare-commit-msg": "exec < /dev/tty && npx cz --hook || true"
  }
}

为什么使用 exec < /dev/tty？ 默认情况下，Git 钩子不可交互。此命令允许用户在钩子运行期间使用终端与 Commitizen 交互。

恭喜！你的仓库已支持 Commitizen。是时候展示出来了！

使用以下 Markdown 将“支持 Commitizen”徽章添加到 README：

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)

你的徽章将如下所示：

你也可以考虑修改 README.md 或 CONTRIBUTING.md 文件，以介绍或链接到 Commitizen 项目，让新的贡献者了解如何安装和使用 Commitizen。

将规范提交消息用作全局工具

如果尚未全局安装 commitizen，请先安装。

npm install -g commitizen

全局安装你首选的 commitizen 适配器（例如 cz-conventional-changelog）。

npm install -g cz-conventional-changelog

在你的 home 目录中创建 .czrc 文件，其中的 path 指向首选的全局安装 commitizen 适配器

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

一切就绪！现在，进入任意 git 仓库，并使用 git cz 代替 git commit，即可看到 commitizen 提示。

专业提示：你可以将所有 git commit options 与 git cz 一起使用。例如：git cz -a。

如果你的仓库是 Node.js 项目，让它支持 Commitizen非常简单。

如果你的仓库已经支持 Commitizen，则会使用本地的 commitizen 适配器，而不是全局安装的适配器。

在多仓库项目中使用 Commitizen

如果你是多个项目的维护者，可能会希望为所有项目采用统一的提交消息格式。你可以创建自己的 node 模块，作为 Commitizen 的前端。

1. 创建自己的入口脚本

// my-cli.js

#!/usr/bin/env node
"use strict";

const path = require('path');
const bootstrap = require('commitizen/dist/cli/git-cz').bootstrap;

bootstrap({
  cliPath: path.join(__dirname, '../../node_modules/commitizen'),
  // this is new
  config: {
    "path": "cz-conventional-changelog"
  }
});

2. 将脚本添加到你的 `package.json` 文件中

// package.json

{
  "name": "company-commit",
  "bin": "./my-cli.js",
  "dependencies": {
    "commitizen": "^2.7.6",
    "cz-conventional-changelog": "^1.1.5"
  }
}

3. 发布到 npm 并使用它！

npm install --save-dev company-commit

./node_modules/.bin/company-commit

适配器

我们知道每个项目和构建流程都有不同的要求，因此我们尽量让 Commitizen 易于扩展。你可以选择任意预构建的适配器，也可以自行构建。以下是一些可供使用的优秀适配器：

要创建适配器，只需 fork 这些优秀适配器之一，并根据你的需求进行修改。我们会向你传入一个 Inquirer.js 实例，但你可以通过任何必要的方式获取输入。只需使用字符串调用 commit 回调，我们就会处理好一切。将它发布到 npm，你就大功告成了！

重试失败的提交

从 2.7.1 版开始，你可以使用 git cz --retry 命令尝试重试上一次提交。如果你设置了通过 git precommit 钩子运行的测试，这会很有帮助。在这种情况下，你可能尝试使用 Commitizen 提交，费心填写了所有 Commitizen 字段，但测试却失败了。在之前的 Commitizen 版本中，修复测试后，你必须重新填写所有字段。现在可以使用重试命令了。Commitizen 会重试你在此仓库中尝试进行的上一次提交，无需你再次填写字段。

请注意，升级 Commitizen 版本、升级适配器，或删除主目录或临时目录中的 commitizen.json 文件时，重试缓存可能会被清除。此外，提交缓存使用仓库的文件系统路径，因此如果你移动仓库或更改其路径，就无法重试提交。这属于边缘情况，但如果你会移动包含仓库的文件夹，可能会因此感到困惑。

需要注意的是，如果你通过 npm 脚本运行 cz（假设脚本名为 commit），则需要执行以下操作之一：