the `pattern` (see |<amatch>|)
• `buf`:   the number of the buffer the event was triggered in (see |<abuf>|)
• `file`:  the file name of the buffer the event was triggered in (see |<afile>|)
• `data`:  a table with other relevant data that is passed for some events

For example, this allows you to set buffer-local mappings for some filetypes:
>lua
    vim.api.nvim_create_autocmd("FileType", {
      pattern = "lua",
      callback = function(args)
        vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
      end
    })
<
This means that if your callback itself takes an (even optional) argument, you
must wrap it in `function() end` to avoid an error:
>lua
    vim.api.nvim_create_autocmd('TextYankPost', {
      callback = function() vim.hl.on_yank() end
    })
<
(Since unused arguments can be omitted in Lua function definitions, this is
equivalent to `function(args) ... end`.)

Instead of using a pattern, you can create a buffer-local autocommand (see
|autocmd-buflocal|) with `buffer`; in this case, `pattern` cannot be used:
>lua
    -- set autocommand for current buffer
    vim.api.nvim_create_autocmd("CursorHold", {
      buffer = 0,
      callback = function() print("hold") end,
    })

    -- set autocommand for buffer number 33
    vim.api.nvim_create_autocmd("CursorHold", {
      buffer = 33,
      callback = function() print("hold") end,
    })
<
Similarly to mappings, you can (and should) add a description using `desc`:
>lua
    vim.api.nvim_create_autocmd('TextYankPost', {
      callback = function() vim.hl.on_yank() end,
      desc = "Briefly highlight yanked text"
    })
<
Finally, you can group autocommands using the `group` key; this will be
covered in detail in the next section.

------------------------------------------------------------------------------
Grouping autocommands                             *lua-guide-autocommands-group*

Autocommand groups can be used to group related autocommands together; see
|autocmd-groups|. This is useful for organizing autocommands and especially
for preventing autocommands to be set multiple times.

Groups can be created with `vim.api.`|nvim_create_augroup()|. This function
takes two mandatory arguments: a string with the name of a group and a table
determining whether the group should be cleared (i.e., all grouped
autocommands removed) if it already exists. The function returns a number that
is the internal identifier of the group. Groups can be specified either by
this identifier or by the name (but only if the group has been created first).

For example, a common Vimscript pattern for autocommands defined in files that
may be reloaded is
>vim
    augroup vimrc
      " Remove all vimrc autocommands
      autocmd!
      au BufNewFile,BufRead *.html set shiftwidth=4
      au BufNewFile,BufRead *.html set expandtab
    augroup END
<
This is equivalent to the following Lua code:
>lua
    local mygroup = vim.api.nvim_create_augroup('vimrc', { clear = true })
    vim.api.nvim_create_autocmd({ 'BufNewFile', 'BufRead' }, {
      pattern = '*.html',
      group = mygroup,
      command = 'set shiftwidth=4',
    })
    vim.api.nvim_create_autocmd({ 'BufNewFile', 'BufRead' }, {
      pattern = '*.html',
      group = 'vimrc',  -- equivalent to group=mygroup
      command = 'set expandtab',
    })
<
Autocommand groups are unique for a given name, so you can reuse them, e.g.,
in a different file:
>lua
    local mygroup = vim.api.nvim_create_augroup('vimrc', { clear = false })
    vim.api.nvim_create_autocmd({ 'BufNewFile', 'BufRead' }, {
      pattern = '*.c',
      group = mygroup,
      command = 'set noexpandtab',
    })
<
------------------------------------------------------------------------------
Deleting autocommands                            *lua-guide-autocommands-delete*

You can use `vim.api.`|nvim_clear_autocmds()| to remove autocommands. This
function takes a single mandatory argument that is a table of keys describing
the autocommands that are to be removed: