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

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`.

runtime/doc/api.txt

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

runtime/doc/deprecated.txt

@@ -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
 

runtime/doc/lsp.txt

@@ -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,

runtime/doc/lua-guide.txt

@@ -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
     })
 <

runtime/doc/lua-plugin.txt

@@ -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*

runtime/doc/lua.txt

@@ -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
+                 • {buf}? (`integer|boolean`) Remove a mapping from the given
-                   given buffer. When `0` or `true`, use the current buffer.
+                   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}.

runtime/ftplugin/checkhealth.lua

@@ -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"'

runtime/ftplugin/help.lua

@@ -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

runtime/ftplugin/markdown.lua

@@ -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"'

runtime/ftplugin/nvim-pack.lua

@@ -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')

runtime/lua/vim/_core/defaults.lua

@@ -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)

runtime/lua/vim/_meta/api.lua

@@ -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).

runtime/lua/vim/diagnostic.lua

@@ -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

runtime/lua/vim/health.lua

@@ -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)
 

runtime/lua/vim/keymap.lua

@@ -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 buf = opts.buf
-    local bufnr = opts.buffer == true and 0 or opts.buffer --[[@as integer]]
+  opts.buf = nil
-    opts.buffer = nil ---@type integer?
+  --- @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

runtime/lua/vim/lsp.lua

@@ -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

runtime/lua/vim/lsp/buf.lua

@@ -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

runtime/lua/vim/lsp/client.lua

@@ -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

runtime/scripts/optwin.lua

@@ -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'

src/nvim/api/vim.c

@@ -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).

test/functional/lua/vim_spec.lua

@@ -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)