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

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