diff --git a/website/docs/en/guide/_meta.json b/website/docs/en/guide/_meta.json index c8316513..e59fcba1 100644 --- a/website/docs/en/guide/_meta.json +++ b/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", diff --git a/website/docs/en/guide/cli/staged.mdx b/website/docs/en/guide/cli/staged.mdx index 0ff122f8..582bb554 100644 --- a/website/docs/en/guide/cli/staged.mdx +++ b/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', }); ``` diff --git a/website/docs/en/guide/git-hooks.mdx b/website/docs/en/guide/git-hooks.mdx new file mode 100644 index 00000000..b57fa088 --- /dev/null +++ b/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: + + + +`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. diff --git a/website/docs/zh/guide/_meta.json b/website/docs/zh/guide/_meta.json index 1c7c16cb..a1a41dc9 100644 --- a/website/docs/zh/guide/_meta.json +++ b/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", diff --git a/website/docs/zh/guide/cli/staged.mdx b/website/docs/zh/guide/cli/staged.mdx index 6191a678..8b716498 100644 --- a/website/docs/zh/guide/cli/staged.mdx +++ b/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', }); ``` diff --git a/website/docs/zh/guide/git-hooks.mdx b/website/docs/zh/guide/git-hooks.mdx new file mode 100644 index 00000000..ade6da5d --- /dev/null +++ b/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 安装： + + + +`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`。 + +全部任务通过后，提交会继续，并包含修复和格式化结果。任一任务失败都会中止提交，解决问题后重新提交即可。