Overview

init.lua under stdpath('config') (~/.config/nvim/init.lua by default) -- the one file Neovim sources every time it starts. A lua/ directory placed beside it joins the runtimepath, which is what makes every file inside it require()-able later.

vim.o gives direct scalar assignment for boolean/number/string values. vim.opt wraps the same options in a Lua-table-like object supporting :append()/:remove(), which matters for options that are really comma-separated lists under the hood -- assigning a list-like option with vim.o silently overwrites the whole list instead of extending it.

vim.g (global), vim.b (buffer), vim.w (window), vim.t (tab) -- typed wrappers over Vim's corresponding variable scopes. vim.g.mapleader is the most common vim.g example any config sets.

mode, lhs, rhs, opts. rhs can be a string (an Ex command or another mapping) or a Lua function, called directly with no command-line round trip.

vim.api.nvim_create_autocmd(event, opts) paired with vim.api.nvim_create_augroup(name, {clear = true}). clear = true wipes the group's prior entries before each re-source adds new ones -- without it, autocommands silently pile up duplicates every time a config is re-sourced.

Any four of nargs, range, count, complete, desc, force, preview, addr, plus generic boolean |command-attributes| like bang and bar. The callback table exposes args, bang, count, fargs, line1, line2, mods, name, nargs, range, reg, smods.

Subdirectories under lua/ map to dotted paths (lua/config/options.lua becomes require('config.options')); an init.lua inside a folder collapses that folder into one requireable unit. Once required, a module is cached in package.loaded until something explicitly clears that entry.

The opt side of the packpath (site/pack/core/opt), never a start/ directory -- vim.pack :packadds it programmatically. A JSON packlockfile tracks installed state.

event, cmd, ft, keys. Setting opts on a spec tells lazy.nvim to call that plugin's own .setup(opts) automatically once it loads -- a convention the plugin itself must actually support.

The native pair vim.lsp.config(name, cfg) / vim.lsp.enable(name). vim.lsp.config('*', {...}) sets shared defaults every subsequently enabled server inherits, without repeating them per server.

nvim-lspconfig is a config-only registry supplying lsp/<name>.lua files that vim.lsp.config auto-discovers on the runtimepath. A user-authored lsp/<name>.lua in a reader's own config is discovered and merged the exact same way, with no plugin API involved.

LspAttach. Its callback receives the attaching client and the buffer number directly (via args.data.client_id and args.buf), letting keymaps and behavior be scoped correctly per buffer.

Any five of grn (rename), gra (code action), grr (references), gri (implementation), grt (type definition), gO (document symbols), grx (run codelens), K (hover).

vim.diagnostic.config(opts, namespace?). Any three of virtual_text, signs, underline, float, severity_sort.

autotrigger = true wires as-you-type completion directly into Neovim's built-in insert-mode completion once a server attaches. This removes the hard dependency on a third-party completion plugin such as nvim-cmp.

C, Lua, Markdown, Vimscript, Vimdoc -- vim.treesitter.start() runs automatically for these via Neovim's own bundled ftplugin/ files. The historic nvim-treesitter plugin was archived 2026-04-03; installing parsers for other languages now points to the active community fork's :TSInstall command.

parse, get, set, iter_captures. an/in ("a node"/"in node") for object selection, ]n/[n for sibling navigation, plus vim.treesitter.foldexpr() for syntax-tree-based folding.

A require()-able module exposing M.setup(opts), an optional plugin/*.lua file for autoloading at startup with no explicit require() call, and a lua/<name>/health.lua module integrating with :checkhealth.

vim.o.wildignore = "node_modules" assigns a scalar string outright, silently REPLACING whatever wildignore already held -- the *.pyc entry is gone, with no error anywhere. They needed vim.opt.wildignore:append({ "node_modules" }) instead, which extends the existing list-like option rather than overwriting it wholesale.

vim.b (buffer-scoped): vim.b.formatter_width = 100 is visible only in the buffer that set it. Using vim.g instead would make whichever buffer set it LAST win globally -- switching to Project B's buffer would silently show Project A's width too, since a global variable is visible from every buffer at once.

A FileType autocommand that fires only when the buffer's filetype becomes help, combined with vim.keymap.set's buffer = args.buf option inside that autocommand's callback. The mapping then exists only in that one buffer; every other buffer's q keeps its built-in macro-recording behavior untouched.

{ range = true } lets the command accept a Visual-selection or explicit line range. The callback must then read o.line1 and o.line2 and apply its effect only to that span -- a callback that accepts range = true but ignores line1/line2 (operating on the whole buffer regardless) silently defeats the entire point of accepting a range.

No. require() caches a module's return value in package.loaded the first time it runs; every subsequent require('a') call, from anywhere in the config, returns that same cached table without re-running the file. This is exactly what guarantees a.lua and b.lua share the identical table instance, not two separately-initialized copies.

lazy.nvim with a cmd trigger (cmd = 'DBUI'). The command registers as a real, callable, tab-completable stub immediately at startup, but the plugin's actual module code doesn't load until that command is typed for the first time. vim.pack has no equivalent command-triggered lazy-loading of its own -- it installs and :packadds a plugin's opt-side files, but does not defer loading behind a specific Ex command the way lazy.nvim's cmd spec field does.

vim.lsp.config('*', { capabilities = ..., root_markers = {'.git'} }). The wildcard sets shared defaults every subsequently enabled server inherits -- one call instead of five, with no drift risk from updating five separate config tables whenever the shared setting needs to change.

No, it's redundant. Neovim 0.11+ ships grn (rename) as an unconditional global keymap the instant any server attaches -- no custom binding required. Skipping it entirely, pressing grn still opens vim.lsp.buf.rename()'s prompt with zero config.

Neither is guaranteed -- without severity_sort, two diagnostics sharing one line render in whatever order they were reported (effectively insertion order), so a low-severity hint could visually cover a same-line error's sign or virtual text. Turning severity_sort on makes the error always outrank the warning visually, regardless of which one Neovim happened to receive first.

vim.keymap.set('i', '<C-space>', vim.lsp.completion.get). Manual and automatic triggering are independent -- vim.lsp.completion.get can be bound directly with no autotrigger configuration anywhere in the config; the two features never depend on each other to function.

Not a bug -- Lua is one of the five languages (C, Lua, Markdown, Vimscript, Vimdoc) whose parser ships bundled with Neovim, with automatic vim.treesitter.start() wired in by Neovim's own ftplugin/lua.lua. Rust is not one of the five, so nothing highlights it automatically. The general fix: install the parser via the active community fork's :TSInstall rust (the original nvim-treesitter/nvim-treesitter has been archived since 2026-04-03), then add a FileType autocommand calling vim.treesitter.start(0, 'rust') for languages Neovim's bundled ftplugin/ files don't already wire up.

lua/<name>/health.lua exposing M.check(), which internally calls vim.health.start('myplugin') to open the report section and vim.health.ok(...)/vim.health.error(...) per individual check -- the exact same functions core Neovim's own health checks use. :checkhealth <name> discovers and runs the module purely from its location on the runtimepath, the identical discovery mechanism used for every bundled and third-party health module.

vim.g.mapleader = ' '                            -- => THE FIX: must run BEFORE any <leader>-prefixed
                                                  -- => keymap (co-03) -- mapleader is resolved into the
                                                  -- => mapping's lhs at the exact moment vim.keymap.set runs
vim.keymap.set('n', '<leader>w', ':w<CR>', { desc = 'Save file' })
                                                  -- => now <leader> resolves to ' ' (co-04) -- the mapping
                                                  -- => is stored as a literal Space-prefixed lhs, <Space>w

Root cause: <leader> is substituted with whatever vim.g.mapleader currently holds at mapping time, not at keypress time. The buggy version sets the keymap first, while mapleader still has its default value (empty, which Neovim treats as backslash) -- reordering the two lines is the entire fix, with no other change needed.

Run: nvim --headless -u init.lua -c 'verbose map <space>w' -c 'verbose map \w' -c 'qa!'

Output (before / after respectively -- see transcript.txt for the full captured run):

No mapping found
n  \w          * :w<CR>

n  <Space>w    * :w<CR>
No mapping found

local function setup()
  local group = vim.api.nvim_create_augroup('MyConfig', { clear = true })
                                                  -- => THE FIX: { clear = true } (co-05) wipes MyConfig's
                                                  -- => prior entries at the TOP of every load, before the
                                                  -- => next line re-adds exactly one
  vim.api.nvim_create_autocmd('BufWritePre', { group = group, pattern = '*', command = 'echo "saving"' })
end
 
setup()

Root cause: an autocommand created with no group at all has nothing to clear it -- every re-source of the config runs nvim_create_autocmd again, adding one more entry with no way to remove the old ones. Wrapping the same call in an augroup created with { clear = true } fixes this without touching the autocommand itself.

Run: nvim --headless -u init.lua -c 'source init.lua' -c 'source init.lua' -c "lua print(#vim.api.nvim_get_autocmds({event='BufWritePre'}))" -c 'qa!'

Output: 3 (before) / 1 (after) -- three total loads either way (the initial load plus two explicit re-sources).

local mod1 = require('config.scratch')          -- => caches config.scratch in package.loaded (co-07)
print('first require:', mod1.value)              -- => Output: first require: 1
 
local target = vim.fn.stdpath('config') .. '/lua/config/scratch.lua'
vim.fn.writefile({ 'return { value = 2 }' }, target)
                                                  -- => simulates a live on-disk edit while Neovim runs
 
package.loaded['config.scratch'] = nil           -- => THE FIX: clears the cache entry FIRST
local mod2 = require('config.scratch')           -- => re-reads and re-runs the file from disk (co-07)
print('second require (cache cleared first):', mod2.value)
                                                  -- => Output: second require (cache cleared first): 2

Root cause: require() alone never re-reads an already-loaded module -- package.loaded still holds the table from the first call, so a second require() with no cache clear returns that identical stale object even though the on-disk file has changed. Clearing package.loaded['config.scratch'] = nil before the second call is the entire fix.

Run: verified against an isolated XDG_CONFIG_HOME whose nvim/ is this kata's before/ or after/ tree (nvim -u before/init.lua alone does not add a sibling lua/ to the runtimepath -- see transcript.txt for why and the exact commands used).

Output: 1 then 1 (before) / 1 then 2 (after).

vim.pack.add({                                   -- => THE FIX: a TABLE spec, not a bare URL string
  { src = 'https://github.com/sainnhe/gruvbox-material', version = 'v1.0.0' },
                                                  -- => version = 'v1.0.0' pins an exact tag (co-08) --
                                                  -- => vim.pack.get() reports it back as spec.version,
                                                  -- => plus the resolved commit as rev
})

Root cause: a bare URL string ({'https://github.com/...'}) has no version field at all -- there is nothing to pin, so vim.pack.add tracks whatever the remote's default branch currently points to, which can differ between machines or between runs. Switching to the table-spec form with an explicit version field is the entire fix.

Run: vim.pack.get({'gruvbox-material'})[1] after each install -- see transcript.txt for the full commands (both runs used isolated, throwaway XDG_CONFIG_HOME/XDG_DATA_HOME directories) and an independent git ls-remote cross-check confirming the pinned tag's resolved commit matches exactly.

Output: version field: nil / resolved rev: 11d779b2... (before) vs. version field: v1.0.0 / resolved rev: 1671e0ec... (after).

vim.api.nvim_create_autocmd('LspAttach', {       -- => THE FIX: bind INSIDE LspAttach (co-12), not at
  callback = function(args)                      -- => the top level
    vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf, desc = 'LSP hover' })
                                                  -- => buffer = args.buf (co-04, co-05) scopes K to ONLY
                                                  -- => the buffer that just attached
  end,
})

Root cause: vim.keymap.set('n', 'K', ...) with no buffer option is a global keymap, active in every buffer the moment it's created -- regardless of whether any LSP client ever attaches there. Wrapping the exact same call inside LspAttach's callback, scoped with buffer = args.buf, is what confines it to buffers a server genuinely attached to, exactly Example 39's own pattern applied to a fresh bug.

Run: see transcript.txt for the full nvim --headless commands against both scratch.lua and scratch.txt.

Output: K in scratch.lua: true / K in scratch.txt: true (before, bug) vs. K in scratch.lua: true / K in scratch.txt: false (after, fixed).

vim.keymap.set('n', '<leader>xl', vim.diagnostic.setloclist, { desc = 'Diagnostics to loclist' })
                                                  -- => THE FIX: vim.diagnostic.setloclist (co-14) targets
                                                  -- => the CURRENT WINDOW's location list directly -- no
                                                  -- => manual toqflist()/setqflist() plumbing needed at all

Root cause: vim.fn.setqflist() always writes to the single, global quickfix list, no matter how the items were gathered -- calling it from a function whose own desc promises "loclist" is a real, easy mix-up between the two genuinely different list mechanisms this topic covers (Examples 78 and 79 sit side by side specifically to make the contrast explicit). vim.diagnostic.setloclist() is the dedicated function for the location list; reaching for it directly avoids the mix-up entirely.

Run: see transcript.txt for the full commands, including how the keymap's callback is invoked directly via maparg(...).callback().

Output: loclist count: 0 qflist count: 1 (before, bug) vs. loclist count: 1 qflist count: 0 (after, fixed).

local files = vim.treesitter.query.get_files('lua', 'highlights')
                                                  -- => THE FIX: locate the BUNDLED query's own source
                                                  -- => file first (co-17), instead of writing only the
                                                  -- => new pattern
local original = table.concat(vim.fn.readfile(files[1]), '\n')
                                                  -- => read the original query TEXT back into a string
vim.treesitter.query.set('lua', 'highlights', original .. '\n(identifier) @custom_ident')
                                                  -- => concatenate the custom pattern onto the END of the
                                                  -- => original -- nothing from the bundled query is lost

Root cause: vim.treesitter.query.set(lang, name, query) fully replaces a language's compiled query -- it has no "merge" mode. Passing only the one new pattern discards everything the bundled query already provided. Reading the bundled query's own source text first (vim.treesitter.query.get_files), then appending the new pattern to it before calling query.set(), keeps every original capture and adds one more.

Run: see transcript.txt for the full commands and a baseline (untouched) capture count for cross-reference.

Output: captures: 1 (before, bug) vs. captures: 38 (after: the original 37 plus the new one) -- baseline, untouched: captures: 37.

local M = {}
 
function M.setup(opts)                           -- => THE FIX: registration moves INSIDE M.setup() (co-18)
  vim.api.nvim_create_user_command('MyPluginCmd', function() print('ran') end, {})
                                                  -- => now only runs once a caller explicitly opts in
end
 
return M

Root cause: any code written at a Lua module's file scope (outside every function) runs the instant that module is require()-d -- module loading and setup() running are two genuinely separate steps (co-18), and a plugin author who registers a command outside M.setup() accidentally couples the two, handing every caller a side effect they never asked for. Moving the exact same nvim_create_user_command call inside M.setup() is the entire fix.

Run: init.lua is identical in both before/ and after/ (require('myplugin'), .setup() deliberately never called) -- see transcript.txt for the full commands.

Output: true (before, bug: leaked) vs. false (after, fixed: correctly absent).

Vanilla Neovim (topic 1) is pure mechanism -- the modal grammar, motions, and text objects every config sits on top of, identical no matter what's layered above it. Which plugins to install, which servers to enable, which keys to bind is exactly the part that legitimately differs from developer to developer -- that's policy. Shipping one fixed opinionated config would collapse that distinction, forcing every reader into someone else's policy choices; teaching the mechanism/policy boundary explicitly means a reader can swap vim.pack for lazy.nvim, or lua_ls for a different server, without relearning anything about how Neovim itself works underneath.

The cost is a layer of indirection between "I want X" and the server or parser actually doing the work underneath. Concretely: Example 37's diagnostics did not disappear as expected in this exact sandbox/version combination, even though the settings-merge itself genuinely reached the attached client (server_capabilities.diagnosticProvider was nil) -- a language-agnostic abstraction still depends on what the specific server underneath actually implements, and that gap is invisible until you check server_capabilities directly, exactly what Examples 64 and 65 do for workspace symbols and inlay hints rather than assuming a keymap "should" work.

co-13's baseline keymaps are mechanism, not policy -- they guarantee any server that attaches gives a reader a working baseline (rename, references, hover) with zero configuration, the same way modal editing's motions work identically regardless of which plugins happen to be installed. LspAttach-scoped custom keymaps remain the policy layer on top, for a reader who wants a DIFFERENT key than grn, or additional behavior beyond the default set. The defaults don't remove that flexibility -- they just make "did I forget to bind grn" no longer block basic productivity while a reader is still building their own config's policy layer.

This mirrors the LSP/Treesitter abstraction-and-its-cost trade at the tooling layer instead of the protocol layer: vim.pack.add({...}) or lazy.nvim's spec table give a uniform installation mechanism regardless of what a given repository's plugin actually contains -- exactly the uniformity that makes plugin management learnable once and reusable for any plugin. The cost is that "installed and pinned" says nothing about what a plugin's Lua code actually does at runtime; co-08's own verification method (checking vim.pack.get()'s resolved rev, cross-checked against a real git ls-remote) confirms WHICH commit installed, not WHAT that commit's code does -- a genuinely separate concern this topic's mechanism does not cover.

It's mechanism -- Neovim's own runtime ships the decision to call vim.treesitter.start() for its five bundled parsers (C, Lua, Markdown, Vimscript, Vimdoc), identically on every install, with no config author choice involved at all. Recognizing this as mechanism (not something a reader's own config "did") matters because it means a reader can trust these five languages will highlight correctly on any fresh Neovim 0.12+ install with zero setup, while every other language remains a genuine POLICY decision -- which parser to install, and whether to write the FileType autocommand that starts it, exactly as Example 49 does manually for Python.

The Lua module system (co-07) -- require()-able files under lua/, an optional plugin/ autoload file, an M.setup(opts) convention -- is the uniform shape both third-party plugins and self-authored code share; learning it once (Example 20's config split) pays off again for authoring (Examples 71-77). The cost: that uniformity is purely structural, not behavioral -- Example 33 shows a real, reproducible error when opts = {} assumes a plugin follows the M.setup(opts) convention and it does not (plenary's own __index-based lazy-loading metatable resolves .setup to an unrelated submodule instead of a callable function). Looking the same on disk never guarantees a plugin actually honors every convention its shape implies -- Kata 8's own bug (a command leaking outside setup()) is the same lesson from the opposite direction: the shape is only a promise a plugin author has to keep on purpose.