Skip to content
Biome 中文网
开发文档 当前版本 v1.9

Git Hooks

Git 允许在使用 Git Hooks 运行 git 命令期间执行脚本。例如，你可以在提交或推送之前格式化和 lint 暂存文件。有几种工具可以简化 Git Hooks 的管理。在下面的部分中，我们将介绍其中一些以及如何将它们与 Biome 一起使用。

¥Git allows executing scripts during the run of a git command using Git Hooks. For example, you can format and lint the staged files before committing or pushing. Several tools exist to simplify the management of Git Hooks. In the following sections we introduce some of them and how they can be used with Biome.

Lefthook

Section titled Lefthook

Lefthook 提供快速、跨平台且无依赖的钩子管理器。可以是 通过 NPM 安装。

¥Lefthook provides a fast, cross-platform, and dependency-free hook manager. It can be installed via NPM.

在 Git 存储库的根目录下添加一个名为 lefthook.yml 的文件。一些 Lefthook 配置示例：

¥Add a file named lefthook.yml at the root of your Git repository. Some examples of Lefthook configurations:

  • 字符类 、、

    ¥Check formatting and lint before committing

    lefthook.yml
    pre-commit:
      commands:
        check:
          glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
          run: npx @biomejs/biome check --no-errors-on-unmatched --files-ignore-unknown=true --colors=off {staged_files}

  • 提交前格式化、检查代码并应用安全代码修复

    ¥Format, lint, and apply safe code fixes before committing

    lefthook.yml
    pre-commit:
      commands:
        check:
          glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
          run: npx @biomejs/biome check --write --no-errors-on-unmatched --files-ignore-unknown=true --colors=off {staged_files}
          stage_fixed: true

    stage_fixed: true 再次添加暂存文件。

    ¥stage_fixed: true adds again the staged files.

  • 提交前检查格式和 lint

    ¥Check formatting and lint before pushing

    lefthook.yml
    pre-push:
      commands:
        check:
          glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
          run: npx @biomejs/biome check --no-errors-on-unmatched --files-ignore-unknown=true --colors=off {push_files}

请注意，你不需要同时使用 glob 和 --files-ignore-unknown=true。仅使用 --files-ignore-unknown=true 可以处理 Biome 目前和将来支持的文件。如果你希望更好地控制要处理的文件，则应使用 glob。

¥Note that you don’t need to use both glob and --files-ignore-unknown=true. Using only --files-ignore-unknown=true allows handling files supported in the present and in the future by Biome. If you wish more control over which files are handled, you should use glob.

--no-errors-on-unmatched 在没有处理任何文件的情况下会隐藏可能的错误。

¥--no-errors-on-unmatched silents possible errors in case no files are processed.

配置完成后，运行 lefthook install 以设置钩子。

¥Once configured, run lefthook install to set up the hooks.

Husky

Section titled Husky

Husky 是 JavaScript 生态系统中广泛使用的钩子管理器。Husky 不会隐藏未暂存的更改，也无法提供暂存文件的列表。这就是为什么它经常与另一个工具（如 lint-staged 或 git-format-staged）一起使用的原因。

¥Husky is a widely-used hook manager in the JavaScript ecosystem. Husky doesn’t hide unstaged changes and is not able to provide the list of staged files. This is why it is often used in tandem with another tool such as lint-staged or git-format-staged.

如果你的项目包含 package.json，你可以在使用 scripts.prepare 安装包时自动设置 husky 钩子：

¥If your project contains a package.json, you can automatically set up husky hooks upon package installation using scripts.prepare:

package.json
{
  "scripts": {
    "prepare": "husky"
  }
}

lint-staged

Section titled lint-staged

lint-staged 是 JavaScript 生态系统中最常用的工具之一。

¥lint-staged is one of the most used tools in the JavaScript ecosystem.

添加以下 husky 配置：

¥Add the following husky configuration:

.husky/pre-commit
lint-staged

lint-staged 的​​配置直接嵌入在 package.json 中。以下是运行 Git 钩子时可能有用的一些命令示例：

¥The configuration of lint-staged is directly embedded in package.json. Here’s some example of commands that you could find useful when running the Git hooks:

package.json
{
  "lint-staged": {
    // Run Biome on staged files that have the following extensions: js, ts, jsx, tsx, json and jsonc
    "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}": [
      "biome check --files-ignore-unknown=true", // Check formatting and lint
      "biome check --write --no-errors-on-unmatched", // Format, sort imports, lint, and apply safe fixes
      "biome check --write --organize-imports-enabled=false --no-errors-on-unmatched", // format and apply safe fixes
      "biome check --write --unsafe --no-errors-on-unmatched", // Format, sort imports, lints, apply safe/unsafe fixes
      "biome format --write --no-errors-on-unmatched", // Format
      "biome lint --write --no-errors-on-unmatched", // Lint and apply safe fixes
    ],
    // Alternatively you can pass every files and ignore unknown extensions
    "*": [
      "biome check --no-errors-on-unmatched --files-ignore-unknown=true", // Check formatting and lint
    ]
  }
}

请记住在命令中使用 CLI 选项 --no-errors-on-unmatched，以便在没有处理任何文件的情况下消除可能的错误。

¥Remember to use the CLI option --no-errors-on-unmatched in your command, to silent possible errors in case no files are processed.

git-format-staged

Section titled git-format-staged

与其他工具（如 lefthook、pre-commit 和 lint-staged）相比，git-format-staged 在内部不使用 git stash。当未暂存的更改和更新的暂存更改之间出现冲突时，这可以避免手动干预。查看 git-format-staged 与其他工具的比较。

¥In contrast to other tools such as lefthook, pre-commit, and lint-staged, git-format-staged doesn’t use git stash internally. This avoids manual intervention when conflicts arise between unstaged changes and updated staged changes. See the comparison of git-format-staged with other tools.

一些配置示例：

¥Some examples of configuration:

  • 字符类 、、

    ¥Check formatting and lint before committing

    .husky/pre-commit
    git-format-staged --formatter 'biome check --files-ignore-unknown=true --no-errors-on-unmatched \"{}\"' .

  • 提交前格式化、检查代码并应用安全代码修复

    ¥Format, lint, and apply safe code fixes before committing

    .husky/pre-commit
    git-format-staged --formatter 'biome check --write --files-ignore-unknown=true --no-errors-on-unmatched \"{}\"' .

pre-commit

Section titled pre-commit

pre-commit 提供多语言钩子管理器。Biome 通过 biomejs/pre-commit 存储库提供四个 pre-commit 钩子。

¥pre-commit provides a multi-language hook manager. Biome provides four pre-commit hooks via the biomejs/pre-commit repository.

钩子 iddescription
biome-ci推送前检查格式和 lint
biome-check格式化、组织导入、检查代码并应用安全修复到已提交的文件
biome-format格式化已提交的文件
biome-lint对已提交的文件进行 Lint 并应用安全修复

在下面的例子中，我们假设你在存储库中 安装预提交 并运行 pre-commit install。如果你想使用 biome-check 钩子，请在项目根目录中名为 .pre-commit-config.yaml 的文件中将以下预提交配置添加到其中：

¥In the following example, we assume that you installed pre-commit and run pre-commit install in your repository. if you want to use the biome-check hook, add the following pre-commit configuration to the root of your project in a file named .pre-commit-config.yaml:

.pre-commit-config.yaml
repos:
-   repo: https://github.com/biomejs/pre-commit
    rev: "v0.1.0"  # Use the sha / tag you want to point at
    hooks:
    -   id: biome-check
        additional_dependencies: ["@biomejs/biome@1.4.1"]

当你运行 git commit 时，这将运行 biome check --write。

¥This will run biome check --write when you run git commit.

请注意，由于 additional_dependencies 选项，你必须指定要使用的 Biome 版本。pre-commit 单独安装工具，需要知道要安装哪一个。

¥Note that you must specify which version of Biome to use thanks to the additional_dependencies option. pre-commit separately installs tools and need to know which one to install.

如果 Biome 已作为 npm 包安装在你的本地存储库中，那么在更新 Biome 时更新 package.json 和 .pre-commit-config.yaml 可能会很麻烦。你可以指定自己的 本地钩子，而不是使用提供的 Biome 钩子。

¥If Biome is already installed as a npm package in your local repository, then it can be a burden to update both package.json and .pre-commit-config.yaml when you update Biome. Instead of using the provided Biome hooks, you can specify your own local hook.

例如，如果你使用 npm，则可以在 .pre-commit-config.yaml 中编写以下钩子：

¥For example, if you use npm, you can write the following hook in .pre-commit-config.yaml:

.pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: local-biome-check
        name: biome check
        entry: npx @biomejs/biome check --write --files-ignore-unknown=true --no-errors-on-unmatched
        language: system
        types: [text]
        files: "\\.(jsx?|tsx?|c(js|ts)|m(js|ts)|d\\.(ts|cts|mts)|jsonc?)$"

预提交选项 files 是可选的，因为 Biome 能够忽略未知文件（使用选项 --files-ignore-unknown=true）。

¥The pre-commit option files is optional, because Biome is able to ignore unknown files (using the option --files-ignore-unknown=true).

Shell 脚本

Section titled Shell 脚本

¥Shell script

你还可以使用自定义 shell 脚本。请注意，你可能会遇到跨平台不兼容问题。我们建议使用专用工具，如前面几节中介绍的工具。

¥You can also use a custom shell script. Note that you can encounter cross-platform incompatibilities. We recommend the use of a dedicated tool as the one presented in the previous sections.

一些 shell 脚本示例：

¥Some examples of shells scripts:

  • 字符类 、、

    ¥Check formatting and lint before committing

    .git/hooks/pre-commit
    #!/bin/sh
    set -eu
    

    npx @biomejs/biome check --staged --files-ignore-unknown=true --no-errors-on-unmatched

  • 提交前格式化、检查代码并应用安全代码修复

    ¥Format, lint, and apply safe code fixes before committing

    .git/hooks/pre-commit
    #!/bin/sh
    set -eu
    

    if git status --short | grep --quiet '^MM'; then
      printf '%s\n' "ERROR: Some staged files have unstaged changes" >&2
      exit 1;
    fi
    

    npx @biomejs/biome check --write --staged --files-ignore-unknown=true --no-errors-on-unmatched
    

    git update-index --again

    请注意，如果暂存文件有未暂存的更改，我们将使钩子失败。

    ¥Note that we make the hook fail if staged files have unstaged changes.