fmt
The rs fmt command formats files or checks whether they are formatted. For detailed usage, see Formatting.
Usage
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 for path resolution and ignore rules.
Examples:
rs format is an alias for rs fmt:
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:
--check cannot be combined with --write or --list-different.
The command uses the following exit codes:
-h, --help
Display usage and options:
--ignore-path <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:
If config/format.ignore contains this rule:
The generated/** rule is relative to config/, where the ignore file is located. It excludes config/generated/**, not 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:
Each file acts as a separate ignore source. See 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:
The short option -u is an alias for --ignore-unknown.
This option does not suppress errors for unmatched paths or globs. Combine it with --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:
The short option -l is an alias for --list-different:
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 on stdio:
The server supports document formatting only and works on the editor's buffer. Formatting rules come from the Rstack config; editor options such as tab size are ignored. Ignored, unsupported, and unparsable documents produce no formatting edits.
The server uses the config at the workspace root reported by the editor and does not discover nested configs for individual files. If a project has multiple configs, launch a server for each config root. The server reuses the loaded config, so restart it after changing the config.
Besides the global --config option, only --ignore-path affects the server's formatting behavior. Relative paths for both are resolved from the directory where the server was launched.
Register rs fmt --lsp as a custom language server in any editor with LSP support to format on demand or on save.
--lspcannot 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:
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 for cache behavior and cleanup guidance.
--cache-location <path>
Store the persistent cache in a custom directory:
Relative paths are resolved from the current working directory. The custom cache directory is excluded from formatting and does not receive an automatic .gitignore. Add the directory to .gitignore if you do not want to commit the cache to Git.
If you also pass --no-cache, --cache-location is ignored and the directory follows the normal file discovery rules.
--clear-cache
Clear the formatting cache and exit without formatting or checking files:
The command removes only the cache file, preserving the directory and other files. The default cache location is .rstack/cache/fmt under the Rstack configuration root. Use --cache-location to specify a custom cache directory:
--clear-cache only clears the cache; it does not accept file arguments or other mode options.
--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:
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 stagedenables this behavior automatically for itsrs fmttasks.
--parallel-workers <count>
Set the maximum number of formatting workers to a positive integer:
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 <path>
Format content received from stdin as if it were saved at <path>, for example when integrating with an editor. The path determines the parser and matching configuration overrides, but it does not need to exist on disk:
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-filepathcannot 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:
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:
The short option -w is an alias for --write:
--write cannot be combined with --check or --list-different.