Neovim config tidying and commenting.

Author: notahat

config/nvim/init.lua

@@ -1,45 +1,27 @@
+-- Highlights of this config are:
+--
+-- * Plugin management with lazy.nvim
+-- * Automatic installation of language servers and formatters with mason.nvim
+-- * Language server support with nvim-lspconfig
+-- * Auto-formatting with null-ls
+-- * Completion with nvim-cmp
+-- * Syntax highlighting with nvim-treesitter
+--
+-- See the lua/plugin-specs directory for more.
+
 -- Don't load all our plugins and stuff in VSCode.
 if vim.g.vscode then
     return
 end
 
 local colorscheme = "nordfox"
 
--- These need to happen before plugins have loaded:
+-- We need to set all our options
 require("options").configure()
 
--- Install lazy.nvim from git if it's not already installed.
-local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
-if not vim.uv.fs_stat(lazypath) then
-    vim.notify("Installing lazy.nvim...")
-    vim.fn.system({
-        "git",
-        "clone",
-        "--filter=blob:none",
-        "https://github.com/folke/lazy.nvim.git",
-        "--branch=stable", -- latest stable release
-        lazypath,
-    })
-end
-
-vim.opt.rtp:prepend(lazypath)
-
--- Then we install and load the plugins.
-require("lazy").setup({
-    spec = {
-        -- Load everything from the lua/plugins directory.
-        import = "plugins",
-    },
-    change_detection = {
-        -- Don't notify whenever a config file changes. It's not helpful.
-        enabled = true,
-        notify = false,
-    },
-    install = {
-        -- Lazy tries to use this colorscheme during installation.
-        colorscheme = { colorscheme },
-    },
-})
+local plugins = require("plugins")
+plugins.install_lazy()
+plugins.install_and_load_plugins(colorscheme)
 
 -- And these need to happen after the plugins have loaded:
 vim.cmd.colorscheme(colorscheme)

config/nvim/lua/actions.lua

@@ -1,12 +1,18 @@
+-- This file wraps up a bunch of useful things that we want to use for key
+-- mappings into convenient functions.
+
 local gitsigns = require("gitsigns")
 local neo_tree = require("neo-tree.command")
 local telescope = require("telescope.builtin")
 
 return {
+    -- Open the current project on GitHub in a browsers.
     browse_on_github = function()
         vim.cmd("silent !gh browse")
     end,
 
+    -- Set the commit against which git differences are shown in both the
+    -- gutter (using Gitsigns) and the explorer (Neo-tree).
     choose_git_base = function()
         local callback = function(git_base)
             if git_base ~= nil then
@@ -25,10 +31,13 @@ return {
         telescope.grep_string({ search = vim.fn.expand("<cword>") })
     end,
 
+    -- Restore open windows and buffers that were previously saved with
+    -- save_session_and_quit.
     restore_session = function()
         vim.cmd.source("Session.vim")
     end,
 
+    -- Save open windows and buffers to a Session.vim file and quit.
     save_session_and_quit = function()
         -- Neo-tree buffers don't restore correctly, so close it first.
         neo_tree.execute({ action = "close" })
@@ -37,19 +46,24 @@ return {
         vim.cmd.quit()
     end,
 
+    -- Switch to the Files tab in Neo-tree, and focus on the file currently
+    -- being edited, expanding any necessary directories.
     show_current_file_in_neo_tree = function()
         neo_tree.execute({ action = "focus", source = "filesystem", reveal = true })
     end,
 
+    -- Open Neo-tree if it's closed, or close it if it's open.
     toggle_neo_tree = function()
         neo_tree.execute({ action = "focus", toggle = true })
     end,
 
+    -- Save every open buffer.
     write_all = function()
         vim.cmd.wall()
         vim.notify("Saved all files.")
     end,
 
+    -- Save every open buffer and quit Neovim.
     write_all_and_quit = function()
         vim.cmd("confirm xall")
     end,

config/nvim/lua/key-mappings.lua

@@ -1,16 +1,16 @@
-local bufdelete = require("bufdelete")
-local gitsigns = require("gitsigns")
-local refactoring = require("refactoring")
-local repeatable_move = require("nvim-treesitter.textobjects.repeatable_move")
-local telescope = require("telescope.builtin")
-local treesj = require("treesj")
-local which_key = require("which-key")
-local actions = require("actions")
-
 local map = vim.keymap.set
 
 -- Set up mappings available in all buffers.
 local function map_global_keys()
+    local actions = require("actions")
+    local bufdelete = require("bufdelete")
+    local gitsigns = require("gitsigns")
+    local refactoring = require("refactoring")
+    local repeatable_move = require("nvim-treesitter.textobjects.repeatable_move")
+    local telescope = require("telescope.builtin")
+    local treesj = require("treesj")
+    local which_key = require("which-key")
+
     -- Things I do often enough get a top-level mapping.
     map("", "<leader><leader>", telescope.find_files, { desc = "find files" })
     map("", "<leader>*", telescope.grep_string, { desc = "find word under cursor" })
@@ -25,7 +25,8 @@ local function map_global_keys()
     map("", "<leader>W", vim.cmd.close, { desc = "close window" })
     map("", "<leader>X", bufdelete.bufdelete, { desc = "close buffer" })
 
-    -- Make command keys do sensible things.
+    -- Make command keys do sensible things. There some stuff in kitty.conf to
+    -- tell Kitty to pass these through to Neovim.
     map("v", "<D-c>", '"*y', { desc = "copy to system clipboard" })
     map("", "<D-q>", actions.write_all_and_quit, { desc = "save all files and quit" })
     map("", "<D-s>", actions.write_all, { desc = "save all files" })
@@ -84,6 +85,8 @@ end
 local function map_lsp_keys(args)
     local buffer = args.buf
 
+    local telescope = require("telescope.builtin")
+
     map({ "n", "x", "o" }, "gd", telescope.lsp_definitions, { buffer = buffer, desc = "Go to defintion" })
     map({ "n", "x", "o" }, "gr", telescope.lsp_references, { buffer = buffer, desc = "Go to references" })
 

config/nvim/lua/plugins/completion.lua …fig/nvim/lua/plugin-specs/completion.luaconfig/nvim/lua/plugins/completion.lua renamed to config/nvim/lua/plugin-specs/completion.lua config/nvim/lua/plugins/completion.lua renamed to config/nvim/lua/plugin-specs/completion.lua

@@ -1,12 +1,17 @@
 return {
     -- Close buffers without closing the window that contains them.
+    --
     -- https://github.com/famiu/bufdelete.nvim
     "famiu/bufdelete.nvim",
 
     -- Handle opening file:line.
+    --
     -- https://github.com/bogado/file-line
     "bogado/file-line",
 
+    -- Show git differences in the gutter to the left of the file being edited,
+    -- and perform other basic git operations.
+    --
     -- https://github.com/lewis6991/gitsigns.nvim
     { "lewis6991/gitsigns.nvim", config = true },
 

config/nvim/lua/plugins/editing.lua config/nvim/lua/plugin-specs/editing.luaconfig/nvim/lua/plugins/editing.lua renamed to config/nvim/lua/plugin-specs/editing.lua

@@ -1,3 +1,24 @@
+-- I use a set of plugins to provide language server support, which gives me
+-- all sorts of good things:
+--
+-- * Great auto-completion
+-- * Hover documentation (hit K to bring it up)
+-- * Real-time errors and warnings
+-- * Quick navigation to defitions and references
+-- * Auto-formatting
+--
+-- The two key plugins are:
+--
+-- * nvim-lspconfig configures and runs language servers
+-- * null-ls configures and runs formatters
+--
+-- Underlying this, I use mason to install all language servers and formatters.
+--
+-- A pair of plugins ties all this this together.
+--
+-- * mason-lspconfig ties nvim-lspconfig to mason
+-- * mason-null-ls ties null-ls to mason
+
 -- mason installs language servers and formatters for us.
 --
 -- It puts them in ~/.local/share/NVIM_APPNAME/mason, where NVIM_APPNAME
@@ -30,7 +51,7 @@ local lspconfig_spec = {
     -- https://github.com/neovim/nvim-lspconfig
     "neovim/nvim-lspconfig",
     dependencies = { "hrsh7th/cmp-nvim-lsp", mason_lspconfig_spec },
-    config = require("plugins/lsp/lspconfig-config"),
+    config = require("plugin-specs.lsp.lspconfig-config"),
 }
 
 -- null-ls lets us auto-format files on save.
@@ -42,7 +63,7 @@ local null_ls_spec = {
     -- https://github.com/nvimtools/none-ls.nvim
     "nvimtools/none-ls.nvim",
     dependencies = { "nvim-lua/plenary.nvim" },
-    config = require("plugins/lsp/null-ls-config"),
+    config = require("plugin-specs.lsp.null-ls-config"),
 }
 
 -- mason-null-ls uses mason to install formatters configured in null-ls.

config/nvim/lua/plugins/lsp/init.lua config/nvim/lua/plugin-specs/lsp/init.luaconfig/nvim/lua/plugins/lsp/init.lua renamed to config/nvim/lua/plugin-specs/lsp/init.lua

@@ -2,23 +2,24 @@ return function()
     local lspconfig = require("lspconfig")
     local capabilities = require("cmp_nvim_lsp").default_capabilities()
 
+    local opts = { capabilities = capabilities }
     local dotfiles_env = os.getenv("DOTFILES_ENV")
 
     if dotfiles_env == "home" then
-        lspconfig.bashls.setup({ capabilities = capabilities })
-        lspconfig.eslint.setup({ capabilities = capabilities })
-        lspconfig.solargraph.setup({ capabilities = capabilities })
-        lspconfig.standardrb.setup({ capabilities = capabilities })
-        lspconfig.tsserver.setup({ capabilities = capabilities })
+        lspconfig.bashls.setup(opts)
+        lspconfig.eslint.setup(opts)
+        lspconfig.solargraph.setup(opts)
+        lspconfig.standardrb.setup(opts)
+        lspconfig.tsserver.setup(opts)
     end
 
     if dotfiles_env == "work" then
-        lspconfig.bashls.setup({ capabilities = capabilities })
-        lspconfig.eslint.setup({ capabilities = capabilities })
-        lspconfig.relay_lsp.setup({ capabilities = capabilities })
-        lspconfig.rubocop.setup({ capabilities = capabilities })
-        lspconfig.sorbet.setup({ capabilities = capabilities })
-        lspconfig.tsserver.setup({ capabilities = capabilities })
+        lspconfig.bashls.setup(opts)
+        lspconfig.eslint.setup(opts)
+        lspconfig.relay_lsp.setup(opts)
+        lspconfig.rubocop.setup(opts)
+        lspconfig.sorbet.setup(opts)
+        lspconfig.tsserver.setup(opts)
     end
 
     -- Set the diagnostic signs shown in the gutter to match lualine's.