The : command line

Press : in Normal mode to enter the command line. Type, edit with <Backspace>, press <Enter> to run, <Esc> to cancel.

Built-in ex commands

:set options

Boolean options accept the bare name to enable, no prefix to disable, or =on/=off/=true/=false/=1/=0.

! suffix forces (e.g. :q!, :w! — though :w! isn't currently distinguishable from :w).

Tab completion

Press <Tab> while typing a : command to complete.

File-path completion

When the cursor is past the first space, <Tab> completes filesystem paths:

• First <Tab> inserts the first matching entry (sorted alphabetically).
• Second <Tab> opens a popup listing every match with the first one highlighted.
• In the popup:
  • <Down> / <Up> / <Tab> — navigate selection (input updates live).
  • <Enter> — accept selection and run the command.
  • <Right> — accept selection, stay in command mode.
  • <Left> — close popup, discard completion state.
  • Any other typed key — close popup, resume normal cmdline editing starting from the current selection.
• Directory matches are completed with a trailing / so you can keep drilling in. Pressing <Tab> again on :vi src/ descends into src/ and lists its contents (instead of just re-showing src/).
• ~/ is expanded to $HOME for that segment.

Command-name completion

When the cursor is BEFORE the first space (still on the command name), <Tab> completes ex command names from the registry — including aliases:

:vspl<Tab>     → :vsplit          (only match)
:tab<Tab>      → :tab, then <Tab><Tab> opens popup with
                 tab, tabnew, tabe, tabedit, tabnext, tabn,
                 tabprev, tabp, tabprevious, tabN
:tabe<Tab>     → tabe, tabedit

Same popup UX as file completion.

How each command declares its argument completion

Every command's ExCommand::complete_arg returns an ArgCompletion value describing what Tab should resolve at a given positional slot. The variants:

• None — Tab is a no-op (zero-arg commands like :q, :bnext).
• Path — filesystem completion (:e, :w, :tabnew).
• Enum(&[…]) — fixed list (:config show <Tab> → json / toml).
• Dynamic(fn) — runtime-resolved list, for things like a future :colorscheme <Tab> that needs editor state.

The completion module dispatches through the registry, so adding a new ex command with custom completion is a single-file change: add the struct, override complete_arg, register it. Existing examples worth copying from:

:config <Tab>      → conv | convert | load | path | show
:config sh<Tab>    → show
:config show <Tab> → json | toml
:config load <Tab> → filesystem paths
:tab <Tab>         → close | new | next | prev
:tab new <Tab>     → filesystem paths

When does completion NOT trigger?

• The partial input matches no entries → <Tab> is a no-op (no popup, no insertion).
• Typing any character clears the active completion cycle.

Search line (/ and ?)

The pattern is a full Rust regex crate regex. The last pattern is remembered for n / N in normal mode.

Substitution (:s)

:[range]s/pattern/replacement/[flags]

Regex search-and-replace, using the same Rust regex syntax as the / search line above.

Ranges (the [range] prefix):

Flags (after the closing /):

• g — replace every match on each line, not just the first.
• i — case-insensitive match.

Replacement understands vim-style back-references: \1…\9 insert capture groups and & inserts the whole match. A literal $ is inserted verbatim. An empty pattern (:%s//new/) reuses the last search pattern.

:%s/foo/bar/g          replace every "foo" with "bar", whole buffer
:s/\s\+$//             strip trailing whitespace on the current line
:2,10s/old/new/        only lines 2–10, first match per line
:%s/(\w+)=(\w+)/\2=\1/ swap around the "=" using capture groups
:%s/cat/[&]/g          wrap every "cat" in brackets → "[cat]"

Substituting over a visual selection

Press : while a visual selection is active and the command line opens prefilled with '<,'> — exactly like vim. Just append the substitution:

V  j  j        select three lines
:              command line shows  :'<,'>
s/old/new/g    →  :'<,'>s/old/new/g
<Enter>        applies only to those lines

The '< / '> line range is captured the moment you press :, so it holds even though entering the command line clears the on-screen highlight.

Custom commands

The ExCommand trait is the extension point. Implement it, register the result via editor.commands.register(Arc::new(...)) in your build, and it becomes available at runtime. See extending.md for the trait shape and an example.

Plugin-style external commands aren't supported in v1 — there's no scripting runtime — but the registry pattern means adding the plumbing later is purely additive.