docs: add Git hooks guide

website/docs/en/guide/_meta.json

@@ -42,6 +42,11 @@
     "name": "formatting",
     "label": "Formatting"
   },
+  {
+    "type": "file",
+    "name": "git-hooks",
+    "label": "Git hooks"
+  },
   {
     "type": "file",
     "name": "monorepo",

website/docs/en/guide/cli/staged.mdx

@@ -96,7 +96,7 @@ Configure staged-file tasks through [`define.staged()`](../configuration#define-
 import { define } from 'rstack';
 
 define.staged({
-  '*.{js,jsx,ts,tsx}': ['rs lint', 'rs fmt'],
-  '*.{json,md,mdx,css,html}': 'rs fmt',
+  '*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}': ['rs lint --fix', 'rs fmt'],
+  '*.{json,md,mdx,css,scss,less,html,yml,yaml}': 'rs fmt',
 });
 ```

website/docs/en/guide/git-hooks.mdx

@@ -0,0 +1,81 @@
+---
+description: 'Set up repository Git hooks with Rstack CLI and automatically lint and format staged files before each commit.'
+---
+
+# Git hooks
+
+import { PackageManagerTabs } from '@rspress/core/theme';
+
+Use [`rs setup`](./cli/setup) to manage repository-level Git hooks that run project commands. By default, hook scripts live in `.rstack/hooks`. You can use them to validate commit messages, check code before pushing, or format files before committing.
+
+This page uses `pre-commit` as an example: first install Git hooks with `rs setup`, then run [`rs staged`](./cli/staged) from the `pre-commit` hook to lint and format the files staged for the commit.
+
+## Set up hooks
+
+Add `rs setup` to the `prepare` script of the project that owns the repository hooks:
+
+```json title="package.json"
+{
+  "scripts": {
+    "prepare": "rs setup"
+  }
+}
+```
+
+Run the script once to install the hooks:
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm run prepare',
+    yarn: 'yarn run prepare',
+    pnpm: 'pnpm run prepare',
+    bun: 'bun run prepare',
+  }}
+/>
+
+`rs setup` sets the repository's `core.hooksPath` to `.rstack/hooks/_`. Verify the installation with:
+
+```bash
+git config --local --get core.hooksPath
+# .rstack/hooks/_
+```
+
+:::tip
+
+- The `_` directory is generated dynamically and ignored by Git by default.
+- If `rs setup` detects another hooks path or existing Git hooks, it skips installation. Migrate any hooks you want to keep, remove the existing configuration, and then try again. See the [`rs setup` guide](./cli/setup#hook-files) for details.
+
+:::
+
+## Pre-commit checks
+
+A `pre-commit` hook can lint and format the files staged for the current commit.
+
+### Configure tasks
+
+Add staged-file tasks to the Rstack config file. Adjust the glob patterns for the languages used by your project:
+
+```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',
+});
+```
+
+### Add the hook
+
+Create `.rstack/hooks/pre-commit` and run `rs staged` from it:
+
+```sh title=".rstack/hooks/pre-commit"
+rs staged
+```
+
+### How it works
+
+When you run `git commit`, Git invokes the hook installed by `rs setup`. The hook executes `.rstack/hooks/pre-commit`, and `rs staged` then runs the configured tasks on the staged files.
+
+`rs staged` passes matching staged files to each command. Commands in an array run in order: [`rs lint --fix`](./cli/lint) first applies available fixes, then [`rs fmt`](./cli/fmt) formats the result. Remove `--fix` if lint errors should block the commit without changing files.
+
+After every task passes, the commit continues and includes the fixed and formatted results. If any task fails, the commit stops; fix the issue and then try again.

website/docs/zh/guide/_meta.json

@@ -42,6 +42,11 @@
     "name": "formatting",
     "label": "格式化"
   },
+  {
+    "type": "file",
+    "name": "git-hooks",
+    "label": "Git hooks"
+  },
   {
     "type": "file",
     "name": "monorepo",

website/docs/zh/guide/cli/staged.mdx

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

website/docs/zh/guide/git-hooks.mdx

@@ -0,0 +1,81 @@
+---
+description: '使用 Rstack CLI 配置仓库级 Git hooks，并在提交前自动检查和格式化暂存文件。'
+---
+
+# Git hooks \{#git-hooks}
+
+import { PackageManagerTabs } from '@rspress/core/theme';
+
+使用 [`rs setup`](./cli/setup) 可以统一管理仓库级 Git hooks，并通过 hook 脚本运行项目命令。hook 脚本默认存放在 `.rstack/hooks` 中，可用于校验提交信息、推送前检查代码、提交前格式化文件等场景。
+
+下面以 `pre-commit` 为例：先通过 `rs setup` 安装 Git hooks，再在 `pre-commit` hook 中运行 [`rs staged`](./cli/staged)，对本次提交的暂存文件进行代码检查和格式化。
+
+## 安装 hooks \{#set-up-hooks}
+
+在负责管理仓库 hooks 的项目中，将 `rs setup` 添加到 `package.json` 的 `prepare` 脚本：
+
+```json title="package.json"
+{
+  "scripts": {
+    "prepare": "rs setup"
+  }
+}
+```
+
+执行一次该脚本，完成 hooks 安装：
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm run prepare',
+    yarn: 'yarn run prepare',
+    pnpm: 'pnpm run prepare',
+    bun: 'bun run prepare',
+  }}
+/>
+
+`rs setup` 会将仓库的 `core.hooksPath` 设为 `.rstack/hooks/_`，可以通过以下命令确认是否安装成功：
+
+```bash
+git config --local --get core.hooksPath
+# .rstack/hooks/_
+```
+
+:::tip
+
+- `_` 目录由命令动态生成，且默认被 Git 忽略。
+- 如果检测到其他 hooks 路径或已有 Git hooks，`rs setup` 会跳过安装。请先迁移需要保留的 hooks，移除原有配置，然后重试。详细说明请参考 [`rs setup` 指南](./cli/setup#hook-files)。
+
+:::
+
+## 提交前检查 \{#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 setup` 安装的 hook。该 hook 会执行 `.rstack/hooks/pre-commit`，再由 `rs staged` 对暂存文件运行配置的任务。
+
+`rs staged` 会将匹配的暂存文件传给对应命令，数组中的命令按顺序执行，[`rs lint --fix`](./cli/lint) 先修复可自动处理的问题，再由 [`rs fmt`](./cli/fmt) 统一格式。如果只希望代码检查阻止提交而不修改文件，可以移除 `--fix`。
+
+全部任务通过后，提交会继续，并包含修复和格式化结果。任一任务失败都会中止提交，解决问题后重新提交即可。