> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# Git hooks \{#git-hooks}

使用 [`rs hooks`](/zh/guide/cli/hooks.md) 可以统一管理仓库级 Git hooks，并通过 hook 脚本运行项目命令。hook 脚本默认存放在 `.rstack/hooks` 中，可用于校验提交信息、推送前检查代码、提交前格式化文件等场景。

下面以 `pre-commit` 为例：先通过 `rs hooks` 安装 Git hooks，再在 `pre-commit` hook 中运行 [`rs staged`](/zh/guide/cli/staged.md)，对本次提交的暂存文件进行代码检查和格式化。

## 安装 hooks \{#set-up-hooks}

在负责管理仓库 hooks 的项目中，将 `rs hooks` 添加到 `package.json` 的 `prepare` 脚本：

```json title="package.json"
{
  "scripts": {
    "prepare": "rs hooks"
  }
}
```

执行一次该脚本，完成 hooks 安装：


```sh [npm]
npm run prepare
```

```sh [yarn]
yarn run prepare
```

```sh [pnpm]
pnpm run prepare
```

```sh [bun]
bun run prepare
```

`rs hooks` 会将仓库的 `core.hooksPath` 设为 `.rstack/hooks/_`，可以通过以下命令确认是否安装成功：

```bash
git config --get core.hooksPath
# .rstack/hooks/_
```

:::tip

- `_` 目录由命令动态生成，且默认被 Git 忽略。
- 如果检测到其他 hooks 路径或已有 Git hooks，`rs hooks` 会跳过安装。可运行 `rs hooks --force` 强制安装 Rstack hooks。详细说明请参考 [`rs hooks` 指南](/zh/guide/cli/hooks.md)。

:::

## 提交前检查 \{#pre-commit-checks}

通过 `pre-commit` hook 可以检查和格式化本次提交的暂存文件。

### 配置任务 \{#configure-tasks}

在 Rstack 配置文件中添加暂存文件任务，根据项目实际使用的语言来调整 glob 模式：

```ts title="rstack.config.ts"
import { define } from 'rstack';

define.staged({
  '*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}': ['rs lint --fix', 'rs fmt'],
  '*.{json,md,mdx,css,scss,less,html,yml,yaml}': 'rs fmt',
});
```

### 添加 hook \{#add-the-hook}

创建 `.rstack/hooks/pre-commit`，并在其中运行 `rs staged`：

```sh title=".rstack/hooks/pre-commit"
rs staged
```

### 执行流程 \{#how-it-works}

运行 `git commit` 时，Git 会调用 `rs hooks` 安装的 hook。该 hook 会执行 `.rstack/hooks/pre-commit`，再由 `rs staged` 对暂存文件运行配置的任务。

`rs staged` 会将匹配的暂存文件传给对应命令，数组中的命令按顺序执行，[`rs lint --fix`](/zh/guide/cli/lint.md) 先修复可自动处理的问题，再由 [`rs fmt`](/zh/guide/cli/fmt.md) 统一格式。如果只希望代码检查阻止提交而不修改文件，可以移除 `--fix`。

全部任务通过后，提交会继续，并包含修复和格式化结果。任一任务失败都会中止提交，解决问题后重新提交即可。