指南：本地设置

¥Guide: Local setup

通过在编写提交消息时立即对其进行 linting，获得高质量的提交消息和较短的反馈周期。

¥Get high commit message quality and short feedback cycles by linting commit messages right when they are authored.

本指南演示了如何通过 git hooks 实现此操作。

¥This guide demonstrates how to achieve this via git hooks.

请遵循 入门指南 的基本安装和配置说明。

¥Follow the Getting Started for basic installation and configuration instructions.

添加钩子

¥Add hook

要使用 commitlint，你需要设置 commit-msg 钩子（目前不支持 pre-commit 钩子）。

¥To use commitlint you need to setup commit-msg hook (currently pre-commit hook is not supported)

使用 git hooks 管理器

¥Using a git hooks manager

要在提交创建之前对其进行 lint 处理，你可以使用 Husky 的 commit-msg 钩子。

¥To lint commits before they are created you can use Husky's commit-msg hook.

你可以在 官方文档 上找到完整的设置说明。

¥You can find complete setup instructions on the official documentation.

如果你使用的是其他版本，以下说明适用于 `husky@v9`，请查阅你版本的官方文档。

¥[!NOTE] The following instructions are meant to husky@v9 if you are using a different version consult the official documentation of your version.

[!警告] 对于 Windows 用户：确保所有 husky 文件都已编码为 UTF-8。如果使用任何其他格式，例如 无法执行二进制文件，运行时可能会抛出错误。

¥[!WARNING] For Windows users: ensure all husky files are UTF-8 enconded. If any other format is used an error may be thrown at runtime such as cannot execute binary file.

---

npm install --save-dev husky

npx husky install

# Add commit message linting to commit-msg hook
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
# Windows users should use ` to escape dollar signs
echo "npx --no commitlint --edit `$1" > .husky/commit-msg

或者，你可以在 package.json 中创建一个脚本。

¥As an alternative you can create a script inside package.json

npm pkg set scripts.commitlint="commitlint --edit"
echo "npm run commitlint \${1}" > .husky/commit-msg

---

使用 git hooks

¥Using git hooks

有关 git hooks 的信息可以在 Git 文档 上找到。

¥Info about git hooks can be found on Git documentation.

必须使用 commit-msg 作为钩子文件的名称。

¥[!WARNING] It's necessary that you use commit-msg as the name for hook file.

测试

¥Test

测试简单用法

¥Test simple usage

对于 commitlint 的首次简单使用测试，你可以执行以下操作：

¥For a first simple usage test of commitlint you can do the following:

npx commitlint --from HEAD~1 --to HEAD --verbose

此操作将检查你的最后一次提交，如果无效则返回错误，如果有效则返回正值。

¥This will check your last commit and return an error if invalid or a positive output if valid.

测试钩子

¥Test the hook

你可以通过简单的提交来测试钩子。如果一切正常，你应该看到类似这样的结果。

¥You can test the hook by simply committing. You should see something like this if everything works.

git commit -m "foo: this will fail"
#  husky > commit-msg
No staged files match any of provided globs.
⧗   input: foo: this will fail
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

✖   found 1 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky - commit-msg script failed (code 1)

由于 v8.0.0 的规则没有问题，因此如果你的提交没有问题，commitlint 不会输出任何内容。（你可以使用 --verbose 标志来获得正值输出）

¥Since v8.0.0 commitlint won't output anything if there are no problems with your commit.\ (You can use the --verbose flag to get positive output)

git commit -m "chore: lint on commitmsg"
# husky > pre-commit
No staged files match any of provided globs.
# husky > commit-msg

本地 lint 可以快速获得反馈，但很容易进行修改。为了确保所有提交都经过 lint 处理，你还需要在自动化 CI 服务器上检查提交。了解如何在 CI 设置指南 中使用。

¥Local linting is fine for fast feedback but can easily be tinkered with. To ensure all commits are linted you'll want to check commits on an automated CI Server too. Learn how to in the CI Setup guide.