Customizing Neovim - Auto-commands & Events

BufAdd

Fires:

After adding a new buffer to the buffer list (except during startup)
After adding an existing buffer to the buffer list (except during startup)
When renaming a listed buffer

Fires Before:

BufEnter

See Also:

VimEnter

BufDelete

Fires:

Before deleting a buffer from the buffer list.
Just before a buffer in the buffer list is renamed.

Notes:

BufUnload may be called first (if the buffer was loaded).

BufEnter

Fires:

After entering (visiting, switching-to) a new or existing buffer.

Notes:

Useful for setting filetype options. Compare BufNew which does not trigger for existing buffers.

Fires After:

BufAdd BufNew BufReadPost

BufFilePost

Fires:

After changing the name of the current buffer with :file or :saveas.

BufFilePre

Fires:

Before changing the name of the current buffer with :file or :saveas.

BufHidden

Fires:

Before a buffer becomes hidden, when there are no longer windows that show the buffer, but the buffer is not unloaded or deleted.

Notes:

Not used for :qa or :q when exiting Neovim.

BufLeave

Fires:

Before leaving to another buffer.
When leaving or closing the current window and the new current window is not for the same buffer.

Notes:

Not used for :qa or :q when exiting Neovim.

BufModifiedSet

Fires:

After the 'modified' value of a buffer has been changed.

BufNew

Fires:

After creating a new buffer (except during startup, see VimEnter)
When renaming an existing buffer.

Notes:

Unlike BufEnter, visiting (switching to) an existing buffer will not trigger this again.

See Also:

BufAdd BufNewFile

BufNewFile

Fires:

When starting to edit a file that doesn't exist.

Notes:

Can be used to read in a skeleton file.

BufRead

Fires:

When starting to edit a new buffer, after reading the file into the buffer, before processing modelines.
When writing an unnamed buffer in a way that the buffer gets a name
After successfully recovering a file for the "filetypedetect" group when executing ":filetype detect".

Notes:

Not triggered for the :read file command when the file doesn't exist See BufWinEnter to do something after processing modelines.

See Also:

BufWinEnter

BufReadCmd

Fires:

Before starting to edit a new buffer.

Notes:

Should read the file into the buffer.

BufReadPost

Notes:

Same as BufRead

BufReadPre

Fires:

When starting to edit a new buffer, before reading the file into the buffer.

Notes:

Not fired if the file doesn't exist.

BufUnload

Fires:

Before unloading a buffer, when the text in the buffer is going to be freed.

Notes:

Triggers for all loaded buffers when Neovim is going to exit.

Fires Before:

BufDelete

Fires After:

BufWritePost

BufWinEnter

Fires:

After a buffer is displayed in a window.
When executing :split with the name of the current buffer, since it reloads that buffer.

Notes:

This may be when the buffer is loaded (after processing modelines) or when a hidden buffer is displayed (and is no longer hidden). Not triggered for :split without arguments, since the buffer does not change, or :split with a file already open in a window.

BufWinLeave

Fires:

Before a buffer is removed from a window.
When exiting.

Notes:

Not fired when a buffer is still visible in another window.

Fires Before:

BufHidden BufUnload

BufWipeout

Fires:

Before completely deleting a buffer.
Just before a buffer is renamed (also when it's not in the buffer list).

Notes:

The BufUnload and BufDelete events may be called first (if the buffer was loaded and was in the buffer list).

BufWrite

Fires:

Before writing the whole buffer to a file.

BufWriteCmd

Fires:

Before writing the whole buffer to a file.

Notes:

Should do the writing of the file and reset 'modified' if successful, unless '+' is in 'cpo' and writing to another file cpo-+. The buffer contents should not be changed. When the command resets 'modified' the undo information is adjusted to mark older undo states as 'modified', like :write does.

BufWritePost

Fires:

After writing the whole buffer to a file (should undo the commands for BufWritePre).

BufWritePre

Notes:

Same as BufWrite

ChanInfo

Fires:

When the state of channel changed, for instance the client of a RPC channel described itself.

Notes:

See nvim_get_chan_info() for the format of the info Dictionary.

ChanOpen

Fires:

Just after a channel opens.

Notes:

See nvim_get_chan_info() for the format of the info Dictionary.

CmdUndefined

Fires:

When an undefined user-command is called.

Notes:

Useful for defining a command only when it's used. The pattern is matched against the command name. Both <amatch> and <afile> expand to the command name. Note that Autocompletion won't work until the command is defined. An alternative is to always define the user-command and have it invoke an autoloaded function.

CmdlineChanged

Fires:

After a change was made to the text inside the command-line.

Notes:

Be careful not to mess up the command-line, it may cause Neovim to lock up. <afile> expands to the cmdline-char.

CmdlineEnter

Fires:

After entering the command-line.

Notes:

The pattern is matched against cmdline-char. <afile> expands to the cmdline-char.

CmdlineLeave

Fires:

Before leaving the command-line.

Notes:

<afile> expands to the cmdline-char.

CmdwinEnter

Fires:

After entering the command-line window.

Notes:

Useful for setting options specifically for this special type of window. <afile> expands to a single character, indicating the type of command-line.

CmdwinLeave

Fires:

Before leaving the command-line window.

Notes:

Useful to clean up any global setting done with CmdwinEnter. <afile> expands to a single character, indicating the type of command-line.

ColorScheme

Fires:

After loading a color scheme.

Notes:

Not triggered if the color scheme is not found. The pattern is matched against the colorscheme name. <afile> can be used for the name of the actual file where this option was set, and <amatch> for the new colorscheme name.

ColorSchemePre

Fires:

Before loading a color scheme.

Notes:

Useful to setup removing things added by a color scheme, before another one is loaded.

CompleteChanged

Fires:

After each time the insert mode completion menu changed.

Notes:

Not fired on popup menu hide, use CompleteDonePre or CompleteDone for that.

CompleteDone

Fires:

After insert mode completion is done, either when something was completed or abandoning completion.

CompleteDonePre

Fires:

After insert mode completion is done, either when something was completed or abandoning completion.

CursorHold

Fires:

When in normal mode and the user doesn't press a key for the time specified with 'updatetime'.

Notes:

Not triggered until the user has pressed a key. This event is only triggered in normal mode. It is not triggered when waiting for a command argument to be typed, or a movement after an operator. CursorHold is not triggered while recording a macro.

See Also:

CursorHoldI

Fires:

When in insert mode and the user doesn't press a key for the time specified with 'updatetime'.

Notes:

Like CursorHold, but in insert mode. Not triggered when waiting for another key, e.g. after C-V, and not in C-X mode

See Also:

CursorHold

CursorMoved

Fires:

After the cursor was moved to another window, in normal or visual mode.
When the text of the cursor line has been changed, e.g. with "x", "rx" or "p".

Notes:

Not always triggered:

when there is typeahead,
while executing commands in a script file, or
when an operator is pending.

Be careful - This event is triggered very often, don't do anything that the user does not expect or that is slow.

CursorMovedI

Fires:

After the cursor was moved, in insert mode.

Notes:

Not triggered when the popup menu is visible. Otherwise the same as CursorMoved.

DiffUpdated

Fires:

After diffs have been updated.

Notes:

Depending on what kind of diff is being used (internal or external) this can be triggered on every change or when doing :diffupdate.

DirChanged

Fires:

After the current-directory was changed.

DirChangedPre

Fires:

Prior to changing the current-directory, as with DirChanged.

ExitPre

Fires:

When using :quit, :wq in a way it makes Neovim exit
When using :qall, just after QuitPre.

Notes:

Can be used to close any non-essential window. Exiting may still be cancelled if there is a modified buffer that isn't automatically saved, use VimLeavePre for really exiting.

See Also:

QuitPre WinClosed

FileAppendCmd

Fires:

Before appending to a file.

Notes:

Should do the appending to the file. Use the '[ and '] marks for the range of lines.

FileAppendPost

Fires:

After appending to a file.

FileAppendPre

Fires:

Before appending to a file.

Notes:

Use the '[ and '] marks for the range of lines.

FileChangedRO

Fires:

Before making the first change to a read-only file.
When making the first change in a buffer
When making the first change after 'readonly' was set, just before the change is applied to the text.

Notes:

Can be used to checkout the file from a source control system. Not triggered when the change was caused by an auto-command.

FileChangedShell

Fires:

When Neovim notices that the modification time of a file has changed since editing started.
When the file attributes of the file change
When the size of the file changes.

Notes:

Triggered for each changed file, after executing a shell command

FileChangedShellPost

Fires:

After handling a file that was changed outside of Neovim.

Notes:

Can be used to update the statusline.

FileReadCmd

Fires:

Before reading a file with a :read command.

Notes:

Should do the reading of the file.

FileReadPost

Fires:

After reading a file with a :read command.

Notes:

Note that Neovim sets the '[ and '] marks to the first and last line of the read. This can be used to operate on the lines just read.

FileReadPre

Fires:

Before reading a file with a :read command.

FileType

Fires:

When the 'filetype' option has been set.

Notes:

The pattern is matched against the filetype. <afile> is the name of the file where this option was set. <amatch> is the new value of 'filetype'. Cannot switch windows or buffers.

FileWriteCmd

Fires:

Before writing to a file, when not writing the whole buffer.

Notes:

Should do the writing to the file. Should not change the buffer. Use the '[ and '] marks for the range of lines.

FileWritePost

Fires:

After writing to a file, when not writing the whole buffer.

FileWritePre

Fires:

Before writing to a file, when not writing the whole buffer.

Notes:

Use the '[ and '] marks for the range of lines.

FilterReadPost

Fires:

After reading a file from a filter command.

Notes:

Neovim checks the pattern against the name of the current buffer as with FilterReadPre. Not triggered when 'shelltemp' is off.

FilterReadPre

Fires:

Before reading a file from a filter command.

Notes:

Neovim checks the pattern against the name of the current buffer, not the name of the temporary file that is the output of the filter command. Not triggered when 'shelltemp' is off.

FilterWritePost

Fires:

After writing a file for a filter command or making a diff with an external diff

Notes:

Neovim checks the pattern against the name of the current buffer as with FilterWritePre. Not triggered when 'shelltemp' is off. See DiffUpdated for internal diff.

See Also:

DiffUpdated

FilterWritePre

Fires:

Before writing a file for a filter command or making a diff with an external diff.

Notes:

Neovim checks the pattern against the name of the current buffer, not the name of the temporary file that is the output of the filter command. Not triggered when 'shelltemp' is off.

FocusGained

Fires:

When Neovim gains focus.

FocusLost

Fires:

When Neovim loses focus.
Possibly when a GUI dialog pops up.

FuncUndefined

Fires:

When an undefined user-function is called.

Notes:

Useful for defining a function only when it's used. The pattern is matched against the function name. Both <amatch> and <afile> are set to the name of the function.

InsertChange

Fires:

When typing <Insert> while in insert or replace mode.

Notes:

The v:insertmode variable indicates the new mode. Be careful not to move the cursor or do anything else that the user does not expect.

InsertCharPre

Fires:

When a character is typed in insert mode, before inserting the char.

Notes:

The v:char variable indicates the char typed and can be changed during the event to insert a different character. When v:char is set to more than one character this text is inserted literally. Cannot change the text.

InsertEnter

Fires:

Just before starting insert mode.
Just before starting replace mode .
Just before starting Virtual Replace mode.

Notes:

The v:insertmode variable indicates the mode. Be careful not to do anything else that the user does not expect. The cursor is restored afterwards. If you do not want that set v:char to a non-empty string.

InsertLeave

Fires:

Just after leaving insert mode.
When using CTRL-O i_CTRL-O.

Notes:

Does not fire for i_CTRL-C.

InsertLeavePre

Fires:

Just before leaving insert mode.
When using CTRL-O i_CTRL-O.

Notes:

Be careful not to change mode or use :normal, it will likely cause trouble.

MenuPopup

Fires:

Just before showing the popup menu (under the right mouse button).

Notes:

Useful for adjusting the menu for what is under the cursor or mouse pointer. The pattern is matched against one or two characters representing the mode.

ModeChanged

Fires:

After changing the mode.

Notes:

The pattern is matched against 'old_mode:new_mode', for example match against *:c to simulate CmdlineEnter.

OptionSet

Fires:

After setting an option (except during startup).

Notes:

The autocmd-pattern is matched against the long option name. indicates what option has been set.

QuickFixCmdPost

Fires:

After a quickfix command is run, before jumping to the first location.
For :cfile and :lfile, after the error file is read and before moving to the first error.

QuickFixCmdPre

Fires:

Before a quickfix command is run.

Notes:

The pattern is matched against the command being run.

QuitPre

Fires:

When using :quit, :wq or :qall, before deciding whether it closes the current window or quits Neovim.

Notes:

For :wq the buffer is written before QuitPre is triggered. Can be used to close any non-essential window if the current window is the last ordinary window.

See Also:

ExitPre WinClosed

RecordingEnter

Fires:

When a macro starts recording.

Notes:

The pattern is the current file name, and reg_recording() is the current register that is used.

RecordingLeave

Fires:

When a macro stops recording.

Notes:

The pattern is the current file name, and reg_recording() is the recorded register.

RemoteReply

Fires:

When a reply from a Neovim that functions as server was received server2client().

Notes:

The pattern is matched against the {serverid}. <amatch> is equal to the {serverid} from which the reply was sent, and <afile> is the actual reply string.

SafeState

Fires:

When nothing is pending, going to wait for the user to type a character.

SearchWrapped

Fires:

After making a search with n or N if the search wraps around the document back to the start/finish respectively.

SessionLoadPost

Fires:

After loading the session file created using :mksession.

ShellCmdPost

Fires:

After executing a shell command with :!cmd, :make, and :grep.

Notes:

Can be used to check for any changed files. For non-blocking shell commands, see job-control.

ShellFilterPost

Fires:

After executing a shell command with :{range}!cmd, :w !cmd, or :r !cmd.

Notes:

Can be used to check for any changed files.

Signal

Fires:

After Neovim receives a signal.

Notes:

The pattern is matched against the signal name. Only "SIGUSR1" and "SIGWINCH" are supported.

SourceCmd

Fires:

When sourcing a vim/lua file.

Notes:

:source <afile> is the name of the file being sourced. The auto-command must source this file.

SourcePost

Fires:

After sourcing a vim/lua file.
After a SourceCmd auto-command was triggered.

Notes:

:source <afile> is the name of the file being sourced. Not triggered when sourcing was interrupted.

SourcePre

Fires:

Before sourcing a vim/lua file.

Notes:

:source <afile> is the name of the file being sourced.

SpellFileMissing

Fires:

When trying to load a spell checking file and it can't be found.

Notes:

The pattern is matched against the language. <amatch> is the language, 'encoding' also matters.

StdinReadPost

Fires:

During startup, after reading from stdin into the buffer, before executing modelines.

StdinReadPre

Fires:

During startup, before reading from stdin into the buffer.

SwapExists

Fires:

When an existing swap file is detected when starting to edit a file.

Syntax

Fires:

When the 'syntax' option has been set.

Notes:

The pattern is matched against the syntax name. <afile> expands to the name of the file where this option was set. <amatch> expands to the new value of 'syntax'.

TabClosed

Fires:

After closing a tab page.

Notes:

<afile> expands to the tab page number.

TabEnter

Fires:

Just after entering a tab page.

Fires Before:

BufEnter

Fires After:

WinEnter

TabLeave

Fires:

Just before leaving a tab page.

Fires After:

WinLeave

TabNew

Fires:

When creating a new tab page.

Fires Before:

TabEnter

Fires After:

WinEnter

TabNewEntered

Fires:

After entering a new tab page.

Fires After:

BufEnter

TermClose

Fires:

When a terminal job ends.

TermEnter

Fires:

After entering Terminal-mode.

Fires After:

TermOpen

TermLeave

Fires:

After leaving Terminal-mode.

Fires After:

TermClose

TermOpen

Fires:

When a terminal job is starting.

Notes:

Can be used to configure the terminal buffer.

TermRequest

Fires:

When a terminal job emits an OSC or DCS sequence.

Notes:

When used from Lua, the request string is included in the "data" field of the auto-command callback.

TermResponse

Fires:

When Neovim receives an OSC or DCS response from the terminal.

Notes:

When used from Lua, the response string is included in the "data" field of the auto-command callback. May be triggered halfway through another event (file I/O, a shell command, or anything else that takes time).

TextChanged

Fires:

After a change was made to the text in the current buffer in normal mode.

Notes:

That is after b:changedtick has changed (also when that happened before the TextChanged auto-command was defined). Not triggered when there is typeahead or when an operator is pending. Careful - This is triggered very often, don't do anything that the user does not expect or that is slow.

TextChangedI

Fires:

After a change was made to the text in the current buffer in insert mode.

Notes:

Not triggered when the popup menu is visible. Otherwise the same as TextChanged.

TextChangedP

Fires:

After a change was made to the text in the current buffer in insert mode, only when the popup menu is visible.

Notes:

Otherwise the same as TextChanged.

TextChangedT

Fires:

After a change was made to the text in the current buffer in Terminal-mode.

Notes:

Otherwise the same as TextChanged.

TextYankPost

Fires:

Just after a yank or deleting command, but not if the black-hole register

Notes:

quote_ is used nor for setreg(). Pattern must be "*".

UIEnter

Fires:

After a UI connects via nvim_ui_attach(),
After builtin TUI is started

Fires After:

VimEnter

UILeave

Fires:

After a UI disconnects from Neovim
After builtin TUI is stopped

Fires After:

VimLeave

User

Notes:

Not executed automatically. Use :doautocmd to trigger this, typically for "custom events" in a plugin.

VimEnter

Fires:

After doing all the startup stuff, including loading vimrc files, executing the -c cmd arguments, creating all windows and loading the buffers in them.

VimLeave

Fires:

Before exiting Neovim, just after writing the .shada file.

Notes:

Executed only once, like VimLeavePre.

VimLeavePre

Fires:

Before exiting Neovim, just before writing the .shada file.

Notes:

This is executed only once, if there is a match with the name of what happens to be the current buffer when exiting. Mostly useful with a "*" pattern.

VimResized

Fires:

After the Neovim window was resized, thus 'lines' and/or 'columns' changed.

Notes:

Not fired when starting up though.

VimResume

Fires:

After Neovim resumes from suspend state.

VimSuspend

Fires:

Before Neovim enters suspend state.

WinClosed

Fires:

When closing a window, just before it is removed from the window layout.

Notes:

The pattern is matched against the window-ID. Both <amatch> and <afile> are set to the window-ID.

Fires After:

WinLeave

WinEnter

Fires:

After entering another window.

Notes:

Not fired for the first window, when Neovim has just started. Useful for setting the window height. If the window is for another buffer, Neovim executes the BufEnter auto-commands after the WinEnter auto-commands.

WinLeave

Fires:

Before leaving a window.

Notes:

If the window to be entered next is for a different buffer, Neovim executes the BufLeave auto-commands before the WinLeave auto-commands (but not for :new). Not used for :qa or :q when exiting Neovim.

Fires Before:

WinClosed

WinNew

Fires:

When a new window was created.

Notes:

Not fired for the first window, when Neovim has just started.

Fires Before:

WinEnter

WinResized

Fires:

After a window in the current tab page changed width or height.

WinScrolled

Fires:

After any window in the current tab page scrolled the text (horizontally or vertically)
After any window in the current tab changed width or height.

Notes:

The pattern is matched against the window-ID of the first window that scrolled or resized.

Neovim Events