Events


BufAdd
Fires:
Fires Before:
See Also:
BufDelete
Fires:
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.

BufFilePost
Fires:
BufFilePre
Fires:
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:
Notes:

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

BufNewFile
Fires:
  • When starting to edit a file that doesn't exist.

Notes:

Can be used to read in a skeleton file.

BufRead
Fires:
  • After successfully recovering a file for the "filetypedetect" group when executing ":filetype detect".

  • 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

Notes:

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

See Also:
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:
    Fires After:
    BufWinEnter
    Fires:
    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:
    Notes:

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

    Fires Before:
    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:
    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:
      Notes:

      Useful for defining a command only when it's used. The pattern is matched against the command name. Both and 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. expands to the cmdline-char.

      CmdlineEnter
      Fires:
      Notes:

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

      CmdlineLeave
      Fires:
      Notes:

      expands to the cmdline-char.

      CmdwinEnter
      Fires:
      Notes:

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

      CmdwinLeave
      Fires:
      Notes:

      Useful to clean up any global setting done with CmdwinEnter. 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. can be used for the name of the actual file where this option was set, and 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:
      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:
      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.

      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 after 'readonly' was set, just before the change is applied to the text.

      • When making the first change in a buffer

      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:
      Notes:

      Should do the reading of the file.

      FileReadPost
      Fires:
      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:
      FileType
      Fires:
      • When the 'filetype' option has been set.

      Notes:

      The pattern is matched against the filetype. is the name of the file where this option was set. 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:
      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:
      • Possibly when a GUI dialog pops up.

      • When Neovim loses focus.

      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 and are set to the name of the function.

      InsertChange
      Fires:
      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 replace mode .

      • Just before starting insert 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.

      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:
      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.

      RecordingEnter
      Fires:
      Notes:

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

      RecordingLeave
      Fires:
      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}. is equal to the {serverid} from which the reply was sent, and 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:
      Notes:

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

      ShellFilterPost
      Fires:
      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 is the name of the file being sourced. The auto-command must source this file.

      SourcePost
      Fires:
      • After a SourceCmd auto-command was triggered.

      • After sourcing a vim/lua file.

      Notes:

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

      SourcePre
      Fires:
      • Before sourcing a vim/lua file.

      Notes:

      :source 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. is the language, 'encoding' also matters.

      StdinReadPost
      Fires:
      StdinReadPre
      Fires:
      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. expands to the name of the file where this option was set. expands to the new value of 'syntax'.

      TabClosed
      Fires:
      • After closing a tab page.

      Notes:

      expands to the tab page number.

      TabEnter
      Fires:
      • Just after entering a tab page.

      Fires Before:
      Fires After:
      TabLeave
      Fires:
      • Just before leaving a tab page.

      Fires After:
      TabNew
      Fires:
      • When creating a new tab page.

      Fires Before:
      Fires After:
      TabNewEntered
      Fires:
      • After entering a new tab page.

      Fires After:
      TermClose
      Fires:
      • When a terminal job ends.

      TermEnter
      Fires:
      • After entering Terminal-mode.

      Fires After:
      TermLeave
      Fires:
      • After leaving Terminal-mode.

      Fires After:
      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:
      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:
      UILeave
      Fires:
      • After a UI disconnects from Neovim

      • After builtin TUI is stopped

      Fires After:
      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 and are set to the window-ID.

        Fires After:
        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:
        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:
        WinNew
        Fires:
        • When a new window was created.

        Notes:

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

        Fires Before:
        WinResized
        Fires:
        • After a window in the current tab page changed width or height.

        WinScrolled
        Fires:
        • After any window in the current tab changed width or height.

        • After any window in the current tab page scrolled the text (horizontally or vertically)

        Notes:

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