LinuxInstalls/nvim

Neovim Setup

A scripted Neovim setup built around C/C++ development (CMake + clangd + codelldb), with LSP support for Go, C#, TypeScript/JavaScript, HTML, and CSS alongside it. setup_neovim.sh handles installing dependencies and putting everything in place; the actual config lives in config/ as plain files, not embedded in the script.

Supports Fedora, Ubuntu, Debian, and Arch Linux (and their common derivatives — Pop!_OS, Linux Mint, Manjaro, EndeavourOS, etc. — via /etc/os-release's ID_LIKE) — the script detects which one you're on and uses the right package manager and package names automatically.

Contents

• Installing
• What gets installed
• Config layout & adding plugins
• Terminal vs. desktop (Neovide)
• Editor basics
• Look & feel
• Buffers & tabs
• Text search (Telescope)
• File explorer (nvim-tree)
• LSP & code intelligence
• Rule-of-five boilerplate
• Autocompletion & snippets
• Documentation generation
• Debugging (nvim-dap)
• Terminal
• Git
• Database (MariaDB)
• Hex viewer
• Formatting and linting
• Known quirks

Installing

chmod +x setup_neovim.sh
./setup_neovim.sh

Keep setup_neovim.sh and the config/ folder next to each other — the script only installs dependencies and copies config/'s contents into place; it exits with an error if it can't find config/ beside itself. To customize anything (keymaps, plugins, the theme, the clang-tidy/format rules), edit the files under config/ directly rather than the script — see What gets installed for where each one ends up.

This deletes ~/.config/nvim and ~/.local/share/nvim before writing the new config — there is no backup step. If you have an existing Neovim setup you care about, copy it elsewhere first.

The script:

1. Detects your distro, asks which Neovim frontend(s) you want (see Terminal vs. desktop (Neovide)), and installs system packages via the right manager (dnf/apt/pacman), plus two Nerd Fonts (JetBrainsMono, Cascadia Code) for icon glyphs.
2. Wipes and rewrites ~/.config/nvim.
3. Copies personal ~/.clang-format/~/.clang-tidy fallbacks and ~/cpp-style-guide.md into place (see Formatting and linting).

First launch takes a minute or two: lazy.nvim bootstraps itself and installs all plugins, then Mason installs the language servers and codelldb.

Distro-specific notes

• Debian: the .NET SDK isn't in Debian's own repos, so the script adds Microsoft's apt feed just for that one package. This step is best-effort — if it fails, the rest of the script still completes; see the printed warning for manual install instructions (only matters for C#/omnisharp).
• Ubuntu/Debian: fd-find's binary is named fdfind (a package-name clash with something unrelated), not fd like on Fedora/Arch. The script symlinks ~/.local/bin/fd to it so anything expecting a plain fd on PATH (e.g. Telescope's file finder) works the same as everywhere else — make sure ~/.local/bin is actually on your PATH.
• Arch: the script runs a full pacman -Syu before installing anything new, per Arch's own guidance against partial upgrades — this does mean it'll upgrade your existing packages too, not just add new ones.
• Older distro releases (Debian stable, older Ubuntu LTS): this config relies on Neovim 0.11+ APIs throughout. If your distro's packaged Neovim is older, the script prints a warning after install — see Neovim's install docs for an AppImage/PPA/prebuilt build if so.
• Neovide (if you choose it — see Terminal vs. desktop (Neovide)): Arch installs the packaged neovide binary directly; Fedora and Debian/Ubuntu have no native package for it, so the script builds it from source via cargo (installing Rust via rustup first if cargo isn't already on PATH), per Neovide's own install docs. This can take several minutes and, like the .NET SDK step, is best-effort — a failed build prints a warning rather than stopping the rest of the script.

What gets installed

Package names vary by distro (see the script for the exact list per package manager), but the same set gets installed everywhere:

• Compilers/tools: gcc, g++, make, cmake, clang tooling, lldb, gdb, .NET SDK 8.0, Go, nodejs/npm, python3-pip
• CLI tools: ripgrep, fd, git, curl, wget, unzip, fish (used only for Neovim's embedded terminal — see Terminal), and the MariaDB client (mariadb; client only, no server — see Database (MariaDB))
• Language servers: clangd, gopls, omnisharp, ts_ls, html, cssls, sqls (via Mason), plus typescript-language-server and vscode-langservers-extracted via npm
• Debug adapter: codelldb (auto-installed by Mason on first debug session)
• Neovide, optionally — see Terminal vs. desktop (Neovide)

Everything the script writes rather than installs comes from config/, copied into place as-is:

config/	Copied to
nvim/ — the whole tree: init.lua, lua/plugins/*.lua, lua/config/…, lua/dap/… (see Config layout)	~/.config/nvim/... (same layout)
clang-format	~/.clang-format
clang-tidy	~/.clang-tidy
cpp-style-guide.md	~/cpp-style-guide.md

Config layout & adding plugins

config/nvim/
├── init.lua                   options, keymaps, Neovide settings, lazy.nvim bootstrap
└── lua/
    ├── plugins/               one file per plugin (or tightly coupled group)
    │   ├── lsp.lua            nvim-lspconfig + Mason
    │   ├── completion.lua     nvim-cmp + LuaSnip
    │   ├── database.lua       vim-dadbod + UI + completion (MariaDB)
    │   ├── dap.lua            nvim-dap + UI
    │   └── …                  telescope, nvim-tree, bufferline, lualine, and so on
    ├── config/lsp/            helper modules that are *not* plugin specs
    │   ├── servers.lua        the list of language servers, plus per-server overrides
    │   ├── keymaps.lua        LSP keymaps, applied when a server attaches
    │   └── commands.lua       :LspRestart & co. for Neovim 0.12+
    └── dap/configurations/    per-project debug targets (cmake.lua)

init.lua calls require("lazy").setup("plugins"), which makes lazy.nvim require every .lua file in lua/plugins/ and merge what they return. Each file returns a list of plugin specs, the files don't depend on one another, and there is no central list to update. File order doesn't matter either: the colorscheme sets priority = 1000, and every plugin that calls into another one declares it as a dependency.

Adding a plugin means dropping a new file into lua/plugins/:

-- lua/plugins/my-plugin.lua
return {
  {
    "author/plugin.nvim",
    event = "VeryLazy",
    opts = {},
  },
}

Adding a language server means adding one line to lua/config/lsp/servers.lua (name = {}, — or with overrides inside the braces). That one table feeds both Mason's installer and vim.lsp.enable(), so there's no second list to keep in sync.

Keep non-spec modules out of lua/plugins/. lazy.nvim treats everything in that folder as a plugin spec, so a helper module placed there would be read as a (malformed) spec. Helpers go under lua/config/ instead.

If you copy these files over an existing ~/.config/nvim by hand rather than running the script (which wipes the directory first), delete the old lua/plugins/init.lua — lazy.nvim would still load it alongside the new files, and every plugin would be declared twice.

Terminal vs. desktop (Neovide)

The installer asks which Neovim frontend(s) to set up:

1. Terminal-based only — just nvim, run inside whatever terminal emulator you already use. This is the default if the script is run non-interactively (piped rather than executed directly).
2. Desktop application only — installs Neovide on top. Neovide is a separate GUI window, but it isn't a separate editor — it runs the real nvim binary as its backend, so that's installed either way regardless of which option you pick.
3. Both.

There's only one config either way (config/nvim/) — Neovide reads the exact same init.lua, so keymaps, plugins, and the LSP setup are all identical between the two. Two things differ between them — cursor animation and background transparency — and the config detects which frontend it's running under (vim.g.neovide) and picks the right mechanism for each automatically:

• Terminal: smear-cursor.nvim draws the animated cursor trail — a terminal has no native equivalent, so this fills that gap. vscode.nvim's transparent option is on, clearing highlight-group backgrounds so whatever the terminal emulator draws behind Neovim shows through — including a background image, if your terminal supports one (e.g. kitty's own background_image setting). That's a terminal-level feature this config has no reach into; without it configured on the terminal side, transparency here just shows the terminal's normal background color, which is a harmless no-op look.
• Neovide: uses Neovide's own built-in, GPU-accelerated cursor VFX (railgun mode) instead of smear-cursor.nvim — running both at once would be two different animation systems fighting over the same cursor, so smear-cursor.nvim doesn't even load when vim.g.neovide is set. For background: Neovide has no background-image setting at all — two attempts to add one (neovide/neovide#2419, #3067) were both closed as abandoned, most recently in October 2025; the feature request itself (neovide/neovide#342) is still open. vim.g.neovide_opacity (set to 0.9) is the closest real substitute — it makes the whole window translucent, so on a compositing window manager, whatever's behind it (your desktop wallpaper, if Neovide isn't covering the whole screen) blends through. Adjust or remove it in init.lua to taste.

Once installed, launch the desktop app with neovide from a terminal — if that command isn't found right after setup, open a new shell first (a fresh rustup install updates PATH via shell startup files, which the setup script's own shell won't have re-read).

Editor basics

• Relative + absolute line numbers, system clipboard integration (unnamedplus), persistent undo, smart-case search, always-on sign column.
• Tab width: 4, using real tab characters — not expanded to spaces.
• c/cpp/javascript/typescript indentation uses Neovim's own built-in per-filetype indent logic (cindent for c/cpp, the bundled JS/TS indent scripts for the rest) rather than treesitter's indent module — treesitter's indent is known to be unreliable for these specifically (inconsistent brace placement, phantom extra indent on nested blocks), more so since the nvim-treesitter branch this config uses is frozen upstream (see Known quirks). css/json are also curly-brace languages that can hit the same issue — worth disabling there too if it comes up.
• Comments don't auto-continue onto a new line when the current line has real code on it — pressing Enter or o/O there starts a plain new line. On a comment-only line, Enter continues it with the same marker (//, #, or --); pressing Enter a second time with nothing typed breaks out instead of continuing again, clearing that line — same convention Vim itself has always used for this.
• Bracket/quote pairs auto-close as you type: (), {}, [], "", ''.
• True color, rounded borders on floating windows (hover, LspInfo, Mason, etc. — Neovim 0.11+), styled window separators.
• OSC 52 clipboard support, so yank/paste works correctly over SSH.

General keymaps

Key	Mode	Action
<Esc>	Normal	Clear search highlight
<leader>p	Normal	Force inline paste (paste as characters at cursor, ignoring line-wise register type)
p / P	Visual	Paste over selection without clobbering the unnamed register
J / K	Visual	Move selected lines down / up
<A-j> / <A-k>	Normal/Insert/Visual	Move current line (or selection) down / up
<leader>cb	Normal	Clear the current line's content, leaving it blank in place (doesn't delete the line itself)
gcc / gc{motion}	Normal	Toggle comment on the current line / over a motion (e.g. gcip for a paragraph) — Neovim's native 0.10+ commenting, untouched
gc	Visual	Toggle comment on the selection
<leader>c/	Normal/Visual	Same toggle as gcc/gc above, as a second which-key-discoverable entry point under the "Comments" group
<C-s>	Normal/Visual/Insert	Save file
<C-h/j/k/l>	Normal	Move to left/lower/upper/right window
<leader>sv / <leader>sh	Normal	Split vertically / horizontally
<leader>se	Normal	Equalize split sizes
<leader>sx	Normal	Close current split

Look & feel

• Theme: vscode.nvim (dark variant, VS Code Dark+ palette), on a near-black #090909 background (explorer, tabs, statusline and popups use near-black shades too, not VS Code's grays), with macros in Visual Studio's muted purple (#BEB7FF) and custom tinted backgrounds for error/warn/info/hint diagnostic virtual lines. lualine uses the plugin's own vscode theme.
• Cursor animation: an animated cursor trail in both frontends, via different mechanisms — see Terminal vs. desktop (Neovide) for which plugin does what and why.
• Dashboard: alpha-nvim start screen with quick actions — find file, recent files, live grep, new file, edit config, quit.
• Statusline: lualine, styled with true Powerline arrow separators (the seamless, edge-to-edge kind — between sections, a thinner version between components within a section). Left to right:
  • Mode, plus a macro-recording indicator (● REC @<register>) that only appears while a macro is actually being recorded.
  • Git branch and a diff summary (added/changed/removed), grouped together as one git cluster instead of being split across the line.
  • File-type icon fused directly to the filename with no separator between them — it reads as one unit rather than a boxed-off icon — plus a ● for unsaved changes and [RO] for read-only buffers.
  • Search count, diagnostics, the name(s) of any attached LSP client(s), and a word count that only shows up on prose filetypes (markdown, text, tex, commit messages).
  • Progress, cursor location, and the file's encoding/line-ending — but only when they differ from Neovim's own defaults (utf-8, unix), so a normal file doesn't clutter the line confirming the obvious.
  • A clock with the abbreviated weekday.
  • The Powerline glyphs live in the E0B0–E0B3 Unicode range, part of the same Nerd Font patch as the file/branch icons elsewhere in the statusline — if the icons render, the arrows will too. If they instead show as boxes or ?, it means the terminal's font setting isn't pointed at the patched font family specifically (Nerd Fonts rename it, e.g. "CaskaydiaCove Nerd Font" rather than plain "Cascadia Code"). Verify with echo -e "\ue0b0" in a terminal, outside Neovim entirely — if that's blank, fix the terminal's font setting rather than the config.
• Indent guides: indent-blankline — colored guide per indent level, plus the current lexical scope (the block your cursor is inside) is highlighted with its own guide color. The underline that used to mark the scope's start/end line is disabled (show_start/show_end = false) — just the colored guide remains.
• Inline color previews: nvim-colorizer shows hex/rgb color values with their actual color as a background.
• Notifications: nvim-notify replaces the default notification popups with floating, styled ones, positioned bottom-right.
• Prompts: dressing.nvim upgrades the rename prompt, breakpoint-condition prompt, and DAP path prompts to floating dialogs instead of plain command-line input.

Buffers & tabs (bufferline)

Each buffer tab shows its ordinal position number. Pinned buffers are always kept leftmost as a block.

Key	Action
<S-h> / <S-l>	Previous / next buffer (follows the order shown on screen, including any reordering)
<A-1> … <A-9> / <F1>–<F9>	Jump directly to the buffer at that position. <F5> and <F10> each pull double duty with the debugger (see Debugging) — they act as buffer jumps at rest, and hand themselves over to DAP for the duration of an active debug session.
<A-0> / <F10>	Jump to the last buffer
<A-,> / <A-.>	Move current buffer left / right (blocked from crossing into the pinned block — wraps to the other end instead)
<leader>bp	Toggle pin on current buffer
<leader>bx	Close every unpinned buffer with no unsaved changes (pinned buffers and anything modified are left alone)
<leader>bd	Close current buffer

Setting an explicit <F1> mapping here also overrides Neovim's built-in <F1>-opens-help default — any explicit keymap for a key always takes precedence over Neovim's default for it.

Text search (Telescope)

Key	Action
<leader>ff	Find files
<leader>fw	Live grep
<leader>fb	List open buffers
<leader>fh	Search help tags
<leader>fr	Recent files

File explorer (nvim-tree)

<leader>e toggles the file explorer sidebar (right side). On top of nvim-tree's own defaults (c/x/p to copy/cut/paste, m to mark, d to delete, etc.), three custom commands:

Key	Action
gP	Paste, resolving every naming collision in that paste with one pattern/replacement (Vim regex — same as :s///) instead of nvim-tree's normal one-at-a-time overwrite/rename prompt per conflicting file. Plain p is untouched. Only confirmed reliable for a single conflicting file at a time — see Known quirks.
gM	Copy every marked file/folder (mark with m, shown as a star) into the directory under the cursor, applying that same pattern/replacement regex to every name unconditionally — not just on collision. Doesn't touch nvim-tree's clipboard at all; reads the mark list directly and shells out to cp -r to do the copying itself. Marks aren't auto-cleared afterward — toggle them off individually with m when done.
gC	Clear the copy/cut clipboard outright. Useful if it's holding a stale entry (a file since renamed, moved, or deleted), which otherwise pastes as ENOENT: no such file or directory until cleared and re-copied fresh.

gP and gM both fail safely rather than silently: a stale mark (pointing at a since-deleted path) is skipped and cleaned up automatically instead of attempted, and a rename that would produce a no-op copy-onto-itself is skipped with a clear reason instead of surfacing a raw cp error.

LSP & code intelligence

Configured servers: clangd (C/C++), gopls (Go), omnisharp (C#), ts_ls (TS/JS), html, cssls, sqls (SQL — see Database (MariaDB)). The list lives in a single table, lua/config/lsp/servers.lua. Diagnostics render as virtual lines directly below the offending line (not inline virtual text), with the message's leading category prefix stripped; diagnostic underlines are off.

Key	Action
gd	Go to definition. Fuzzy picker with preview if there's more than one match (e.g. overloads); jumps directly for a single match. On an #include line, opens the header file directly — falls back to Vim's built-in gf if clangd can't resolve it.
gD	Go to declaration. Same #include-awareness and fallback as gd.
gr	Find all references, in a fuzzy picker with preview.
K	Hover documentation (renders Doxygen comments if present).
<leader>lr	Rename symbol (prompts for new name, safe against double-firing, refuses macros/namespaces — see note below)
<leader>la	Code actions at the cursor (normal mode) or over a selection (visual mode — needed for tweaks like Extract Function/Variable, which require an actual range). Also catches a diagnostic one line above/below the cursor, not just the exact line — see note below.
<leader>lt	Run clang-tidy --fix on the file directly (not through clangd — see Formatting and linting for why), then reload the buffer
<leader>lf	Format file (via clangd/LSP formatting — see Formatting and linting for the style used)
<leader>li	Show LSP client info
]d / [d	Jump to next/previous diagnostic, any severity
]e / [e	Jump to next/previous error
]w / [w	Jump to next/previous warning
]t / [t	Jump to next/previous tip (LSP's "Hint" severity)
<leader>cd	Generate a Doxygen-style comment block — see Documentation generation

:LspRestart and friends. Neovim 0.12 added a built-in :lsp command (:lsp enable, :lsp disable, :lsp restart, :lsp stop), and nvim-lspconfig responds by no longer registering its own :LspStart / :LspStop / :LspRestart / :LspInfo / :LspLog — so on 0.12 they simply don't exist (E492: Not an editor command). lua/config/lsp/commands.lua restores the old names as thin aliases over the built-ins:

Command	Runs
:LspRestart [client…]	:lsp restart [client…]
:LspStart [server…]	:lsp enable [server…]
:LspStop [server…]	:lsp disable [server…]
:LspInfo (also <leader>li)	:checkhealth vim.lsp
:LspLog	opens the LSP log in a new tab

Arguments are passed straight through and tab-complete (running clients for restart/stop, configured servers for start). On Neovim 0.11 and older there is no :lsp, nvim-lspconfig still provides the real commands itself, and the aliases stay out of the way.

On <leader>la coming up thin: clangd's code actions — and most of its clang-tidy checks — need real compiler flags (-std=, -I, defines) to do full semantic analysis. Without a compile_commands.json in the project, clangd falls back to guessed flags and the action list shrinks accordingly, often down to "No code actions available" everywhere. Generate one via CMake (-DCMAKE_EXPORT_COMPILE_COMMANDS=ON, then symlink or copy build/compile_commands.json to the project root) or bear for non-CMake projects.

<leader>lt and the same compile database: <leader>lt runs the standalone clang-tidy binary rather than going through clangd's code actions, so it never comes back "No code actions available" — it always runs. But it looks for that same compile_commands.json on its own (passed via clang-tidy's -p flag, found the same way as above), for the same underlying reason clangd wants one: without it, clang-tidy falls back to guessed flags and can miss checks that need real semantic analysis. It also uses --fix rather than --fix-errors, so it deliberately leaves the file untouched if clang-tidy hits real compiler errors, instead of forcing fixes onto code that doesn't currently compile.

<leader>lr and macros/namespaces: clangd doesn't support renaming macros or namespaces at all (clangd/clangd#1890, still open) — it's supposed to just reply with an error, but has a separate crash bug where it can take the whole clangd process down (SIGSEGV) while handling that rejection instead. <leader>lr checks with treesitter whether the cursor is on a macro or namespace's own definition line first and refuses locally if so, before clangd ever sees the request. That catches the common case, but not every one — renaming a macro from where it's used rather than defined still reaches clangd, since a macro usage is just plain text to treesitter. If clangd crashes anyway, :LspRestart brings it back; renaming a macro with :%s/\<old\>/new/g is the right tool regardless, since it's pure text substitution with no scope for clangd to resolve.

A second, unrelated way to come up empty: cursor position. <leader>la's underlying LSP request is normally scoped to diagnostics on the exact cursor line — easy to miss given that virtual_lines (see Look & feel) renders a diagnostic's message as an extra line directly below its own line, i.e. right where the next real line of code sits, making it look like it "belongs" to wherever the cursor already is. <leader>la now also catches a diagnostic one line above or below the cursor for exactly this reason, so this should come up much less than before — but for anything further away, jump to it first with ]e/]w/]t (see the diagnostic-navigation rows above) before requesting code actions.

Rule-of-five boilerplate

On a C++ buffer, <leader>oc / <leader>om insert the copy or move constructor + assignment operator pair, defaulted, for whichever class or struct the cursor is currently inside:

Foo(const Foo&) = default;
Foo& operator=(const Foo&) = default;

The enclosing class is found via Treesitter by walking up from the cursor — no need to have the class's own name line in view, and nested classes resolve to the innermost one. = default covers the overwhelming majority of real rule-of-five cases; delete it and write a body for the rare one that needs custom logic. C++ only (no move semantics in C, so this doesn't apply to .c buffers).

Autocompletion & snippets

nvim-cmp with LSP, snippet, buffer, and path sources.

• Ghost text: the top completion candidate previews inline after the cursor as you type — including path/directory completions (type ./ or /home/ and see what's in that directory before you finish typing it).
• <Tab> / <S-Tab>: cycle the completion menu when it's open; otherwise, jump forward/backward through snippet placeholders (e.g. clangd's function-argument placeholders after accepting a call like memcpy(...)) if you're inside one.
• <CR>: confirm the selected completion.
• <Up>/<Down>/<Left>/<Right>/<Esc>: close the completion menu, then perform the normal cursor/escape action.
• Snippet sessions auto-close once the cursor actually leaves their text (different line, or outside the placeholder's parentheses) — so Tab won't unexpectedly jump back into an old, already-finished snippet later on.
• SQL buffers use their own source list: dadbod's table names, LSP (sqls), snippets, and buffer words (no path source). See Database (MariaDB).

Documentation generation

neogen generates Doxygen-style comment skeletons — <leader>cd on/above a function drops in @brief/one @param per argument/@return matching that function's real signature. Fields are inserted as snippet placeholders, so <Tab>/<S-Tab> cycles through them the same way as any other snippet.

(There's no such thing as an actual "Doxygen language server" — clangd already understands Doxygen comment syntax natively for hover/signature help. This only handles generating the comment itself.)

Debugging (nvim-dap)

C/C++ (and Rust) debugging via codelldb, auto-installed by Mason on first use. UI (nvim-dap-ui) opens automatically when a session starts and closes when it ends; variable values show inline via virtual text.

Key	Action
F5 / <leader>dc	Continue / start debugging — F5 only while a session is already active; before that it's the "jump to buffer 5" shortcut, so start a session with <leader>dc or <leader>db, not F5
F10 / <leader>do	Step over — F10 only while a debug session is active; otherwise it's the "jump to last buffer" shortcut (see Buffers & tabs)
F11 / <leader>di	Step into
F12 / <leader>dO	Step out
<leader>db	Toggle breakpoint
<leader>dB	Conditional breakpoint
<leader>dr	Open the debug REPL
<leader>dl	Re-run the last debug configuration
<leader>dt	Terminate the session
<leader>du	Toggle the debug UI
<leader>dh	Hover the variable under the cursor

Default launch configs prompt for a path to the executable, or let you attach to a running process. ~/.config/nvim/lua/dap/configurations/cmake.lua additionally defines project-specific configs for CMake-built targets (build/tests/test_dynamic_library, build/demo/example_host) — this file is a template with this repo's specific binary names/paths and will need editing for a different project.

Terminal

Key	Action
<leader>tf	Floating terminal
<leader>th	Horizontal terminal (bottom)
<leader>tv	Vertical terminal (side)

Neovim's embedded terminal launches fish instead of your login shell, purely for its built-in inline "ghost text" suggestions for paths and command history (no config needed, accept with →/End) — a terminal-side equivalent of the completion ghost text above, since a :terminal buffer is a raw PTY that nvim-cmp has no visibility into. Your actual system login shell is untouched.

Git

gitsigns shows added/changed/removed lines in the sign column against the current git state.

Database (MariaDB)

Two separate tools do two separate jobs here:

• Connection and queries: vim-dadbod + vim-dadbod-ui. Browse a server's tables in a sidebar, run queries, read the results in a split. dadbod doesn't speak the database protocol itself; it shells out to the mariadb command-line client, which the setup script installs. That's the client only — no MariaDB server is installed or started, so you need one running somewhere (local or remote).
• Editing help: sqls, a language server for SQL (completion, hover, formatting, code actions). There is no MariaDB-specific language server; sqls's MySQL driver speaks MariaDB's wire protocol and SQL flavor, which covers it. Mason installs it on first launch — it builds from source with go install, so Go has to be on PATH (the setup script installs it).

The two are independent: dadbod works without sqls, and sqls works without dadbod.

Connecting

Key	Action
<leader>Du	Toggle the DB UI sidebar
<leader>Da	Add a connection (same as pressing A inside the sidebar)
<leader>Df	Find the current buffer in the sidebar — or, for a buffer that wasn't opened from the DB UI (a plain .sql file), pick the connection it should run against (:DBUIFindBuffer)
<leader>Dr	Rename the current query buffer or saved query (a buffer has to have been written once first)
<leader>Dl	Print the last query that ran and how long it took

<leader>Da asks for a URL and then a name:

mariadb://user:password@host:3306/dbname

Open the sidebar, pick a connection, and expand it to see its tables; expanding a table shows List, Columns, Indexes, and Count queries. Picking one writes the query into a buffer without running it; to write your own, choose New query under the connection. Either way, saving the buffer runs it (:w, and <C-s> works too), and dadbod-ui's own default <leader>S runs it without saving — the whole buffer, or only the visual selection if there is one. Results open in a split. Query buffers are temporary (they live in a temp folder and are cleared when Neovim quits) unless you save one with dadbod-ui's default <leader>W, which files it under the connection's Saved queries.

Details worth knowing:

• Include the database name in the URL: the sidebar lists the tables of that one database. For several databases on one server, add one connection each.
• localhost vs 127.0.0.1: the client treats localhost as "use the local Unix socket" and 127.0.0.1 as "use TCP". Use whichever your server is actually set up for.
• Special characters in the password have to be percent-encoded in the URL (@ → %40, / → %2F, and so on).
• Keeping the password out of the URL: leave it out and put user= / password= under [client] in ~/.my.cnf instead — the mariadb client reads credentials from there.
• Where connections are stored: ~/.local/share/db_ui/connections.json, in plain text, password included. That location is deliberately outside ~/.config/nvim and ~/.local/share/nvim, so re-running setup_neovim.sh (which wipes both) doesn't delete your connections. Nothing with credentials is ever written into the config files themselves.
• Why mariadb:// and not mysql://: dadbod has a dedicated MariaDB adapter that runs the mariadb binary. The older mysql:// scheme runs mysql instead, which MariaDB 11+ only ships as a deprecated alias that prints a "Deprecated program name" warning on every call — noise that ends up in query results and table lists. The trade-off is that dadbod-completion's column-level completion covers only some schemes (mysql:// is one, mariadb:// isn't), which is why columns come from sqls (below). Stick to mysql:// for real MySQL servers.

Language server (sqls)

sqls starts automatically in sql/mysql buffers and works out of the box for keyword completion and formatting (<leader>lf). For table and column completion it has to connect to the database itself — it does not share dadbod's connections — and it reads that from its own config file, ~/.config/sqls/config.yml:

lowercaseKeywords: false
connections:
  - alias: local_mariadb
    driver: mysql        # MariaDB speaks the MySQL protocol
    proto: tcp
    host: 127.0.0.1
    port: 3306
    user: me
    passwd: secret
    dbName: mydb

The file holds a password in plain text, so chmod 600 ~/.config/sqls/config.yml. For a Unix-socket connection, swap the individual fields for a Go-MySQL DSN: dataSourceName: me:secret@unix(/run/mysqld/mysqld.sock)/mydb (the socket path varies by distro). After editing the file, :LspRestart restarts sqls so it picks the change up.

This file is deliberately not created by the setup script, so a half-filled template with a made-up password can't make sqls fail to connect on every start.

Completion and syntax

In SQL buffers, completion draws on dadbod's table names (from the connection the buffer is attached to), sqls, snippets, and words already in the buffer. Vim's built-in SQL syntax is switched to its MySQL dialect (Vim defaults to Oracle's), the closest built-in match for MariaDB.

Hex viewer

<leader>h toggles the current buffer between normal and hex-dump view (backed by xxd), rather than showing both simultaneously. That's deliberate: the hex dump is just ordinary buffer text under the hood, so editing it gets normal Neovim undo/redo for free, and nothing writes to disk until an explicit :w — same as any other file. A plugin doing a true live simultaneous hex+ASCII view was tried first, but it manages bytes with its own logic outside normal buffer editing, which is exactly why it had no undo at all.

The mapping also makes sure the buffer is actually loaded in binary mode before toggling (re-reading it with ++bin if not) — opening a real binary file without that causes Neovim to misinterpret raw bytes as text before xxd even runs, surfacing as a CONVERSION ERROR instead of a clean hex dump. Since that reload discards whatever's currently in the buffer, <leader>h refuses to run it if there are unsaved changes — save (or explicitly discard with :e!) first.

Formatting and linting

~/.clang-format and ~/.clang-tidy are both copied from config/ on every run, implementing a specific C/C++ coding style guide (naming conventions, Allman braces, real tabs, include ordering, and a curated set of modernize/cppcoreguidelines/bugprone clang-tidy checks — see the comments in each file for exactly which style guide section a given setting maps to, and config/cpp-style-guide.md — also copied, to ~/cpp-style-guide.md — for the guide itself). Both tools walk upward from the file being checked looking for their config file; since $HOME sits above every project, these act as your personal default for any project that doesn't ship its own .clang-format/.clang-tidy — a project's own file always takes precedence.

<leader>lf (LSP format) only consumes .clang-format — clangd's formatting is pure clang-format and has nothing to do with clang-tidy. .clang-tidy is picked up two separate ways: automatically by clangd for live diagnostics (clangd's clang-tidy integration is explicitly enabled via --clang-tidy, alongside --background-index so checks run against the whole project's semantic info rather than just what's open), and directly by <leader>lt, which shells out to the real clang-tidy --fix on the file instead of going through clangd. That's a deliberate difference, not an oversight: clangd filters code actions by LSP "kind", and clang-tidy fixes only ever surface from clangd as individual quickfix actions — one per diagnostic — never as a single batched "fix everything" action, because clangd doesn't implement the source.fixAll kind that would take (clangd/clangd#1446). Asking for that kind specifically is why this used to just return "No code actions available" no matter what the file contained. Running the actual clang-tidy binary sidesteps that entirely and does what the key was always meant to: fix everything the tool can in one pass. See the LSP table above for the compile-database caveat that governs how much either <leader>la or <leader>lt can actually catch.

Known quirks

• nvim-treesitter is pinned to its master branch, not the current upstream default (main). main is an incompatible rewrite that removed the nvim-treesitter.configs API this config (and most existing configs/plugins) are built on. master is kept frozen upstream specifically for this kind of backward compatibility.
• A Neovim 0.12 compatibility shim is included for master-branch treesitter: 0.12 changed query predicate/directive results to sometimes be a list of nodes instead of a single node, which master's legacy predicate handlers don't expect — this caused a "Decoration provider ... attempt to call method 'range'" error (most visible on markdown files). The shim normalizes results back to a single node before those handlers run. Purely cosmetic when unpatched (highlighting still worked) but noisy.
• nvim-cmp absorbs the <CR> mapping used for smart comment continuation as its own fallback, rather than it being called directly by Neovim. cmp.setup() runs after init.lua's top-level code, and per its own keymap-composition system, it wraps whatever <CR> mapping already existed as the function it calls when its completion menu isn't visible, instead of simply discarding it. Worth knowing if you ever add or change an insert-mode <CR> mapping here: it will run through cmp's fallback chain rather than being invoked directly, which also means direct buffer edits from inside it (e.g. nvim_set_current_line()) fail with E565 — express any change as keys to return instead.
• gP's regex-on-paste only handles single-file conflicts reliably. nvim-tree has a separate, differently-shaped dialog specifically for multi-file conflicts within one paste ("N file(s) already exist" / Rename (suffix) / Overwrite all / Skip all), which gP doesn't detect. gM (copying marked files with an unconditional regex) was built as the more reliable tool for renaming several files at once.
• gM's stale-mark cleanup depends on api.marks.toggle, a function name inferred from m's own behavior rather than confirmed in nvim-tree's documentation directly, so it's wrapped defensively — if it's wrong on a given nvim-tree version, a stale mark just won't auto-clear (still requires manually pressing m on it), without otherwise breaking gM.
• Smart comment continuation (<CR>) only recognizes //, #, and -- (C-family/JS/TS/Go, Python/bash/YAML/CMake, and Lua/SQL respectively) rather than being fully comment-syntax-agnostic — it computes the marker to repeat directly rather than deferring to Neovim's own 'comments'-option-driven logic, which would cover more comment styles but came with its own timing problems (see the <CR>/cmp entry above).