Vim mode

Active contributors: ConradIrwin, dinocosta, probably-neb

Purpose

crates/vim (≈46k LOC) implements a modal-editing layer over the regular Editor. It supports normal/insert/visual modes, motions, operators, registers, marks, macros, ex commands, and many of the features power users expect from Vim. There is also a Helix-style mode under the same crate's switches (@kubkon is a reviewer for helix).

Crates

Crate	Role
crates/vim	The modal-editing implementation
crates/vim_mode_setting	Toggle + base-keymap interaction

Key abstractions

Type	File	Description
Vim	crates/vim/src/vim.rs	The mode-state extension on the editor
Mode	crates/vim/src/mode_indicator.rs	Normal / Insert / Visual / VisualLine / VisualBlock / Replace / Helix
Motion, Operator	crates/vim/src/motion.rs, operator.rs	Building blocks for vim commands
Ex command parsing	crates/vim/src/normal/...	Handles :w, :%s/foo/bar/g, :bd, etc.
Register store	crates/vim/src/state.rs (and similar)	Yank registers, marks, last search

How it works

The vim crate is not a fork of the editor; it is an entity that observes the editor and translates key sequences into editor operations. It hooks into the editor's keymap dispatch, intercepts events while a mode is active, and emits standard editor actions (Move, Delete, Yank, etc.). When in Insert mode, vim mostly steps aside and lets the regular editor keymap apply.

graph LR
    Key[Keystroke] --> Vim
    Vim -->|in Normal| Op[Operator+Motion]
    Op --> Ed[Editor actions]
    Vim -->|in Insert| Ed
    Vim -->|on : keystroke| ExLine[Ex command line]
    ExLine --> Vim
    Ed --> Buffer

Visual modes and selections

Visual / Visual-Line / Visual-Block reuse the editor's multi-selection machinery: a Visual-Block selection is just multiple cursors with a shared anchor column. Operators apply to whatever the current selection is, regardless of how it was made.

Macros and registers

Yanks land in the unnamed register by default; named registers ("a, "b, …) are stored on the Vim entity. Macros (q<reg> / @<reg>) record key sequences.

Helix mode

The same crate hosts a Helix-flavoured mode (selection-first, action-second) gated by setting. The mode-state machine knows the difference.

Integration points

• Above: the user's keymap. assets/keymaps/default-vim.json provides the canonical bindings.
• Below: crates/editor actions. Vim does not duplicate selection or motion logic; it composes editor primitives.

Entry points for modification

• New motion or operator — crates/vim/src/motion.rs / operator.rs.
• New ex command — crates/vim/src/normal/....
• New mode — crates/vim/src/state.rs plus dispatch.
• Keymap tweaks — assets/keymaps/default-vim.json (with deliberate care; tests in crates/vim/tests).

Related pages

• Editor