> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # fmt The `rs fmt` command formats files or checks whether they are formatted. For detailed usage, see [Formatting](/guide/formatting.md). ## Usage ```bash 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. See [Formatting scope](/guide/formatting.md#formatting-scope) for path resolution and ignore rules. Examples: ```bash # Format files in the current directory rs fmt # Format specific files and directories rs fmt src package.json # Check formatting in CI rs fmt --check ``` `rs format` is an alias for `rs fmt`: ```bash rs format ``` ## Options ### `--check` 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: ```bash rs fmt --check ``` `--check` cannot be combined with `--write` or `--list-different`. The command uses the following exit codes: | Code | Meaning | | ---- | -------------------------------------------------- | | `0` | The command completed successfully. | | `1` | One or more files have formatting issues. | | `2` | The command could not run or encountered an error. | ### `-h, --help` Display usage and option information without formatting files: ```bash rs fmt --help ``` ### `--ignore-path ` Use `--ignore-path` to load additional Gitignore-compatible rules from a file. Relative ignore-file paths are resolved from the current working directory. Rules inside a file are resolved from the directory containing that file. For example, run the following command from the project root: ```bash rs fmt --ignore-path config/format.ignore ``` If `config/format.ignore` contains this rule: ```text title="config/format.ignore" generated/** ``` Here, `config/format.ignore` is located relative to the project root. The `generated/**` rule is relative to `config/`. It therefore ignores `config/generated/**` instead of `generated/**` in the project root. Loaded rules apply to scanned paths, explicitly passed files, `--stdin-filepath`, and documents formatted through `--lsp`. To load multiple ignore files, repeat the option: ```bash rs fmt --ignore-path .prettierignore --ignore-path config/format.ignore ``` Each file acts as a separate ignore source. See [Ignore order](/guide/formatting.md#ignore-order) for how these sources combine with `.gitignore`, default ignore rules, and `ignorePatterns`. ### `--ignore-unknown` Ignore matched files when no parser can be inferred. This allows the command to exit successfully even when every matched file has an unknown type: ```bash rs fmt --ignore-unknown ``` The short option `-u` is an alias for `--ignore-unknown`. ```bash rs fmt -u ``` This option does not suppress errors for unmatched paths or globs. Combine it with [`--no-error-on-unmatched-pattern`](#--no-error-on-unmatched-pattern) when an integration needs to tolerate both cases. When used with `--stdin-filepath`, unsupported input is skipped without writing output. ### `--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 short option `-l` is an alias for `--list-different`: ```bash rs fmt -l ``` The option uses the same exit codes as `--check` and cannot be combined with `--write` or `--check`. ### `--lsp` Run a language server that formats editor buffers over the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) on stdio: ```bash rs fmt --lsp ``` The server only advertises document formatting and formats the buffer held by the editor, not the file on disk. Formatting options sent by the editor, such as tab size, are ignored: the Rstack config is the single source of truth. Ignored, unsupported, and unparsable documents produce no edits rather than an error. The server loads a single config for the workspace root reported by the editor and does not discover nested configs per file; launch one server per config root when a project contains several. The config is loaded on the first formatting request and reused for the lifetime of the server; restart the server after changing it. Besides the global [`--config`](/guide/configuration.md#configuration-file) option, only [`--ignore-path`](#--ignore-path-path) affects the server. Relative values for both are resolved from the directory the server was launched in. Register `rs fmt --lsp` as a custom language server in any editor with LSP support to format on demand or on save. > `--lsp` cannot be combined with file arguments or with `--write`, `--check`, `--list-different`, or `--stdin-filepath`. ### `--no-cache` Disable the persistent formatting cache for the current invocation: ```bash rs fmt --no-cache ``` Without this option, `rs fmt` stores cache data in `.rstack/cache/fmt` under the Rstack configuration root. `--no-cache` prevents the command from reading, creating, or updating that cache. Stdin formatting never uses the persistent cache. See [Cache](/guide/formatting.md#cache) for cache behavior and cleanup guidance. ### `--cache-location ` Store the persistent cache in a custom directory: ```bash rs fmt --cache-location .cache/rs-fmt ``` Relative paths are resolved from the current working directory, while absolute paths are used as-is. The directory is created as needed and excluded from file discovery. Unlike the default cache location, a custom directory does not receive an automatic `.gitignore`; exclude it from version control or manage it through your CI cache configuration. When both options are provided, `--no-cache` takes precedence and the custom directory is not excluded from file discovery. ### `--no-error-on-unmatched-pattern` Exit successfully without diagnostics when no files match the provided paths or globs, including when all matching files are ignored: ```bash rs fmt --no-error-on-unmatched-pattern 'src/**/*.ts' ``` For example, a pre-commit script may always run `rs fmt`, even when the staged changes contain no supported files. This option lets the command exit successfully in that case instead of blocking the commit. > [`rs staged`](/guide/cli/staged.md) enables this behavior automatically for its `rs fmt` tasks. ### `--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 ``, for example when integrating with an editor. The path determines the parser and matching [configuration overrides](/guide/formatting.md#overrides), but it does not need to exist on disk: ```bash cat src/index.ts | rs fmt --stdin-filepath src/index.ts ``` Formatted output is written to stdout and diagnostics to stderr. If the input path is ignored, `rs fmt` skips formatting and writes the input unchanged. If it cannot infer a parser from the path or parse the content, it reports an error and exits with code `2`. > `--stdin-filepath` cannot be combined with file arguments or with `--write`, `--check`, or `--list-different`. ### `--with-node-modules` Process files inside `node_modules`, which `rs fmt` excludes by default: ```bash rs fmt --with-node-modules node_modules/example/index.js ``` This option only disables the built-in `node_modules` exclusion. Directory and glob scans still follow `.gitignore`, while `ignorePatterns` and `--ignore-path` continue to apply to every input. ### `--write` Write formatted files in place. This is the default mode, so specifying `--write` is optional: ```bash rs fmt src --write ``` The short option `-w` is an alias for `--write`: ```bash rs fmt -w src ``` `--write` cannot be combined with `--check` or `--list-different`.