vim.keymap.set a fondo: modos, callbacks y opciones

Cada atajo que añades a tu configuración pasa por la misma puerta. vim.keymap.set no es azúcar sintáctico sobre nvim_set_keymap: invierte un valor por defecto heredado de Vimscript, acepta funciones de Lua donde la API solo admitía cadenas y normaliza la notación de modos. Conocer sus cuatro argumentos con precisión quirúrgica es la diferencia entre coleccionar atajos sueltos y diseñar un lenguaje.

La firma y la asimetría que corrige

La función toma cuatro argumentos: el modo (una cadena o una lista de cadenas), el lhs o secuencia de teclas que pulsas, el rhs o comportamiento resultante, y una tabla de opciones. En Vimscript, :map es recursivo por definición histórica: el resultado vuelve a pasar por la tabla de mapeos, y por eso existía :noremap. nvim_set_keymap heredó ese defecto y exige noremap = true de forma explícita. vim.keymap.set invierte la carga de la prueba: nunca remapea salvo que se lo pidas con remap = true.

-- API cruda: heredera de Vimscript, recursiva salvo que digas lo contrario
vim.api.nvim_set_keymap('n', '<leader>w', ':write<CR>', { noremap = true, silent = true })

-- Envoltorio de Lua: no recursivo por defecto
vim.keymap.set('n', '<leader>w', '<Cmd>write<CR>', { silent = true, desc = 'Guardar' })

-- La excepción legítima: encadenar con un mapeo <Plug> de un plugin exige recursión
vim.keymap.set('n', 'ys', '<Plug>(nvim-surround-normal)', { remap = true, desc = 'Envolver' })

Un mapeo <Plug> es, por construcción, inalcanzable desde el teclado: nadie puede teclear <Plug>. Solo existe para ser el destino de otro mapeo, y llegar hasta él requiere recursión. Ese es prácticamente el único caso donde remap = true está justificado.

Fíjate también en <Cmd>write<CR> frente a :write<CR>. Con dos puntos entras de verdad en la línea de comandos: cambias de modo, disparas CmdlineEnter y CmdlineLeave, y en modo visual Neovim te inserta el rango '<,'> automáticamente. Con <Cmd> el comando se ejecuta sin abandonar el modo actual y sin efectos colaterales. Salvo que quieras justo ese rango automático, <Cmd> es siempre la opción correcta.

Modos: la tabla que casi todos usan mal

El error más extendido de toda la comunidad es escribir v cuando se quiere decir x. El modo selección existe para que, al saltar a un hueco de un snippet, cualquier tecla imprimible sustituya el texto seleccionado, tal como haría un editor convencional. Si mapeas p en modo v, ese mapeo también se instala en selección y romperás la escritura sobre los huecos del snippet. La regla es tajante: mapea siempre en x salvo que sepas explícitamente que quieres tocar el modo selección.

El modo o es el otro gran desaprovechado. Un mapeo en operator-pending define un nuevo complemento gramatical: si mapeas ir en o y en x, acabas de crear un objeto de texto que funciona con todos los verbos nativos a la vez, y dir, cir e yir pasan a existir sin escribir una línea más.

-- Un objeto de texto nuevo: el contenido íntegro del buffer
vim.keymap.set({ 'o', 'x' }, 'ie', function()
  vim.cmd('normal! ggVG')
end, { desc = 'Objeto de texto: el archivo entero' })

Con esas cuatro líneas, die, yie, cie y =ie existen de golpe. Esa es la aritmética de la gramática: los mapeos suman, los complementos y los operadores multiplican.

flowchart TB
T[Tecla pulsada] --> L[Existe mapeo local de buffer]
L -->|si| E[Se ejecuta ese y gana siempre]
L -->|no| G[Existe mapeo global]
G -->|si| E
G -->|no| D[Comportamiento nativo de Neovim]
style E fill:#a6e3a1,color:#11111b
style D fill:#89b4fa,color:#11111b
style T fill:#cba6f7,color:#11111b

Callbacks de Lua en lugar de cadenas

Cuando el rhs es una función, Neovim no guarda ninguna secuencia de teclas: almacena la referencia en el campo callback de la tabla de mapeos, y nvim_get_keymap devolverá rhs vacío. Esto tiene consecuencias que van mucho más allá de la comodidad. Puedes cerrar sobre variables locales, no tienes que escapar termcodes, no atraviesas la frontera Lua-Vimscript-Lua que impone <Cmd>lua ...<CR>, y un error te da una traza legible en lugar de un E5108 desnudo.

vim.keymap.set('n', '<leader>bd', function()
  local buf = vim.api.nvim_get_current_buf()
  if vim.bo[buf].modified then
    vim.notify('El buffer tiene cambios sin guardar', vim.log.levels.WARN)
    return
  end
  vim.api.nvim_buf_delete(buf, {})
end, { desc = 'Cerrar el buffer si está guardado' })

Dentro del callback tienes acceso al contexto completo de la pulsación: vim.v.count1 te da el conteo que el usuario tecleó antes de la tecla (con 1 como valor por defecto), vim.v.register el registro que precedía con comillas, y vim.fn.mode() el modo exacto. El valor de retorno se ignora por completo salvo que la opción expr esté activa; es la fuente de errores más común al empezar.

Las opciones que cambian el comportamiento

Quedan cuatro opciones menores pero decisivas. nowait impide que Neovim espere más teclas cuando tu lhs es prefijo de otro mapeo. unique provoca un error E227 si el mapeo ya existía, y colocarlo en tu configuración convierte cualquier colisión silenciosa en un fallo ruidoso al arrancar. replace_keycodes solo tiene sentido junto a expr. Y vim.keymap.del retira un mapeo, incluidos los que Neovim instala de fábrica.

-- Renunciar a un mapeo nativo que quieres reservar para otra cosa
vim.keymap.del('n', 'grn')

-- Mapeo local instalado cuando un cliente LSP se engancha al buffer
vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(ev)
    vim.keymap.set('n', '<leader>cf', function()
      vim.lsp.buf.format({ async = true })
    end, { buffer = ev.buf, desc = 'Formatear con el LSP' })
  end,
})