Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Autocommand events

These are the events the nxvim editor currently emits. Register a handler for one with nx.autocmd.create (or vim.api.nvim_create_autocmd). The event name is matched exactly, and a handler’s callback receives the event table { id, event, match, buf, file, data }.

The list is the emitted set, not all of vim’s events. nxvim fires events as features come to need them. A handler registered for an event that isn’t emitted yet (e.g. OptionSet) is accepted but simply never fires — it does not error. If you need one that’s missing, it’s a feature gap, not a config mistake.

Patterns support shell globs: a pattern such as "*.rs" (no /) matches a file event by the path tail, one containing a / matches the whole path, and "*" (or an omitted pattern) matches everything. A pattern with no glob metacharacter is an exact compare — so a FileType rust autocmd never glob-matches a path.

Buffer lifecycle

EventWhen it firesNotes
BufReadPostA file-backed buffer is first shown after reading an existing file from disk.Fires once per buffer (gated by the “announced” set). buf / file set.
BufNewFileA buffer is opened for a path with no file on disk — fires instead of BufReadPost.buf / file set.
FileTypeA buffer is first announced and whenever its filetype changes.match is the filetype (e.g. "rust"); file is the path. Where ftplugins and vim.lsp.enable attach.
BufEnter / BufLeaveA buffer becomes / stops being the current one (including plain switches with no read).buf / file set.
BufDeleteJust before a buffer is deleted (:bdelete), while its state still exists.buf / file set.

Ordering on opening a file is BufReadPost (or BufNewFile for a new path) → FileTypeBufEnter.

Writing

EventWhen it firesNotes
BufWritePreBefore a buffer is written to disk (:w, :wall, and finalized off-tick saves).match / file is the path; glob-matchable, e.g. a *.rs format-on-save hook.
BufWriteSame point as BufWritePre — the bare-name spelling.
BufWritePostAfter a successful write.The hook format-on-save and “reload affected tools” plugins use.

Window & tab

EventWhen it fires
WinNewA new window is created.
WinEnter / WinLeaveFocus moves to / away from a window.
WinClosedA window is closed.
WinResizedA window’s rectangle changes (split/resize/layout change).
WinScrolledA window’s viewport scrolls — topline (vertical) or leftcol (horizontal) changes. match is the scrolled window’s id; fires per-window. Gated on a registered handler (high-frequency), so it costs nothing when nothing listens.
TabNewA new tab page is created.
TabEnter / TabLeaveThe active tab changes.
TabClosedA tab page is closed.

Mode

EventWhen it fires
InsertEnter / InsertLeaveThe editor enters / leaves Insert (or Replace) mode.
ModeChangedThe reported mode() code changes. match is the transition old:new (e.g. "n:i", "v:n"); a handler’s pattern glob-matches it ("*:i", "n:*", "*:*"). A Normal↔MultiCursor swap fires "n:m" / "m:n" (MultiCursor reports its own "m"). Gated on a registered handler.

Editing & cursor

These fire at high frequency, so they are gated on a registered handler — when no autocmd listens for them they cost nothing.

EventWhen it fires
TextChangedThe buffer’s text changes in Normal mode (edit, paste, …).
TextChangedIThe buffer’s text changes in Insert mode (per keystroke).
CursorMovedThe cursor moves in Normal mode.
CursorMovedIThe cursor moves in Insert mode.

LSP

EventWhen it firesNotes
LspAttachA language server attaches to a buffer.data = { client_id = … }.
LspDetachA language server detaches from a buffer.data = { client_id = … }.

Files & environment

EventWhen it firesNotes
FileChangedShellA loaded file changed on disk (the watch/checktime reconcile).A handler may set vim.v.fcs_choice to "reload" / "edit" / "ask".
FileChangedShellPostAfter the file-change reconcile completes.
DirChangedThe working directory changes (:cd / :lcd / :tcd).file is the new cwd; match is the scope.
ColorSchemeA colorscheme finishes loading.match is the colorscheme name. This is what colorscheme plugins hook.

Startup

EventWhen it firesNotes
VimEnterOnce, after the editor has finished starting (config sourced, first frame imminent).vim.v.vim_did_enter is 1 from this point on. The built-in plugin manager’s first-run prompt hooks it.