Skip to content

Add safe Neovim configuration reload command #22

Description

@Unique-Divine

Goal

Allow the non-plugin parts of this Neovim configuration to be reloaded without
closing and restarting Neovim.

Provide a user command, proposed as :ConfigReload, that safely reapplies the
supported configuration files without attempting to re-run Lazy.nvim startup.

Background

Running command :source $MYVIMRC re-executes file nvim/init.lua. That file
calls function require("lazy").setup(...), and Lazy.nvim intentionally rejects
a second setup pass with:

Re-sourcing your config is not supported with lazy.nvim

Lazy.nvim supports command :Lazy reload {plugin} for individual plugins, but
that experimental command does not reload this repository's core configuration.

The desired workflow is:

  1. Edit and save a supported Neovim config file.
  2. Run command :ConfigReload.
  3. Observe the change without restarting Neovim.

Terminology

An autocommand is Neovim behavior triggered by an event, such as saving a
buffer or opening a file type.

An augroup is a named collection of autocommands. Creating an augroup with
clear = true removes its previous autocommands before adding replacements.
This prevents reloads from stacking duplicate actions, such as formatting the
same file multiple times after saving.

Proposed design

  • Keep Lazy.nvim bootstrap and function require("lazy").setup(...) as
    startup-only behavior in file nvim/init.lua.
  • Refactor reloadable configuration into modules with an idempotent setup()
    function. Running setup() multiple times must leave one effective version
    of each keymap, command, option, and autocommand.
  • Add command :ConfigReload, implemented outside the Lazy.nvim setup path.
  • Have command :ConfigReload reload only an explicit allowlist of safe core
    modules. Do not source file nvim/init.lua.
  • Clear and recreate reloadable autocommands through named augroups.
  • Define reloadable user commands with force = true, or otherwise avoid
    redefining them during a reload.
  • Print a concise confirmation listing the modules that were reloaded.

Initial reloadable candidates

  • File nvim/lua/core/vim.lua

    • Core options and keymaps.
    • Requires cleanup before it can be safely re-run because it defines user
      commands and has ungrouped FileType autocommands.
  • File nvim/lua/core/telescope.lua

    • Telescope setup and keymaps.
  • File nvim/lua/core/treesitter.lua

    • Already clears its UserTreesitter augroup and is a strong candidate.
  • File nvim/lua/core/cmp.lua

    • Completion setup.
  • File nvim/lua/core/comment.lua

    • Comment.nvim and context-commentstring setup.
  • File nvim/lua/core/harpoon.lua

    • Harpoon keymaps.

Excluded from the first implementation

  • File nvim/init.lua: must not be re-run because it initializes Lazy.nvim.
  • File nvim/lua/core/lazy-plugins.lua: contributes Lazy.nvim plugin specs.
  • File nvim/lua/core/lsp.lua: reconfigures LSP/Mason state and defines user
    commands; evaluate separately.
  • File nvim/lua/core/fmt.lua: its ungrouped BufWritePost autocommand would
    duplicate save-time formatting.
  • Files nvim/lua/core/debugger.lua,
    nvim/lua/core/debug-kickstart.lua, and nvim/lua/core/snippets.lua:
    plugin state requires separate idempotency review.

Acceptance criteria

  • Command :ConfigReload exists and does not call
    require("lazy").setup(...).
  • Running :ConfigReload twice produces no errors or duplicate behavior.
  • Reloading does not show Lazy.nvim's re-sourcing warning.
  • Reloadable autocommands belong to named augroups that are cleared before
    replacement.
  • Reloadable user commands can be redefined without errors.
  • Existing terminal keymap <Esc><Esc> still enters terminal-normal mode.
  • Existing keymap <leader>r still runs command :checktime.
  • The configuration documents which files :ConfigReload covers and which
    changes still require a Neovim restart.
  • Add a headless Neovim test or equivalent reproducible check that loads
    the reloadable configuration twice.

Non-goals

  • Reloading Lazy.nvim itself.
  • Installing, updating, or reloading arbitrary plugins.
  • Restarting active language servers unless a later follow-up explicitly adds
    that behavior.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions