From 4d3a67cd620152d11ab9b5f5bdd973f84cc2d44b Mon Sep 17 00:00:00 2001
From: skewb1k <skewb1kunix@gmail.com>
Date: Sat, 21 Mar 2026 16:00:06 +0000
Subject: 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/keymap.lua | 40 ++++++++++++++++++++++++++--------------
 1 file changed, 26 insertions(+), 14 deletions(-)

(limited to 'runtime/lua/vim/keymap.lua')

diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index 8464f68a37..94e1df0f31 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/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
-- 
cgit