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

# fmt

`rs fmt` 命令用于格式化文件或检查文件格式。详细用法请参考[格式化](/zh/guide/formatting.md)指南。

## 用法 \{#usage}

```bash
rs fmt [options] [files/globs...]
```

可以传入文件、目录或 glob 模式来指定格式化范围。不传入路径时，`rs fmt` 会格式化当前目录。路径解析和忽略规则请参考[格式化范围](/zh/guide/formatting.md#formatting-scope)。

示例：

```bash
# 格式化当前目录中的文件
rs fmt

# 格式化指定文件和目录
rs fmt src package.json

# 在 CI 中检查格式
rs fmt --check
```

`rs format` 是 `rs fmt` 的别名：

```bash
rs format
```

## 选项 \{#options}

### `--check`

检查文件是否已格式化，但不修改文件。输出会列出存在格式问题的文件，并提供便于阅读的汇总信息，因此适合在 CI 中使用：

```bash
rs fmt --check
```

`--check` 不能与 `--write` 或 `--list-different` 同时使用。

该命令使用以下退出状态码：

| 状态码 | 含义                |
| --- | ----------------- |
| `0` | 命令执行成功。           |
| `1` | 一个或多个文件存在格式问题。    |
| `2` | 命令无法运行或执行过程中遇到错误。 |

### `-h, --help`

显示命令用法和选项信息，但不格式化文件：

```bash
rs fmt --help
```

### `--ignore-path <path>`

使用 `--ignore-path` 从文件中加载额外的 Gitignore 兼容规则。

相对的 ignore 文件路径基于当前工作目录解析。文件中的规则基于该文件所在目录解析。

例如，在项目根目录执行以下命令：

```bash
rs fmt --ignore-path config/format.ignore
```

假设 `config/format.ignore` 包含以下规则：

```text title="config/format.ignore"
generated/**
```

这里，`config/format.ignore` 相对项目根目录定位。文件中的 `generated/**` 规则则相对 `config/` 目录解析。因此，它会忽略 `config/generated/**`，而不是项目根目录下的 `generated/**`。

加载的规则会作用于扫描得到的路径、显式传入的文件、`--stdin-filepath`，以及通过 `--lsp` 格式化的文档。

如需加载多个 ignore 文件，可以重复传入该选项：

```bash
rs fmt --ignore-path .prettierignore --ignore-path config/format.ignore
```

每个文件都是独立的忽略来源。关于这些来源与 `.gitignore`、默认忽略规则和 `ignorePatterns` 的组合方式，请参考[忽略顺序](/zh/guide/formatting.md#ignore-order)。

### `--ignore-unknown`

忽略无法推断 parser 的匹配文件。即使所有匹配文件的类型均未知，该选项也可以让命令成功退出：

```bash
rs fmt --ignore-unknown
```

短选项 `-u` 是 `--ignore-unknown` 的别名。

```bash
rs fmt -u
```

此选项不会忽略未匹配路径或 glob 的错误。如果集成需要同时容忍这两种情况，可以将它与 [`--no-error-on-unmatched-pattern`](#--no-error-on-unmatched-pattern) 一起使用。

与 `--stdin-filepath` 一起使用时，不支持的输入会被跳过，且不会输出内容。

### `--list-different`

输出未格式化文件的路径，但不提供 `--check` 的汇总信息。需要将结果交给其他命令处理时，可以使用此选项：

```bash
rs fmt --list-different
```

短选项 `-l` 是 `--list-different` 的别名：

```bash
rs fmt -l
```

此选项与 `--check` 使用相同的退出状态码，且不能与 `--write` 或 `--check` 同时使用。

### `--lsp`

启动一个 language server，通过 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 在 stdio 上为编辑器提供格式化能力：

```bash
rs fmt --lsp
```

该 server 只声明 document formatting 一项能力，格式化的是编辑器内存中的 buffer，而不是磁盘上的文件。编辑器传入的格式化选项（如缩进宽度）会被忽略，Rstack 配置是唯一的配置来源。被忽略、无法推断 parser 或解析失败的文件不会返回任何编辑操作，而不是返回错误。

server 只为编辑器上报的 workspace root 加载一份配置，不会按文件发现嵌套配置；如果项目包含多份配置，请为每个配置根目录各启动一个 server。配置会在第一次格式化请求时加载，并在 server 的整个生命周期内复用；修改配置后需要重启 server。除全局的 [`--config`](/zh/guide/configuration.md#configuration-file) 选项外，只有 [`--ignore-path`](#--ignore-path-path) 会影响该 server。两者的相对路径都相对于 server 的启动目录解析。

在任何支持 LSP 的编辑器中将 `rs fmt --lsp` 注册为自定义 language server，即可手动或在保存时格式化。

> `--lsp` 不能与文件参数，或 `--write`、`--check`、`--list-different`、`--stdin-filepath` 同时使用。

### `--no-cache`

在当前调用中关闭持久化格式化缓存：

```bash
rs fmt --no-cache
```

默认情况下，`rs fmt` 会将缓存数据保存在 Rstack 配置根目录下的 `.rstack/cache/fmt` 中。`--no-cache` 会阻止命令读取、创建或更新该缓存。stdin 格式化始终不会使用持久化缓存。

缓存行为和清理方式请参考[缓存](/zh/guide/formatting.md#cache)。

### `--cache-location <path>`

将持久化缓存保存到自定义目录：

```bash
rs fmt --cache-location .cache/rs-fmt
```

相对路径基于当前工作目录解析，绝对路径则原样使用。目录会在需要时自动创建，并从文件发现中排除。与默认缓存位置不同，自定义目录不会自动生成 `.gitignore`；请将其排除在版本控制之外，或通过 CI 缓存配置进行管理。

同时使用两个选项时，优先使用 `--no-cache`，且不会从文件发现中排除自定义目录。

### `--no-error-on-unmatched-pattern`

如果传入的路径或 glob 没有匹配任何文件（包括所有匹配文件均被忽略的情况），则不输出诊断信息并成功退出：

```bash
rs fmt --no-error-on-unmatched-pattern 'src/**/*.ts'
```

例如，pre-commit 脚本可能会始终运行 `rs fmt`，即使暂存的改动中没有支持的文件。此选项可让命令在这种情况下成功退出，避免阻止提交。

> [`rs staged`](/zh/guide/cli/staged.md) 会为其中的 `rs fmt` 任务自动启用此行为。

### `--parallel-workers <count>`

将格式化 worker 的最大数量设置为正整数：

```bash
rs fmt --parallel-workers 4
```

省略此选项时，`rs fmt` 会根据可用的 CPU 并行度和匹配的文件数量，自动选择最多 8 个 worker。在资源受限的环境中，可以设置较小的值来限制 CPU 或内存用量。

### `--stdin-filepath <path>`

将 stdin 传入的内容按保存在 `<path>` 的文件进行格式化，例如用于编辑器集成。该路径用于确定 parser 和匹配的[覆盖配置](/zh/guide/formatting.md#overrides)，但不需要在磁盘上真实存在：

```bash
cat src/index.ts | rs fmt --stdin-filepath src/index.ts
```

格式化结果写入 stdout，诊断信息写入 stderr。若输入路径被忽略，`rs fmt` 会跳过格式化并原样输出内容；若无法根据路径推断 parser 或内容解析失败，则输出错误并以状态码 `2` 退出。

> `--stdin-filepath` 不能与文件参数或 `--write`、`--check`、`--list-different` 同时使用。

### `--with-node-modules`

处理 `node_modules` 中的文件。默认情况下，`rs fmt` 会排除这些文件：

```bash
rs fmt --with-node-modules node_modules/example/index.js
```

此选项只会关闭内置的 `node_modules` 排除规则。目录和 glob 扫描仍然遵循 `.gitignore`，`ignorePatterns` 和 `--ignore-path` 也会继续作用于所有输入。

### `--write`

将格式化结果写回文件。这是默认模式，因此可以省略 `--write`：

```bash
rs fmt src --write
```

短选项 `-w` 是 `--write` 的别名：

```bash
rs fmt -w src
```

`--write` 不能与 `--check` 或 `--list-different` 同时使用。