diff --git a/website/docs/en/guide/cli/fmt.mdx b/website/docs/en/guide/cli/fmt.mdx index f6a59b1..d30a0e1 100644 --- a/website/docs/en/guide/cli/fmt.mdx +++ b/website/docs/en/guide/cli/fmt.mdx @@ -8,7 +8,7 @@ The `rs fmt` command formats files or checks whether they are formatted. For det rs fmt [options] [files/globs...] ``` -Pass files, directories, or glob patterns to choose what to format. When no paths are provided, `rs fmt` formats the current directory. +Pass files, directories, or glob patterns to choose what to format. When no paths are provided, `rs fmt` formats the current directory. See [Formatting scope](../formatting#formatting-scope) for path resolution and ignore rules. Examples: @@ -31,15 +31,68 @@ rs format ## Options -| Option | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | -| `--write` | Write formatted files in place. This is the default mode. | -| `--check` | Check formatting without writing files. Exits with code 1 when files are different. | -| `--list-different` | Print only unformatted paths. Exits with code 1 when files are different. | -| `--parallel-workers ` | Set the maximum number of formatting workers. | -| `--stdin-filepath ` | Format stdin as if it were saved at `` and print the result to stdout. | -| `-h, --help` | Display usage and option information. | +### `--check` -> `--write`, `--check`, and `--list-different` are mutually exclusive. +Check whether files are formatted without changing them. The output lists files with formatting issues and includes a human-friendly summary, making this option useful in CI: -> `--stdin-filepath` cannot be combined with `--write`, `--check`, `--list-different`, or file arguments. +```bash +rs fmt . --check +``` + +`--check` cannot be combined with `--write` or `--list-different`. + +The command uses the following exit codes: + +| Code | Meaning | +| ---- | --------------------------------------------------------- | +| `0` | All matched files are formatted. | +| `1` | One or more matched files have formatting issues. | +| `2` | `rs fmt` could not run or encountered a formatting error. | + +### `-h, --help` + +Display usage and option information without formatting files: + +```bash +rs fmt --help +``` + +### `--list-different` + +Print the paths of unformatted files without the summary produced by `--check`. This is useful when another command needs to consume the output: + +```bash +rs fmt . --list-different +``` + +The option uses the same exit codes as `--check` and cannot be combined with `--write` or `--check`. + +### `--parallel-workers ` + +Set the maximum number of formatting workers to a positive integer: + +```bash +rs fmt . --parallel-workers 4 +``` + +When this option is omitted, `rs fmt` automatically chooses up to eight workers based on the available CPU parallelism and the number of matched files. Set a lower value to limit CPU or memory usage in constrained environments. + +### `--stdin-filepath ` + +Format content received from stdin as if it were saved at ``. The path determines the parser and matching configuration overrides, but it does not need to exist on disk. The formatted content is written to stdout: + +```bash +cat src/index.ts | rs fmt --stdin-filepath src/index.ts +``` + +`--stdin-filepath` cannot be combined with file arguments or with `--write`, `--check`, or `--list-different`. See [Formatting stdin](../formatting#formatting-stdin) for details. + +### `--write` + +Write formatted files in place. This is the default mode, so specifying `--write` is optional: + +```bash +rs fmt src --write +``` + +`--write` cannot be combined with `--check` or `--list-different`. diff --git a/website/docs/zh/guide/cli/fmt.mdx b/website/docs/zh/guide/cli/fmt.mdx index 689a9ce..cda3f3c 100644 --- a/website/docs/zh/guide/cli/fmt.mdx +++ b/website/docs/zh/guide/cli/fmt.mdx @@ -8,7 +8,7 @@ rs fmt [options] [files/globs...] ``` -可以传入文件、目录或 glob 模式来指定格式化范围。不传入路径时，`rs fmt` 会格式化当前目录。 +可以传入文件、目录或 glob 模式来指定格式化范围。不传入路径时，`rs fmt` 会格式化当前目录。路径解析和忽略规则请参考[格式化范围](../formatting#formatting-scope)。 示例： @@ -31,15 +31,68 @@ rs format ## 选项 \{#options} -| 选项 | 说明 | -| ---------------------------- | --------------------------------------------------------- | -| `--write` | 将格式化结果写回文件。这是默认模式。 | -| `--check` | 检查格式但不写入文件；存在格式差异时以状态码 1 退出。 | -| `--list-different` | 仅输出未格式化的路径；存在格式差异时以状态码 1 退出。 | -| `--parallel-workers ` | 设置格式化 worker 的最大数量。 | -| `--stdin-filepath ` | 将标准输入按保存在 `` 的文件格式化并输出到 stdout。 | -| `-h, --help` | 显示命令用法和选项。 | +### `--check` -> `--write`、`--check` 和 `--list-different` 不能同时使用。 +检查文件是否已格式化，但不修改文件。输出会列出存在格式问题的文件，并提供便于阅读的汇总信息，因此适合在 CI 中使用： -> `--stdin-filepath` 不能与 `--write`、`--check`、`--list-different` 或文件参数同时使用。 +```bash +rs fmt . --check +``` + +`--check` 不能与 `--write` 或 `--list-different` 同时使用。 + +该命令使用以下退出状态码： + +| 状态码 | 含义 | +| ------ | ------------------------------------------- | +| `0` | 所有匹配的文件均已格式化。 | +| `1` | 一个或多个匹配的文件存在格式问题。 | +| `2` | `rs fmt` 无法运行或在格式化过程中遇到错误。 | + +### `-h, --help` + +显示命令用法和选项信息，但不格式化文件： + +```bash +rs fmt --help +``` + +### `--list-different` + +输出未格式化文件的路径，但不提供 `--check` 的汇总信息。需要将结果交给其他命令处理时，可以使用此选项： + +```bash +rs fmt . --list-different +``` + +此选项与 `--check` 使用相同的退出状态码，且不能与 `--write` 或 `--check` 同时使用。 + +### `--parallel-workers ` + +将格式化 worker 的最大数量设置为正整数： + +```bash +rs fmt . --parallel-workers 4 +``` + +省略此选项时，`rs fmt` 会根据可用的 CPU 并行度和匹配的文件数量，自动选择最多 8 个 worker。在资源受限的环境中，可以设置较小的值来限制 CPU 或内存用量。 + +### `--stdin-filepath ` + +将 stdin 传入的内容按保存在 `` 的文件进行格式化。该路径用于确定 parser 和匹配的覆盖配置，但不需要在磁盘上真实存在。格式化结果会输出到 stdout： + +```bash +cat src/index.ts | rs fmt --stdin-filepath src/index.ts +``` + +`--stdin-filepath` 不能与文件参数或 `--write`、`--check`、`--list-different` 同时使用。详细说明请参考[格式化标准输入](../formatting#formatting-stdin)。 + +### `--write` + +将格式化结果写回文件。这是默认模式，因此可以省略 `--write`： + +```bash +rs fmt src --write +``` + +`--write` 不能与 `--check` 或 `--list-different` 同时使用。