Create an autocommand

The API allows for two (mutually exclusive) types of actions to be executed when the autocommand triggers: a callback function (Lua or Vimscript), or a command (like regular autocommands).

Example using callback:

-- Lua function
local myluafun = function() print("This buffer enters") end

-- Vimscript function name (as a string)
local myvimfun = "g:MyVimFunction"

vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
  pattern = {"*.c", "*.h"},
  callback = myluafun,  -- Or myvimfun
})

Lua functions receive a table with information about the autocmd event as an argument. To use a function which itself accepts another (optional) parameter, wrap the function in a lambda:

-- Lua function with an optional parameter.
-- The autocmd callback would pass a table as argument but this
-- function expects number|nil
local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end

vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
  pattern = {"*.c", "*.h"},
  callback = function() myluafun() end,
})

Example using command:

vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
  pattern = {"*.c", "*.h"},
  command = "echo 'Entering a C or C++ file'",
})

Example values for pattern:

pattern = "*.py"
pattern = { "*.py", "*.pyi" }

Example values for event:

"BufWritePre"
{"CursorHold", "BufWritePre", "BufWritePost"}

Parameters: {event} (string|array) The event or events to register this autocommand {opts} Dictionary of autocommand options: - group (string|integer) optional: the autocommand group name or id to match against. - pattern (string|array) optional: pattern or patterns to match against autocmd-pattern. - buffer (integer) optional: buffer number for buffer local autocommands autocmd-buflocal. Cannot be used with {pattern}. - desc (string) optional: description of the autocommand. - callback (function|string) optional: if a string, the name of a Vimscript function to call when this autocommand is triggered. Otherwise, a Lua function which is called when this autocommand is triggered. Cannot be used with {command}. Lua callbacks can return true to delete the autocommand; in addition, they accept a single table argument with the following keys: - id: (number) the autocommand id - event: (string) the name of the event that triggered the autocommand autocmd-events - group: (number|nil) the autocommand group id, if it exists - match: (string) the expanded value of <amatch> - buf: (number) the expanded value of <abuf> - file: (string) the expanded value of <afile> - data: (any) arbitrary data passed to nvim_exec_autocmds()

         - command (string) optional: Vim command to execute on event.
           Cannot be used with **{callback}**
         - once (boolean) optional: defaults to false. Run the
           autocommand only once `autocmd-once`.
         - nested (boolean) optional: defaults to false. Run nested
           autocommands `autocmd-nested`.

Return: Integer id of the created autocommand.

See also: autocommand nvim_del_autocmd()