true`: >lua
vim.keymap.set('n', '<Leader>ex1', '<cmd>echo "Example 1"<cr>')
-- add a shorter mapping
vim.keymap.set('n', 'e', '<Leader>ex1', { remap = true })
<
Note: |<Plug>| mappings are always expanded even with the default `remap = false`: >lua
vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
<
------------------------------------------------------------------------------
Removing mappings *lua-guide-mappings-del*
A specific mapping can be removed with |vim.keymap.del()|:
>lua
vim.keymap.del('n', '<Leader>ex1')
vim.keymap.del({'n', 'c'}, '<Leader>ex2', {buffer = true})
<
------------------------------------------------------------------------------
See also:
• `vim.api.`|nvim_get_keymap()|: return all global mapping
• `vim.api.`|nvim_buf_get_keymap()|: return all mappings for buffer
==============================================================================
Autocommands *lua-guide-autocommands*
An |autocommand| is a Vim command or a Lua function that is automatically
executed whenever one or more |events| are triggered, e.g., when a file is
read or written, or when a window is created. These are accessible from Lua
through the Nvim API.
------------------------------------------------------------------------------
Creating autocommands *lua-guide-autocommand-create*
Autocommands are created using `vim.api.`|nvim_create_autocmd()|, which takes
two mandatory arguments:
• {event}: a string or table of strings containing the event(s) which should
trigger the command or function.
• {opts}: a table with keys that control what should happen when the event(s)
are triggered.
The most important options are:
• `pattern`: A string or table of strings containing the |autocmd-pattern|.
Note: Environment variable like `$HOME` and `~` are not automatically
expanded; you need to explicitly use `vim.fn.`|expand()| for this.
• `command`: A string containing a Vim command.
• `callback`: A Lua function.
You must specify one and only one of `command` and `callback`. If `pattern` is
omitted, it defaults to `pattern = '*'`.
Examples:
>lua
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
command = "echo 'Entering a C or C++ file'",
})
-- Same autocommand written with a Lua function instead
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
callback = function() print("Entering a C or C++ file") end,
})
-- User event triggered by MyPlugin
vim.api.nvim_create_autocmd("User", {
pattern = "MyPlugin",
callback = function() print("My Plugin Works!") end,
})
<
Nvim will always call a Lua function with a single table containing information
about the triggered autocommand. The most useful keys are
• `match`: a string that matched 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|)