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

# staged

`rs staged` 命令使用 [lint-staged](https://github.com/lint-staged/lint-staged) 对 Git 暂存文件运行任务。

`rs staged` 可用于在提交代码前，对暂存文件运行 linter、格式化工具或其他检查。

常见做法是将 `rs staged` 与 [`rs hooks`](/zh/guide/cli/hooks.md) 配合使用，通过 `pre-commit` hook 运行暂存文件任务。

## 用法 \{#usage}

```bash
rs staged [options]
```

该命令会加载通过 [`define.staged()`](/zh/guide/configuration.md#define-staged) 注册的暂存文件任务。

## 选项 \{#options}

### `--allow-empty`

`--allow-empty` 允许在任务撤销全部暂存变更时创建空提交。

```bash
rs staged --allow-empty
```

### `--concurrent`

`--concurrent` 用于控制同时运行的任务数量，可设置为 `true`、`false` 或正整数。

省略该选项时，默认值为 `true`，`rs staged` 会并发运行任务且不设置固定的并发上限。设为 `false` 时会逐个运行任务；设为正整数时，会限制同时运行的任务数量。

```bash
# 使用默认行为：并发运行任务，不设置固定的并发上限
rs staged
rs staged --concurrent true

# 每次运行一个任务
rs staged --concurrent false

# 最多同时运行四个任务
rs staged --concurrent 4

# -p 是 --concurrent 的缩写
rs staged -p 4
```

例如：

```ts
define.staged({
  '*.ts': ['rs lint --fix', 'rs fmt'],
  '*.md': 'rs fmt',
});
```

启用并发时，Markdown 文件的 `rs fmt` 可以在 TypeScript 文件执行 `rs lint --fix` 的同时运行；对于 TypeScript 文件，只有 `rs lint --fix` 完成后才会运行 `rs fmt`。

### `--cwd`

`--cwd` 用于设置运行所有任务时使用的工作目录。

```bash
rs staged --cwd packages/app
```

### `--debug`

`--debug`（或 `-d`）用于输出额外的调试信息。

```bash
rs staged --debug
```

### `--no-stash`

`--no-stash` 会禁用备份 stash，并在任务失败时跳过自动还原。

```bash
rs staged --no-stash
```

### `--quiet`

`--quiet`（或 `-q`）用于禁用 lint-staged 自身的控制台输出。

```bash
rs staged --quiet
```

### `--relative`

`--relative`（或 `-r`）会将相对于工作目录的文件路径传递给任务。

```bash
rs staged --relative
```

### `--verbose`

`--verbose`（或 `-v`）会在任务成功时也显示其输出；默认仅显示失败任务的输出。

```bash
rs staged --verbose
```

### `--help`

`--help`（或 `-h`）用于显示命令的用法和选项。

```bash
rs staged --help
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.staged()`](/zh/guide/configuration.md#define-staged) 配置暂存文件任务。该 API 支持标准的 [lint-staged 配置](https://github.com/lint-staged/lint-staged#configuration)：

```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',
});
```