External formatting

kvim runs external formatters directly, without a shell. Formatter input and output use stdin/stdout; commands never receive a temporary file.

Kvim home

Commands

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 = true

When 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 = 10000

Supported placeholders:

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.