From 0f7f1dade287bfd8270b0180f6c9da9c78ad601f Mon Sep 17 00:00:00 2001 From: Daniel Fainberg Date: Tue, 15 Sep 2026 13:31:06 +0200 Subject: [PATCH] docs(nvim): record why this is hand-rolled, not a distro MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit State the reason for nixvim over LazyVim/NvChad — lazy.nvim fetches and updates plugins at runtime, putting the editor outside the flake — along with what that costs in ergonomics, and that borrowing a distro's keymaps and defaults into this file remains open. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_015D4NsszUG7hy9ghKZ4nfhm --- modules/nvim.nix | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/modules/nvim.nix b/modules/nvim.nix index 64e35da..58a825f 100644 --- a/modules/nvim.nix +++ b/modules/nvim.nix @@ -1,8 +1,26 @@ # Neovim, configured declaratively via nixvim. The editor — plugins, LSP, # completion, keymaps — is defined here and pinned by the flake lock; nothing is -# downloaded at runtime, unlike an imperative distro (NvChad/LazyVim). The nixvim -# home-manager module that provides `programs.nixvim` is imported for consumers by -# `homeModules.default` in flake.nix, so this file only sets options. +# downloaded at runtime. The nixvim home-manager module that provides +# `programs.nixvim` is imported for consumers by `homeModules.default` in +# flake.nix, so this file only sets options. +# +# Why this rather than a distro (LazyVim, NvChad, AstroNvim): those drive +# lazy.nvim as a package manager, which git-clones plugins into +# ~/.local/share/nvim on first launch and updates them in place. The editor's +# actual contents would then live outside the flake — unpinned, unreproducible, +# and invisible to a rollback. +# +# That choice has a price, and it is paid in ergonomics. A distro ships hundreds +# of defaults other people already sanded smooth; this config does not. Rough +# edges surface one at a time, mid-task, and each gets fixed by hand here (see +# the `bd` and `Q` keymaps for two such fixes). Anyone extending +# this should expect that cost rather than be surprised by it. +# +# The middle path stays open: the objection is to lazy.nvim as a *runtime* +# package manager, not to a distro's ergonomics. Individual keymaps, option +# sets, and plugin configurations can be lifted from LazyVim & co. into this +# file, and nixvim installs any plugin set declaratively. Borrow freely — just +# keep the installation declarative. # # Consumer knobs (the option-with-default contract): `local.nvim.enable` to opt # out wholesale, `local.nvim.colorscheme` to swap theme in one line, and