Skip to content

Commit 08ee874

Browse files
chenjiahanchenjiahan
committed
docs: add Git hooks guide
1 parent 1b5185b commit 08ee874

6 files changed

Lines changed: 176 additions & 4 deletions

File tree

‎website/docs/en/guide/_meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,11 @@
4242
"name": "formatting",
4343
"label": "Formatting"
4444
},
45+
{
46+
"type": "file",
47+
"name": "git-hooks",
48+
"label": "Git hooks"
49+
},
4550
{
4651
"type": "file",
4752
"name": "monorepo",

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ Configure staged-file tasks through [`define.staged()`](../configuration#define-
9696
import { define } from 'rstack';
9797

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

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
description: 'Set up repository Git hooks with Rstack CLI and automatically lint and format staged files before each commit.'
3+
---
4+
5+
# Git hooks
6+
7+
import { PackageManagerTabs } from '@rspress/core/theme';
8+
9+
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.
10+
11+
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.
12+
13+
## Set up hooks
14+
15+
Add `rs setup` to the `prepare` script of the project that owns the repository hooks:
16+
17+
```json title="package.json"
18+
{
19+
"scripts": {
20+
"prepare": "rs setup"
21+
}
22+
}
23+
```
24+
25+
Run the script once to install the hooks:
26+
27+
<PackageManagerTabs
28+
command={{
29+
npm: 'npm run prepare',
30+
yarn: 'yarn run prepare',
31+
pnpm: 'pnpm run prepare',
32+
bun: 'bun run prepare',
33+
}}
34+
/>
35+
36+
`rs setup` sets the repository's `core.hooksPath` to `.rstack/hooks/_`. Verify the installation with:
37+
38+
```bash
39+
git config --local --get core.hooksPath
40+
# .rstack/hooks/_
41+
```
42+
43+
:::tip
44+
45+
- The `_` directory is generated dynamically and ignored by Git by default.
46+
- 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.
47+
48+
:::
49+
50+
## Pre-commit checks
51+
52+
A `pre-commit` hook can lint and format the files staged for the current commit.
53+
54+
### Configure tasks
55+
56+
Add staged-file tasks to the Rstack config file. Adjust the glob patterns for the languages used by your project:
57+
58+
```ts title="rstack.config.ts"
59+
import { define } from 'rstack';
60+
61+
define.staged({
62+
'*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}': ['rs lint --fix', 'rs fmt'],
63+
'*.{json,md,mdx,css,scss,less,html,yml,yaml}': 'rs fmt',
64+
});
65+
```
66+
67+
### Add the hook
68+
69+
Create `.rstack/hooks/pre-commit` and run `rs staged` from it:
70+
71+
```sh title=".rstack/hooks/pre-commit"
72+
rs staged
73+
```
74+
75+
### How it works
76+
77+
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.
78+
79+
`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.
80+
81+
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‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,11 @@
4242
"name": "formatting",
4343
"label": "格式化"
4444
},
45+
{
46+
"type": "file",
47+
"name": "git-hooks",
48+
"label": "Git hooks"
49+
},
4550
{
4651
"type": "file",
4752
"name": "monorepo",

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ rs staged --help
9696
import { define } from 'rstack';
9797

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

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
description: '使用 Rstack CLI 配置仓库级 Git hooks，并在提交前自动检查和格式化暂存文件。'
3+
---
4+
5+
# Git hooks \{#git-hooks}
6+
7+
import { PackageManagerTabs } from '@rspress/core/theme';
8+
9+
使用 [`rs setup`](./cli/setup) 可以统一管理仓库级 Git hooks，并通过 hook 脚本运行项目命令。hook 脚本默认存放在 `.rstack/hooks` 中，可用于校验提交信息、推送前检查代码、提交前格式化文件等场景。
10+
11+
下面以 `pre-commit` 为例：先通过 `rs setup` 安装 Git hooks，再在 `pre-commit` hook 中运行 [`rs staged`](./cli/staged)，对本次提交的暂存文件进行代码检查和格式化。
12+
13+
## 安装 hooks \{#set-up-hooks}
14+
15+
在负责管理仓库 hooks 的项目中，将 `rs setup` 添加到 `package.json` 的 `prepare` 脚本：
16+
17+
```json title="package.json"
18+
{
19+
"scripts": {
20+
"prepare": "rs setup"
21+
}
22+
}
23+
```
24+
25+
执行一次该脚本，完成 hooks 安装：
26+
27+
<PackageManagerTabs
28+
command={{
29+
npm: 'npm run prepare',
30+
yarn: 'yarn run prepare',
31+
pnpm: 'pnpm run prepare',
32+
bun: 'bun run prepare',
33+
}}
34+
/>
35+
36+
`rs setup` 会将仓库的 `core.hooksPath` 设为 `.rstack/hooks/_`，可以通过以下命令确认是否安装成功：
37+
38+
```bash
39+
git config --local --get core.hooksPath
40+
# .rstack/hooks/_
41+
```
42+
43+
:::tip
44+
45+
- `_` 目录由命令动态生成，且默认被 Git 忽略。
46+
- 如果检测到其他 hooks 路径或已有 Git hooks，`rs setup` 会跳过安装。请先迁移需要保留的 hooks，移除原有配置，然后重试。详细说明请参考 [`rs setup` 指南](./cli/setup#hook-files)。
47+
48+
:::
49+
50+
## 提交前检查 \{#pre-commit-checks}
51+
52+
通过 `pre-commit` hook 可以检查和格式化本次提交的暂存文件。
53+
54+
### 配置任务 \{#configure-tasks}
55+
56+
在 Rstack 配置文件中添加暂存文件任务，根据项目实际使用的语言来调整 glob 模式：
57+
58+
```ts title="rstack.config.ts"
59+
import { define } from 'rstack';
60+
61+
define.staged({
62+
'*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}': ['rs lint --fix', 'rs fmt'],
63+
'*.{json,md,mdx,css,scss,less,html,yml,yaml}': 'rs fmt',
64+
});
65+
```
66+
67+
### 添加 hook \{#add-the-hook}
68+
69+
创建 `.rstack/hooks/pre-commit`，并在其中运行 `rs staged`：
70+
71+
```sh title=".rstack/hooks/pre-commit"
72+
rs staged
73+
```
74+
75+
### 执行流程 \{#how-it-works}
76+
77+
运行 `git commit` 时，Git 会调用 `rs setup` 安装的 hook。该 hook 会执行 `.rstack/hooks/pre-commit`，再由 `rs staged` 对暂存文件运行配置的任务。
78+
79+
`rs staged` 会将匹配的暂存文件传给对应命令，数组中的命令按顺序执行，[`rs lint --fix`](./cli/lint) 先修复可自动处理的问题，再由 [`rs fmt`](./cli/fmt) 统一格式。如果只希望代码检查阻止提交而不修改文件，可以移除 `--fix`。
80+
81+
全部任务通过后，提交会继续，并包含修复和格式化结果。任一任务失败都会中止提交，解决问题后重新提交即可。

0 commit comments

Comments
 (0)