Command-Line Reference¶
Usage¶
slang-format [options] [<file-or-dir> ...]
If no files are specified or the sole input is -, slang-format reads from stdin
and writes to stdout.
Stdin cannot be combined with other inputs or -i.
If files are specified without -i, it prints formatted output to stdout.
With -i, it modifies files in place. Multiple files require -i, --dry-run, or --check.
Directory inputs recursively collect .sv, .svh, .v, and .vh files. Each directory
argument's config controls excludeDirectoryNames (directory names) and
projectPaths (files or subtrees when targeting the project root containing
.slang/). Each collected file resolves its own formatting config.
See validation for checks, rejected files, and exit statuses, and disabling formatting for preserving source formatting.
Options¶
-h, --help¶
Display a help message and exit.
--version¶
Display version information and exit.
-i, --inplace¶
Edit files in place. This option cannot be used with stdin. Unchanged files retain their contents and timestamps. Changed files are written completely to a temporary file in the destination directory, then renamed over the destination. A failed write leaves the original in place. Symlinks remain symlinks and their targets are updated; permission bits are preserved. Replacement creates a new file, so other hard links retain the old contents, and ownership and extended metadata are not copied. The destination directory must be writable. Read-only files are rejected when changes are needed.
Batch summaries count each file once: formatted, unchanged, excluded, skipped, or
failed. --dry-run counts actual changes as "would format". Skipped files retain
their original contents; the summary distinguishes depth limits, input parse errors, and output
validation failures. When multiple reasons occur in a batch, the reason counts show how many
skipped files had each problem; a file can have multiple reasons. Files are counted
as failed when operations abort or config, read, or write errors occur.
Forced output counts as formatted or unchanged when the operation completes, even when input or output checks fail. Diagnostics and exit status still report those failures. Strict/check modes can also return status 1 for skipped files without counting them again as failed.
-f, --force¶
Use the formatter's output despite validation failures, including Git merge
conflict markers. Diagnostics are still printed to stderr, and the command exits
with status 1 when validation fails. See validation.
Depth-limit skips always preserve the input, including with --force.
--force overrides validation, while --dry-run still suppresses writes and
explicit formatting markers remain respected.
-n, --dry-run¶
Run formatting and validation without writing to source files or emitting source on stdout.
This mode uses the same verbosity as a normal run: diagnostics and a batch summary, with
per-file progress and timing only when --verbose is enabled. The summary says
"would format" for files that would change. Differences alone return status 0.
It can be used with multiple files and combined with --force to check forced formatting.
--check, --verify¶
Check that files are already formatted and pass validation. Return 0 on success or
1 if any file needs formatting, fails validation, or cannot be processed.
This mode reports <path>: needs formatting on stderr for each file that would change.
It supports stdin, multiple files, and directories. It never writes to source files or emits source
on stdout, including with -i or --force. An explicit --stats-csv report is still written. Generated files and explicitly disabled
formatting regions are respected. Batch results do not depend on file order.
--Werror¶
Treat diagnostic warnings as failures. With --dry-run, also fail when formatting
would change a file and report each such file on stderr. --dry-run --Werror is the stricter, clang-format-compatible
check spelling; unlike --check, it also fails on unmatched on warnings.
Without --dry-run, this changes exit status without suppressing normal output.
--strict, --fail-on-incomplete-format¶
Return status 1 on every validation failure, including structural parse failures,
CST mismatches, and non-idempotent output. When these failures occur, the formatter
normally preserves the input and returns 0. Output handling is unchanged:
rejected candidates remain unapplied unless
--force is also given. Formatting differences and unmatched on warnings alone
are not failures. This is validation of formatting safety, not compilation.
--failsafe_success defaults to true; setting it to true cannot override
--strict, --check, or --Werror.
--config <path>¶
Path to a JSON config file. Without --config or --config-json, slang-format searches upward from each file independently, then from the current directory, for .slang/format.json. An explicit config applies to every file. Nested configs replace parent configs; missing settings use defaults. Unknown keys are errors, including nested keys.
See Configuration for config file options.
--config-json <json>¶
Supply a JSON config directly on the command line:
slang-format --config-json '{"columnLimit":80,"indentWidth":2}' -i file.sv
The config applies to every input, including stdin, and overrides automatic config
discovery. Omitted settings use built-in defaults. It cannot be combined with
--config. Use --dump-config to inspect the resolved settings.
Unknown keys (including nested keys), invalid value types, and malformed JSON
produce an error on stderr and exit status 1 before any files are formatted or
written. For example, {"indentWidht":2} reports
Unknown configuration key 'indentWidht'. The same diagnostic is used for config
files; nested errors also identify the containing field.
As with --config, excludeDirectoryNames controls directory collection and
projectPaths is ignored because no discovered project root is associated with
an explicit config.
--assume-filename <path>, --stdin_name <path>¶
Give stdin a filename for config discovery and diagnostic locations. The file need
not exist, so unsaved editor buffers work. Relative paths resolve against the
current directory. The formatter searches for .slang/format.json from the filename's parent,
then falls back to the current directory. --config or --config-json takes precedence.
This option is ignored for actual file inputs. Without it, stdin uses the current
directory's config, and diagnostics identify <stdin>.
slang-format --assume-filename rtl/top.sv - < editor-buffer.sv
--dump-config¶
Print the configuration for the first target (or stdin's assumed filename) as JSON and exit. Useful for inspecting defaults or verifying which config file is being picked up.
--stage <layout|aligned>¶
Select the last formatter pass to run. layout performs normalization, spacing, and line breaking without cross-row column alignment. aligned (the default) also runs the alignment pass. Both stages run CST validation and idempotency checks independently.
-j, --jobs <n>¶
Number of parallel formatting jobs. Defaults to the number of CPU cores. Used for file batches, including checks and dry runs.
-v, --verbose¶
Report formatting <path> ... when a worker starts reading and formatting a file,
then finished <path> (12.345 ms) after its result has been handled. Starts without matching
finishes identify outstanding work when investigating a stall. finished also
appears for rejected or failed files; diagnostics and the summary report failures.
Formatting runs in parallel using --jobs (or the default CPU count). Workers
queue progress events; only the main thread prints progress and diagnostics and
applies results. Events are reported as they arrive, so a stalled worker does not
hold up reports from other workers. Output order can vary between runs. Use -j1
to isolate one active file at a time. Single-file and stdin modes also report progress.
Elapsed time measures wall-clock milliseconds spent reading, formatting, and
validating that input, including blocked reads. It excludes config discovery,
time spent waiting in the worker queue, result reporting, and output writes. For stdin, it includes
waiting for input/EOF. Timings use a monotonic clock.
--stats-csv <path>¶
Write per-file timing and outcomes to a CSV file, independently of --verbose.
This option works for files, directory batches, stdin, both formatter stages, checks, and dry
runs. An explicitly requested report is written even when source writes are disabled
by --check or --dry-run. Source stdout remains unchanged.
The report has these columns:
| Column | Meaning |
|---|---|
path |
Input filename, or <stdin> / --assume-filename for stdin. |
elapsed_ms |
Wall-clock time spent reading, formatting, and validating, in milliseconds, with three decimal places; the same measurement as verbose output. |
input_bytes |
Number of source bytes read, or zero when input was not read. |
status |
changed, unchanged, excluded, skipped, or error. |
validation_failed |
true if an input check or output validation failed; otherwise false. |
changed means output changed, or would change in a check/dry run. excluded
identifies generated files; unchanged disabled regions are unchanged. skipped
means an input check or output validation kept the original. error covers aborts and file/config/write
failures. Forced failed output can be changed with validation_failed=true.
These fields describe outcomes, not the command's exit status: strictness and
checking flags still control that status.
An existing report is overwritten. Rows are written and flushed by the main thread as results are handled, in completion order, so finished rows remain available if another worker stalls. An interrupted operation has no row. An empty batch writes only the header. Errors before input processing, such as invalid arguments or a missing input path, can prevent report creation entirely.
Paths are CSV-quoted with embedded quotes doubled. The report cannot overwrite an
input or loaded configuration, including aliases through symlinks or hard links.
- is rejected as a report path. Failure to open the report stops formatting;
a later report write failure makes the command exit 1 while processing continues.
slang-format -v -j8 --dry-run --stats-csv timings.csv rtl/
Examples¶
# Format a file and print it to stdout
slang-format top.sv
# Format in place
slang-format -i top.sv
# Format multiple files in place with 8 threads
slang-format -i -j 8 src/**/*.sv
# Pipe from stdin
cat top.sv | slang-format
# Check current config
slang-format --dump-config
# Use a specific config file
slang-format --config path/to/format.json top.sv
# Force output despite validation warnings
slang-format -f top.sv
# Inspect independently testable pre-alignment output
slang-format --stage layout top.sv
# CI: fail if any file needs formatting or cannot be validated
slang-format --check rtl/