mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-03-27 19:02:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(lua): replace buffer with buf in vim.keymap.set/del #38360

Browse Source 
The `buffer` option remains functional but is now undocumented.
Providing both will raise an error. Since providing `buf` was disallowed
before, there is no code that will break due to using `buffer` alongside
`buf`.
This commit is contained in:
skewb1k
2026-03-21 16:00:06 +00:00
committed by GitHub
parent a969e92249
commit 4d3a67cd62
21 changed files with 68 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
runtime/doc/api.txt
View File

@@ -1315,7 +1315,7 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()*
line2
line3
]], false, -1)
end, { buffer = true })
end, { buf = true })
<
Attributes: ~

1
runtime/doc/deprecated.txt
View File

@@ -51,6 +51,7 @@ LSP
LUA
• *vim.diff()* Renamed to |vim.text.diff()|
• "buffer" in `vim.keymap.set.Opts` and `vim.keymap.del.Opts` Renamed to "buf"
UI

2
runtime/doc/lsp.txt
View File

@@ -139,7 +139,7 @@ To remove or override BUFFER-LOCAL defaults, define a |LspAttach| handler: >lua
-- Unset 'omnifunc'
vim.bo[ev.buf].omnifunc = nil
-- Unmap K
vim.keymap.del('n', 'K', { buffer = ev.buf })
vim.keymap.del('n', 'K', { buf = ev.buf })
-- Disable document colors
vim.lsp.document_color.enable(false, { bufnr = ev.buf })
end,

10
runtime/doc/lua-guide.txt
View File

@@ -426,12 +426,12 @@ want to defer the loading to the time when the mapping is executed (as for
The fourth, optional, argument is a table with keys that modify the behavior
of the mapping such as those from |:map-arguments|. The following are the most
useful options:
• `buffer`: If given, only set the mapping for the buffer with the specified
• `buf`: If given, only set the mapping for the buffer with the specified
number; `0` or `true` means the current buffer. >lua
-- set mapping for the current buffer
vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { buffer = true })
vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { buf = true })
-- set mapping for the buffer number 4
vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { buffer = 4 })
vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { buf = 4 })
<
• `silent`: If set to `true`, suppress output such as error messages. >lua
vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { silent = true })
@@ -467,7 +467,7 @@ 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})
vim.keymap.del({'n', 'c'}, '<Leader>ex2', { buf = true })
<
See also:
• `vim.api.`|nvim_get_keymap()|: return all global mapping
@@ -532,7 +532,7 @@ For example, this allows you to set buffer-local mappings for some filetypes:
vim.api.nvim_create_autocmd("FileType", {
pattern = "lua",
callback = function(ev)
vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = ev.buf })
vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buf = ev.buf })
end
})
<

2
runtime/doc/lua-plugin.txt
View File

@@ -239,7 +239,7 @@ A plugin tailored to Rust development might have initialization in
-- e.g. add a |<Plug>| mapping or create a command
vim.keymap.set('n', '<Plug>(MyPluginBufferAction)', function()
print('Hello')
end, { buffer = bufnr, })
end, { buf = bufnr })
<
==============================================================================
Configuration *lua-plugin-config*

10
runtime/doc/lua.txt
View File

@@ -3598,15 +3598,15 @@ vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()*
Remove an existing mapping. Examples: >lua
vim.keymap.del('n', 'lhs')
vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })
vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buf = 5 })
<
Parameters: ~
• {modes} (`string|string[]`)
• {lhs} (`string`)
• {opts} (`table?`) A table with the following fields:
• {buffer}? (`integer|boolean`) Remove a mapping from the
given buffer. When `0` or `true`, use the current buffer.
• {buf}? (`integer|boolean`) Remove a mapping from the given
buffer. When `0` or `true`, use the current buffer.
See also: ~
• |vim.keymap.set()|
@@ -3618,7 +3618,7 @@ vim.keymap.set({modes}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
-- Map "x" to a Lua function:
vim.keymap.set('n', 'x', function() print('real lua function') end)
-- Map "<leader>x" to multiple modes for the current buffer:
vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buf = true })
-- Map <Tab> to an expression (|:map-<expr>|):
vim.keymap.set('i', '<Tab>', function()
return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
@@ -3652,7 +3652,7 @@ vim.keymap.set({modes}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
below).
Also accepts:
• {buffer}? (`integer|boolean`) Creates buffer-local mapping,
• {buf}? (`integer|boolean`) Creates buffer-local mapping,
`0` or `true` for current buffer.
• {remap}? (`boolean`, default: `false`) Make the mapping
recursive. Inverse of {noremap}.

6
runtime/ftplugin/checkhealth.lua
View File

@@ -1,13 +1,13 @@
vim.keymap.set('n', 'gO', function()
require('vim.treesitter._headings').show_toc(6)
end, { buffer = 0, silent = true, desc = 'Show an Outline of the current buffer' })
end, { buf = 0, silent = true, desc = 'Show an Outline of the current buffer' })
vim.keymap.set('n', ']]', function()
require('vim.treesitter._headings').jump({ count = 1, level = 1 })
end, { buffer = 0, silent = false, desc = 'Jump to next section' })
end, { buf = 0, silent = false, desc = 'Jump to next section' })
vim.keymap.set('n', '[[', function()
require('vim.treesitter._headings').jump({ count = -1, level = 1 })
end, { buffer = 0, silent = false, desc = 'Jump to previous section' })
end, { buf = 0, silent = false, desc = 'Jump to previous section' })
vim.b.undo_ftplugin = (vim.b.undo_ftplugin or '')
.. '\n sil! exe "nunmap <buffer> gO"'

8
runtime/ftplugin/help.lua
View File

@@ -57,14 +57,14 @@ end
vim.keymap.set('n', 'gO', function()
require('vim.treesitter._headings').show_toc()
end, { buffer = 0, silent = true, desc = 'Show an Outline of the current buffer' })
end, { buf = 0, silent = true, desc = 'Show an Outline of the current buffer' })
vim.keymap.set('n', ']]', function()
require('vim.treesitter._headings').jump({ count = 1 })
end, { buffer = 0, silent = false, desc = 'Jump to next section' })
end, { buf = 0, silent = false, desc = 'Jump to next section' })
vim.keymap.set('n', '[[', function()
require('vim.treesitter._headings').jump({ count = -1 })
end, { buffer = 0, silent = false, desc = 'Jump to previous section' })
end, { buf = 0, silent = false, desc = 'Jump to previous section' })
local parser = assert(vim.treesitter.get_parser(0, 'vimdoc'))
@@ -111,7 +111,7 @@ local function runnables()
elseif code_block.lang == 'vim' then
vim.cmd(code_block.code)
end
end, { buffer = true })
end, { buf = true })
end
-- Retry once if the buffer has changed during the iteration of the code

6
runtime/ftplugin/markdown.lua
View File

@@ -2,14 +2,14 @@ vim.treesitter.start()
vim.keymap.set('n', 'gO', function()
require('vim.treesitter._headings').show_toc()
end, { buffer = 0, silent = true, desc = 'Show an Outline of the current buffer' })
end, { buf = 0, silent = true, desc = 'Show an Outline of the current buffer' })
vim.keymap.set('n', ']]', function()
require('vim.treesitter._headings').jump({ count = 1 })
end, { buffer = 0, silent = false, desc = 'Jump to next section' })
end, { buf = 0, silent = false, desc = 'Jump to next section' })
vim.keymap.set('n', '[[', function()
require('vim.treesitter._headings').jump({ count = -1 })
end, { buffer = 0, silent = false, desc = 'Jump to previous section' })
end, { buf = 0, silent = false, desc = 'Jump to previous section' })
vim.b.undo_ftplugin = (vim.b.undo_ftplugin or '')
.. '\n sil! exe "nunmap <buffer> gO"'

2
runtime/ftplugin/nvim-pack.lua
View File

@@ -59,7 +59,7 @@ local map_section_jump = function(lhs, search_flags, desc)
for _ = 1, vim.v.count1 do
vim.fn.search('^## ', search_flags)
end
end, { buffer = 0, desc = desc })
end, { buf = 0, desc = desc })
end
map_section_jump('[[', 'bsW', 'Previous plugin')

4
runtime/lua/vim/_core/defaults.lua
View File

@@ -741,10 +741,10 @@ do
vim.keymap.set({ 'n', 'x', 'o' }, '[[', function()
jump_to_prompt(nvim_terminal_prompt_ns, 0, ev.buf, -vim.v.count1)
end, { buffer = ev.buf, desc = 'Jump [count] shell prompts backward' })
end, { buf = ev.buf, desc = 'Jump [count] shell prompts backward' })
vim.keymap.set({ 'n', 'x', 'o' }, ']]', function()
jump_to_prompt(nvim_terminal_prompt_ns, 0, ev.buf, vim.v.count1)
end, { buffer = ev.buf, desc = 'Jump [count] shell prompts forward' })
end, { buf = ev.buf, desc = 'Jump [count] shell prompts forward' })
-- If the terminal buffer is being reused, clear the previous exit msg
vim.api.nvim_buf_clear_namespace(ev.buf, nvim_terminal_exitmsg_ns, 0, -1)

2
runtime/lua/vim/_meta/api.lua generated
View File

@@ -2018,7 +2018,7 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end
--- line2
--- line3
--- ]], false, -1)
--- end, { buffer = true })
--- end, { buf = true })
--- ```
---
--- @param data string Multiline input. Lines break at LF ("\n"). May be binary (containing NUL bytes).

2
runtime/lua/vim/diagnostic.lua
View File

@@ -2661,7 +2661,7 @@ function M.open_float(opts, ...)
else
vim.cmd.normal({ 'gf', bang = true })
end
end, { buffer = float_bufnr, remap = false })
end, { buf = float_bufnr, remap = false })
--- @diagnostic disable-next-line: deprecated
local add_highlight = api.nvim_buf_add_highlight

2
runtime/lua/vim/health.lua
View File

@@ -505,7 +505,7 @@ function M._check(mods, plugin_names)
if not pcall(vim.cmd.close) then
vim.cmd.bdelete()
end
end, { buffer = bufnr, silent = true, noremap = true, nowait = true })
end, { buf = bufnr, silent = true, noremap = true, nowait = true })
end
end)

40
runtime/lua/vim/keymap.lua
View File

@@ -10,7 +10,7 @@ local keymap = {}
--- @inlinedoc
---
--- Creates buffer-local mapping, `0` or `true` for current buffer.
--- @field buffer? integer|boolean
--- @field buf? integer|boolean
---
--- Make the mapping recursive. Inverse of {noremap}.
--- (Default: `false`)
@@ -24,7 +24,7 @@ local keymap = {}
--- -- Map "x" to a Lua function:
--- vim.keymap.set('n', 'x', function() print('real lua function') end)
--- -- Map "<leader>x" to multiple modes for the current buffer:
--- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
--- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buf = true })
--- -- Map <Tab> to an expression (|:map-<expr>|):
--- vim.keymap.set('i', '<Tab>', function()
--- return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
@@ -83,14 +83,22 @@ function keymap.set(modes, lhs, rhs, opts)
rhs = ''
end
if opts.buffer then
local bufnr = opts.buffer == true and 0 or opts.buffer --[[@as integer]]
opts.buffer = nil ---@type integer?
local buf = opts.buf
opts.buf = nil
--- @cast opts +{buffer?:integer|boolean}
if opts.buffer ~= nil then
-- TODO(skewb1k): soft-deprecate `buffer` option in 0.13, remove in 0.15.
assert(buf == nil, "Conflict: 'buf' not allowed with 'buffer'")
buf = opts.buffer
opts.buffer = nil
end
if buf then
buf = buf == true and 0 or buf
for _, m in ipairs(modes) do
vim.api.nvim_buf_set_keymap(bufnr, m, lhs, rhs, opts)
vim.api.nvim_buf_set_keymap(buf, m, lhs, rhs, opts)
end
else
opts.buffer = nil
for _, m in ipairs(modes) do
vim.api.nvim_set_keymap(m, lhs, rhs, opts)
end
@@ -102,7 +110,7 @@ end
---
--- Remove a mapping from the given buffer.
--- When `0` or `true`, use the current buffer.
--- @field buffer? integer|boolean
--- @field buf? integer|boolean
--- Remove an existing mapping.
--- Examples:
@@ -110,7 +118,7 @@ end
--- ```lua
--- vim.keymap.del('n', 'lhs')
---
--- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })
--- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buf = 5 })
--- ```
---
---@param modes string|string[]
@@ -126,18 +134,22 @@ function keymap.del(modes, lhs, opts)
modes = type(modes) == 'string' and { modes } or modes
--- @cast modes string[]
local buffer = false ---@type false|integer
local buf = opts.buf
--- @cast opts +{buffer?:integer|boolean}
if opts.buffer ~= nil then
buffer = opts.buffer == true and 0 or opts.buffer --[[@as integer]]
-- TODO(skewb1k): soft-deprecate `buffer` option in 0.13, remove in 0.15.
assert(opts.buf == nil, "Conflict: 'buf' not allowed with 'buffer'")
buf = opts.buffer
end
if buffer == false then
if buf then
buf = buf == true and 0 or buf
for _, mode in ipairs(modes) do
vim.api.nvim_del_keymap(mode, lhs)
vim.api.nvim_buf_del_keymap(buf, mode, lhs)
end
else
for _, mode in ipairs(modes) do
vim.api.nvim_buf_del_keymap(buffer, mode, lhs)
vim.api.nvim_del_keymap(mode, lhs)
end
end
end

2
runtime/lua/vim/lsp.lua
View File

@@ -862,7 +862,7 @@ function lsp._set_defaults(client, bufnr)
then
vim.keymap.set('n', 'K', function()
vim.lsp.buf.hover()
end, { buffer = bufnr, desc = 'vim.lsp.buf.hover()' })
end, { buf = bufnr, desc = 'vim.lsp.buf.hover()' })
end
end)
if client:supports_method('textDocument/diagnostic') then

4
runtime/lua/vim/lsp/buf.lua
View File

@@ -462,12 +462,12 @@ function M.signature_help(config)
vim.keymap.set('n', '<Plug>(nvim.lsp.ctrl-s)', function()
show_signature(fwin)
end, {
buffer = fbuf,
buf = fbuf,
desc = 'Cycle next signature',
})
if vim.fn.hasmapto('<Plug>(nvim.lsp.ctrl-s)', 'n') == 0 then
vim.keymap.set('n', '<C-s>', '<Plug>(nvim.lsp.ctrl-s)', {
buffer = fbuf,
buf = fbuf,
desc = 'Cycle next signature',
})
end

2
runtime/lua/vim/lsp/client.lua
View File

@@ -1376,7 +1376,7 @@ local function reset_defaults(bufnr)
vim._with({ buf = bufnr }, function()
local keymap = vim.fn.maparg('K', 'n', false, true)
if keymap and keymap.callback == lsp.buf.hover and keymap.buffer == 1 then
vim.keymap.del('n', 'K', { buffer = bufnr })
vim.keymap.del('n', 'K', { buf = bufnr })
end
end)
end

4
runtime/scripts/optwin.lua
View File

@@ -701,9 +701,9 @@ else
local name = line:match('[^\t]*')
vim.cmd.help(("'%s'"):format(name))
end
end, { buffer = buf })
end, { buf = buf })
vim.keymap.set({ 'n', 'i' }, '<space>', update_current_line, { buffer = buf })
vim.keymap.set({ 'n', 'i' }, '<space>', update_current_line, { buf = buf })
end
vim.cmd '1'

2
src/nvim/api/vim.c
View File

@@ -1320,7 +1320,7 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
/// line2
/// line3
/// ]], false, -1)
/// end, { buffer = true })
/// end, { buf = true })
/// ```
///
/// @param data Multiline input. Lines break at LF ("\n"). May be binary (containing NUL bytes).

10
test/functional/lua/vim_spec.lua
View File

@@ -3178,7 +3178,7 @@ describe('vim.keymap', function()
0,
exec_lua [[
GlobalCount = 0
vim.keymap.set('n', 'asdf', function() GlobalCount = GlobalCount + 1 end, {buffer=true})
vim.keymap.set('n', 'asdf', function() GlobalCount = GlobalCount + 1 end, {buf=true})
return GlobalCount
]]
)
@@ -3188,7 +3188,7 @@ describe('vim.keymap', function()
eq(1, exec_lua [[return GlobalCount]])
exec_lua [[
vim.keymap.del('n', 'asdf', {buffer=true})
vim.keymap.del('n', 'asdf', {buf=true})
]]
feed('asdf\n')
@@ -3201,16 +3201,16 @@ describe('vim.keymap', function()
eq(
true,
exec_lua [[
opts = {buffer=true}
opts = {buf=true}
vim.keymap.set('n', 'asdf', function() end, opts)
return opts.buffer
return opts.buf
]]
)
eq(
true,
exec_lua [[
vim.keymap.del('n', 'asdf', opts)
return opts.buffer
return opts.buf
]]
)
end)