Autocommand events

These are the events the bemtvi editor currently emits. Register a handler for one with btv.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. bemtvi 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.

Hot-path events are synchronous

Events fall into two classes, and it decides whether your handler may be async.

Hot-path events fire while the editor converges a single input tick — that is, on nearly every keypress:

CursorMoved   CursorMovedI   TextChanged   TextChangedI   ModeChanged
InsertEnter   InsertLeave    BufEnter      BufLeave
WinEnter      WinLeave       WinScrolled   WinResized

Their handlers must be synchronous. Returning a promise from one raises, naming the event and the file:line you registered it at. The editor will never wait for it, so returning one means expecting an ordering that cannot happen.

This is not a ban on async work — only on handing back the promise. Start it and return nothing:

-- WRONG: raises. Nothing awaits this.
btv.autocmd.create("CursorMoved", { callback = function()
  return btv.lsp.buf.hover()
end })

-- Right: fire-and-forget, or defer with btv.schedule / btv.on_next_tick.
btv.autocmd.create("CursorMoved", { callback = function()
  btv.lsp.buf.hover()
end })

Every other event is async-capable: a callback may return a promise (btv.promise, or the result of an btv.* async call). A returned promise is never dropped — a rejection surfaces like any unhandled btv.promise rejection, named for the event that raised it.

The split exists so the machinery below never touches the per-keypress path.

What happens when a handler is async

Two guarantees, both reproducing for async what vim gets for free by being synchronous.

Late subscribers still get the event. If a handler registers another handler for the same event while the first is still running, the newcomer receives that event too. This is what makes a lazily-loaded plugin work: FileType wakes the plugin, the plugin’s config runs (possibly btv.await-ing), it registers its own FileType handler — and that handler still fires for the buffer that woke it. Nothing fires twice: delivery is filtered by registration order, not replayed wholesale.

Plugins loading late still get the startup file’s events. This is the same guarantee widened to the plugin-load boundary — see Plugins and the startup file.

The read sequence is ordered. BufReadPost → FileType → BufEnter → BufWinEnter advances one stage at a time, each waiting for the previous stage’s async handlers to finish. So a BufReadPost handler that detects the filetype asynchronously is reflected in the FileType that follows — you get one correct FileType, not a wrong one followed by a correction. This is vim’s order, and an async handler does not reorder it: BufEnter and BufWinEnter stay behind the read, however long it takes. BufWritePre (the write waits — see Writing) and QuitPre / ExitPre / VimLeavePre (the exit waits — see Quitting & exit) are awaited the same way.

Handlers have a time budget: 500 ms by default. It bounds how long the editor waits, never whether anything gets delivered — when it expires, the sequence advances and late subscribers are still served, so one slow handler cannot wedge a buffer half-initialised. Blowing it warns, naming the handler’s file:line; finishing late warns again with the elapsed time. Raise it for a handler you know is slow:

btv.autocmd.create("FileType", { timeout = 5000, callback = function() … end })

A handler that never settles at all never reports completion, so it stays listed in btv.autocmd.pending() — inspect with :lua print(vim.inspect(btv.autocmd.pending())). Warnings go to :messages.

Buffer lifecycle

Ordering on opening a file is BufAdd → BufReadPost (or BufNewFile for a new path) → FileType → BufEnter → BufWinEnter, with BufLeave for the buffer being left ahead of the whole sequence; an async handler does not reorder it — see What happens when a handler is async. Re-reading the current buffer (:e!) fires the same sequence minus the BufLeave and the BufAdd (the bufnr is neither left nor new).

Plugins and the startup file

Plugins load asynchronously. btv.plugins awaits a spec’s directory before sourcing it, and a spec’s config may btv.await on its own — so a plugin’s config, and every autocmd that config registers, lands several ticks into startup. The file you named on the command line has already been read by then. Painting before the plugins are up is deliberate: it is what makes bemtvi file.txt open instantly.

You do not have to work around it. Every first-announce event fired before the plugins were ready is replayed to the handlers that registered while they were loading, when PluginsLoaded fires:

BufReadPost   -> the handlers that exist now (your init.lua's, the built-in
FileType         treesitter / LSP attach) — so the file colours immediately
BufEnter
VimEnter
  <plugin configs run, registering their own BufReadPost / FileType handlers>
PluginsLoaded -> BufReadPost / FileType replayed to exactly those handlers

So a plugin registers a plain BufReadPost handler and sees the startup file, with the buffer and the match it was read with. There is no separate event to hook and no sweep of btv.buf.list() to write. Restored session windows are covered the same way.

Three things worth knowing:

• Nothing fires twice. Delivery is filtered by registration order, the same watermark the async replay above uses. A handler registered before the read — one from your init.lua — receives it on the read and is never replayed to.
• Only BufReadPost, BufNewFile and FileType are replayed. They fire once per read and carry no pairing semantics, so re-delivering one is unambiguous. BufEnter and BufWinEnter are not: they mean “became current” / “a window displayed it”, which may no longer be true by the time the plugins land, and a BufEnter replayed without its BufLeave twin would misreport editor state.
• The window is a startup one. It closes at PluginsLoaded and never reopens, so a handler registered later — by a lazy plugin, or by you at the : prompt — gets the reads that follow it and nothing from before.

Writing

Window & tab

Mode

Editing & cursor

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

Mouse

LSP

Treesitter

Files & environment

Startup

Quitting & exit

Fired when the editor is really leaving — a committed :qa / last-window :q / :wq / :x / :wqa (! skips only the modified-buffer E37 guard, not these events). The three *Pre events are awaited: a handler may return a promise and the exit waits for every handler to settle before advancing, so an async flush/cleanup runs before the process leaves. They fire in order.

A handler cannot cancel the quit (these events are advisory, as in neovim), and a handler whose promise rejects does not block the exit — a failing cleanup still lets the editor leave.

Plugins

Fired by the built-in plugin manager (btv.plugins). See Writing bemtvi plugins.

To hook one named plugin, prefer btv.plugins.on_loaded(name, fn) over subscribing to PluginLoaded yourself. The event only reports a load that happens later, so the raw subscription silently never runs if that plugin turns out to be eager and already loaded; on_loaded runs fn immediately in that case and waits otherwise, so it fires exactly once either way:

btv.plugins.on_loaded("bemtvi-lspconfig", function()
  require("bemtvi-lspconfig").setup()
end)

User

User is the freeform event namespace: any plugin (or bemtvi itself) fires one with btv.autocmd.exec("User", { pattern = "MyEvent", data = … }), and a handler subscribes by pattern. bemtvi fires User DaemonStatusChanged whenever a daemon session’s connection phase changes (read the phase with btv.daemon.status()).

Event aliases

A handful of neovim event names are aliases for another event. bemtvi honors these by canonicalizing the alias to its real event at registration — so a config that does btv.autocmd.create("BufRead", …) (muscle memory from neovim) behaves exactly as if it had used "BufReadPost", and the callback’s event field reports the canonical name. Aliases are accepted anywhere an event name is (create, exec, get, clear).

Every alias’s target event is one bemtvi actually emits — registering on an alias whose target never fired would be a silent no-op, so we don’t add one until the target exists.