Opening and creating files

Passing a path to kvim opens an existing UTF-8 regular file. When only the final path component is missing and its parent directory exists, kvim opens an empty buffer bound to that validated path. The file is not created until a successful :w; parent directories are never created automatically.

Kvim home

:new opens an unnamed empty buffer in a new horizontal split and focuses that split. :new <path> uses the same existing-or-missing behavior as a command-line path. An unnamed buffer has no save target, while a named missing buffer is created by :w.

If another process creates a named missing file before its first write, kvim treats that as an external change and requires conflict resolution rather than silently overwriting it.

Following automatically reloaded files

Starting with 0.25.0, when a clean file changes outside Kvim, automatic reloads follow its new end only in views whose cursor was at the old end immediately before the reload is applied. Other splits keep their existing position, clamped if the file shrank. Being somewhere on the last line is not enough: Normal mode must be on its final character (or the final empty line after a newline), and Insert mode must be at the end-of-file insertion point.

Following moves the cursor to the new end and scrolls it into view, including wrapped lines and long unwrapped lines. Diff panes retain their linked vertical scrolling, controlled by the focused comparison pane. Moving the cursor away while the reload is pending prevents following. Manual reloads, confirmed conflict resolution, and Git discard keep their existing position-preserving behavior. Unsaved changes still require conflict resolution; failed or stale reads do not trigger following.

Successful automatic reloads show a temporary bottom-right notice above the status bar, using the workspace-relative path when possible. Notices expire after four seconds even if more changes arrive. Repeated reloads are combined, with a four-second quiet period between notice batches to avoid continuous popups while following a log. Dialogs and interactive popups take precedence. Reload failures and conflict confirmations keep their existing persistent feedback; manual reload and save messages still use the status line.

Command-line startup

kvim
kvim <path>
kvim -- <path>
kvim --version
kvim --goto <line> [--] <file>
kvim --diff [--] <left> <right>
kvim --review
kvim --review -- <directory>

With no path, kvim opens Explorer at the launch directory and may restore a matching workspace. A directory path opens Explorer there. An explicit file takes precedence over saved workspace sessions and normally restores that file's saved cursor position.

Starting with 0.18.0, --goto opens one file at a positive, 1-based decimal source line, overriding its saved cursor position for this launch:

kvim --goto 42 -- src\main.rs
kvim --goto 7 -- "C:\work tree\project\notes.txt"

The cursor lands on the line's first non-blank column using existing Normal-mode navigation. All-blank lines retain Normal-mode's last-column behavior. Beyond-EOF destinations clamp to the final source line, including an empty line after a trailing newline; empty or named-missing buffers use their only line. The destination is visible in the first frame, even with wrapping or rendered Markdown enabled. Positions continue to be saved normally on exit.

--goto must precede the single file operand and cannot target a directory. Line numbers must fit the platform's usize; zero, signs, whitespace, fractions, non-decimal values, and overflow are errors. There is no column, +line, or file:line syntax: file arguments are literal paths.

Use -- to end option parsing, especially for paths beginning with a dash (for example, kvim -- --goto opens a file named --goto). External callers should pass separate process arguments, such as ["--goto", "42", "--", "<absolute file path>"], rather than build a shell command string. The argument contract is the same on Windows, Linux, and macOS; the editor remains a foreground process until the user quits.

Invalid arguments, missing operands, repeated options, mixed --version/editing requests, and directory destinations print a diagnostic and usage to stderr and exit with status 2, before loading configuration/state or acquiring the terminal. File-open failures retain status 1. Extra arguments that older versions silently ignored are now errors; except for --diff, only one startup path is supported. Older kvim versions do not understand --goto or --; integrations targeting them must explicitly use a legacy file-only invocation, without positioning.

Editable two-file comparison

Starting with 0.19.0, open two files side by side with:

kvim --diff before.txt after.txt
kvim --diff -- "C:\before\config.toml" "C:\after\config.toml"

The first operand is the left pane; the second is the right pane. Both are ordinary editable buffers, with syntax coloring, independent cursors and undo histories, completion, and existing save/external-change protection. No Git repository is needed. The comparison uses current in-memory contents, including unsaved edits, and updates shortly after editing pauses.

Changed lines are tinted. Blank visual filler rows align insertions and deletions; these rows are never inserted into either buffer. Vertical scrolling is linked, while horizontal scrolling and cursors remain independent. The comparison uses unwrapped source text: Markdown rendering and inlay hints are suppressed only in its two panes, without changing saved settings.

Sign columns are hidden by default in diff panes, leaving more space for text. Line numbers and ordinary editor panes are unchanged. To show diff/Git, diagnostic, and debug sign columns in diff panes, set:

[editor]
diff_sign_columns = true

With sign columns enabled, changed lines are marked - on the left and + on the right, and filler rows are marked ~.

The cursor moves to the first change when the initial comparison is ready. Use ]c and [c for the next and previous change; counts are supported. Navigation stops at the first/last change rather than wrapping. Normal editing, page motions, H/M/L, zz, mouse positioning, and scrollbars use the aligned view. Clicking filler selects that change and maps editing to the adjacent source boundary.

Each transfer is one undoable destination edit. It never writes a file; use :w in the destination pane to save. Transfers are rejected while comparison results are stale or when the cursor is not on a change. The configurable action names are next_diff_change, previous_diff_change, diff_get, and diff_put.

Whitespace and final-newline differences count as changes. LF versus CRLF is reported in each pane's header rather than marking every line changed. Transfers use the destination's line-ending convention without merging standalone-CR source lines. An identical header therefore means identical line contents and final-newline presence, not necessarily byte-for-byte identical line endings.

A missing final filename opens as an empty named buffer when its parent exists; it is created only on a successful save. Directories, invalid UTF-8, and other file-open errors are reported normally. Paths referring to the same underlying file share one buffer rather than creating competing writable copies. Use -- for literal paths starting with a dash. --diff requires exactly two operands and cannot be combined with --goto or --version.

The comparison starts independently of saved workspace layouts and does not overwrite a managed workspace profile on exit. Closing a participant or opening another buffer in it ends the comparison, restoring normal presentation in the remaining panes. Existing unsaved-change protections still apply.

Use <space>ac to send the current change or selected source range to an existing Copilot CLI conversation. The explicit commands :copilot send hunk, :copilot send line, and :copilot send selection choose the context scope. Diff snapshots include both sides' identities and coordinates; they do not save either buffer. See Copilot. Remote PR review has its own Review workspace.

Comparison is bounded to 4 MiB and 50,000 source lines per file. Errors and exceeded limits appear in the pane headers; files remain editable even when comparison is unavailable. Work runs off the editor loop, and outdated results cannot authorize a transfer.

Line endings

Kvim detects LF or CRLF line endings when opening a file and shows the active convention in the status bar. Use :eol to report it, :eol lf to normalize the buffer to LF, or :eol crlf to normalize it to CRLF. <space>te toggles between LF and CRLF.

Conversion updates existing LF and CRLF terminators as one undoable buffer change, preserves standalone carriage returns, and controls line endings inserted afterward. It does not write automatically; use :w to persist the change.

Syntax coloring

Use :syntax <language> to select the Tree-sitter syntax for the current buffer. Language names are the same stable keys used by language-server configuration, including rust, typescript, tsx, javascript, cpp, markdown, toml, json, yaml, and python. Command completion lists every supported value. Files ending in .http are detected as HTTP request files automatically and can also be selected explicitly with :syntax http. Files named .gitignore are detected as Gitignore files automatically; use :syntax gitignore to apply the same coloring to another ignore-pattern file. Files named .gitattributes use their dedicated Git attributes grammar; use :syntax gitattributes to apply it explicitly.

The selection is remembered by the file's complete basename, including its extension but not its directory. For example, setting :syntax yaml in one compose.conf applies to every subsequently opened file named compose.conf. Other files in the same directory are unaffected.

:syntax reports the active selection. :syntax text disables syntax coloring for that filename, and :syntax auto removes the remembered choice and restores normal exact-filename and extension detection. These choices control syntax parsing, highlighting, and syntax-derived presentation; they do not change language-server or formatter selection.