Creates an autocommand event handler, defined by callback (Lua function or Vimscript function name string) or command (Ex command string).

Example using Lua callback: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { pattern = {".c", ".h"}, callback = function(ev) print(string.format('event fired: s', vim.inspect(ev))) end }) <

Example using an Ex command as the handler: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { pattern = {".c", ".h"}, command = "echo 'Entering a C or C++ file'", }) <

Note: pattern is NOT automatically expanded (unlike with :autocmd), thus names like "$HOME" and "~" must be expanded explicitly: >lua pattern = vim.fn.expand("~") .. "/some/path/*.py" <

Parameters:

• {event} (string|array) Event(s) that will trigger the handler (callback or command).

• {opts} Options dict: - group (string|integer) optional: autocommand group name or id to match against. - pattern (string|array) optional: pattern(s) to match literally autocmd-pattern. - buffer (integer) optional: buffer number for buffer-local autocommands autocmd-buflocal. Cannot be used with {pattern}. - desc (string) optional: description (for documentation and troubleshooting). - callback (function|string) optional: Lua function (or Vimscript function name, if string) called when the event(s) is triggered. Lua callback can return true to delete the autocommand, and receives a table argument with these keys: - id: (number) autocommand id - event: (string) name of the triggered event autocmd-events - group: (number|nil) autocommand group id, if any - match: (string) expanded value of <amatch> - buf: (number) expanded value of <abuf> - file: (string) expanded value of <afile> - data: (any) arbitrary data passed from 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: Autocommand id (number)

See also:

• autocommand
• nvim_del_autocmd()