Commands
:formatformats the whole buffer.<space>ffformats the whole buffer in Normal mode and the selected range in Visual, Visual-Line, or Visual-Block mode.:format-lineand<space>flformat the current complete line. They require a formatter withrange_args; kvim reports an error instead of unexpectedly formatting the whole file.- In Visual, Visual-Line, or Visual-Block mode,
:formatformats the selected range when the formatter definesrange_args. Otherwise kvim formats the whole buffer and reports the fallback. :format-on-saveand<space>tftoggle format-on-save. The runtime choice persists inui_state.toml.
The file picker is bound to <space>sf. Formatting uses the <space>f namespace because key sequences are resolved without a timeout, so <space>f cannot simultaneously be an immediate action and the prefix of <space>fl.
Formatting is asynchronous. kvim discards results when the buffer changed while the formatter was running. A changed result is one undo step; a no-op result creates no undo entry.
Format-on-save is disabled by default:
[editor]
format_on_save = trueWhen enabled, saving waits for formatting. Formatter failure or a stale result blocks the write. kvim then verifies that the opened disk file has not changed before writing. :wq and Save & quit close their original window only after a successful current-revision write. If strip_trailing_whitespace_on_save = true, formatting and whitespace cleanup are applied as one undoable edit.
Built-in recipes
Recipes are enabled automatically when their executable is available:
| Filetypes | Ordered formatter list |
|---|---|
| Rust | rustfmt |
| TypeScript, TSX, JavaScript, JSON, YAML, Markdown, HTML, CSS, SCSS | prettier |
| C++ | clang-format |
| TOML | taplo |
| Python | ruff, then black |
| Bash | shfmt |
| CMake | cmake-format |
INI, PowerShell, and env files have no built-in formatter. Missing or unlaunchable executables fall through to the next configured formatter. Once a formatter launches, timeout, nonzero exit, invalid UTF-8, or oversized output is reported rather than falling through.
Custom formatters
Define a named formatter, then assign an ordered list to a filetype:
[formatters.dprint]
command = "dprint"
args = ["fmt", "--stdin", "{path}"]
timeout_ms = 10000
[format.typescript]
formatters = ["dprint", "prettier"]args are individual argv tokens. range_args, when present, replace args for visual formatting:
[formatters.prettier]
command = "prettier"
args = ["--stdin-filepath", "{path}"]
range_args = [
"--stdin-filepath", "{path}",
"--range-start", "{range_start_utf16}",
"--range-end", "{range_end_utf16}",
]
timeout_ms = 10000Supported placeholders:
{path},{language},{rust_edition}{range_start_byte},{range_end_byte},{range_length_byte}{range_start_utf16},{range_end_utf16}{range_start_line},{range_end_line}{range_start_column},{range_end_column}
Lines are zero-based. Columns count UTF-16 code units. The document-wide UTF-16 offsets match formatters such as Prettier. A placeholder that is unavailable for the request is an explicit error.
Structural indentation
Indentation is separate from external semantic formatting. With editor.auto_indent = true, Enter, o, and O derive indentation from the incremental tree-sitter tree for Rust, TypeScript, TSX, JavaScript, C++, JSON, CSS, and SCSS. Enter between syntax-confirmed {}, [], or () pairs expands the pair onto three lines, and typing a structural closing delimiter on a whitespace-only line aligns it with its opening depth. Delimiter-like text in strings and comments is ignored. Unsupported filetypes retain the existing indent-copying fallback.
Use == to reindent the current line, =motion for an operator range, and = in any Visual mode for the selected lines. Counts, text objects, gg=G, undo, and dot-repeat use the same operator machinery. Pasted text is not automatically reindented. Setting editor.auto_indent = false disables syntax-aware insertion and delimiter expansion; explicit = operations remain available.