🦈 NVIME: Modern NeoVim Configuration

NVIME is a pure Lua Neovim configuration built around Neovim 0.12+, the native vim.pack package manager, built-in LSP, and a compact plugin set.

Snapshots

Install from Source

1. Install Neovim 0.12 or newer.
2. (Optional) On Arch Linux, run arch-install.sh to install common dependencies.
3. Otherwise, install the required tools manually:

   # Fedora example
   sudo dnf install \
       ripgrep \
       nodejs \
       tree-sitter-cli \
       gcc \
       g++ \
       wget \
       unzip

4. Clone this repository into your config path:

   git clone https://github.com/MrZLeo/nvime ~/.config/nvim

5. Start Neovim:

   nvim

   Missing plugins are installed automatically on first launch.

Install from Release Artifacts

Tagged releases publish prebuilt artifacts for Linux and macOS:

• Linux: .tar.gz, .deb, .rpm
• macOS: .dmg

The .tar.gz and .dmg bundles contain:

• install.sh: installs the packaged config and downloaded plugins
• payload/config/nvim: the NVIME config
• payload/data/nvim/site/pack/core/opt: the bootstrapped vim.pack plugin directory

Installation defaults:

• Config: ${XDG_CONFIG_HOME:-$HOME/.config}/nvim
• Data: ${XDG_DATA_HOME:-$HOME/.local/share}/nvim

To install a release bundle from .tar.gz or .dmg:

1. Download the matching release artifact for your platform.
2. Extract or open it.
3. Run the installer:

   ./install.sh

4. Start Neovim:

   nvim

Linux package manager artifacts install the same bundle under /usr/share/nvime and expose nvime-install on PATH. They do not overwrite user config during apt or dnf installation. The packages recommend Neovim but do not require the distro package name, because nvime-install checks the actual nvim binary on PATH.

Debian/Ubuntu:

sudo apt install ./nvime-*.deb
nvime-install

Fedora/RHEL:

sudo dnf install ./nvime-*.rpm
nvime-install

The installer creates timestamped backups before replacing an existing install. It also checks that nvim is already installed and that the detected version is 0.12 or newer.

Useful installer options:

• ./install.sh --config-dir /path/to/nvim
• ./install.sh --data-dir /path/to/share/nvim
• ./install.sh --no-backup

Plugin Management

Plugin specs live in plugin/*.lua and are installed by vim.pack. Pinned revisions are stored in nvim-pack-lock.json.

Example plugin spec:

vim.pack.add({
    {
        src = "https://github.com/user/repo",
        version = vim.version.range("*"),
    },
})

Useful maintenance commands:

• :lua vim.pack.update() updates plugins with a confirmation buffer.
• :TSSyncParsers installs or updates the Tree-sitter parsers listed in plugin/02-treesitter.lua.

Key Bindings

Key Combination	Mode	Description
<C-h/j/k/l>	Normal	Navigate between windows
<C-h/j/k/l>	Terminal	Navigate between windows from terminal
<C-w>k	Normal	Split window above
<C-w>h	Normal	Split window left
<C-w>j	Normal	Split window below
<C-w>l	Normal	Split window right
<BackSpace>	Normal	Clear search highlighting
<Space><Space>	Normal	Save file
-	Normal	Open Oil file explorer
<Leader>ff	Normal	Find files
<Leader>fg	Normal	Live grep
<Leader>fb	Normal	List buffers
<Leader>fh	Normal	Help tags
<Leader>o	Normal	Toggle outline sidebar
gD	Normal	Go to declaration
gd	Normal	Go to definition (telescope)
K	Normal	Show hover information
gi	Normal	Go to implementation (telescope)
gr	Normal	Find references (telescope)
<Space>rn	Normal	Rename symbol
<Space>f	Normal	Code action
<Space>l	Normal	Show diagnostics (telescope)

Commands

• :CodeCompanion runs the inline assistant on the current buffer or selection.
• :CodeCompanionChat Toggle opens or hides the chat buffer.
• :Outline toggles the symbol outline window.
• :Clear deletes all hidden loaded buffers.
• :Spell toggles spell checking.
• :TSSyncParsers syncs the configured Tree-sitter parser set.

LSP

LSP configuration is centralized in plugin/zz-lsp.lua.

Current enabled servers:

local lsp_servers = {
    "clangd",
    "lua_ls",
    "ruff",
    "ty",
    "taplo",
    "texlab",
    "neocmake",
}

To add or remove a server, update that list and adjust any server-specific settings in the same file.

Current defaults include:

• Telescope-backed definition, implementation, reference, and diagnostics pickers
• Hover and floating diagnostics
• Inlay hints
• Format-on-save, except for filetypes explicitly skipped in plugin/zz-lsp.lua

Development checks

The normal push/PR checks validate shell scripts, Lua syntax, Lua formatting, and Lua linting:

bash -n scripts/*.sh
bash scripts/ci-lua-syntax.sh
stylua --check .
selene .

CI installs pinned versions of the Lua tooling with scripts/ci-install-lua-tools.sh. The workflow caches the Neovim install and Lua tooling directories between runs, keyed by OS, architecture, and tool version/configuration.

Release CI

GitHub Actions builds and publishes release artifacts for tags matching v*.*.*.*.

Release tags follow this format:

• v<neovim-major>.<neovim-minor>.<neovim-patch>.<nvime-revision>
• Example: v0.12.1.0

The first three fields track the upstream Neovim version. The final field is the NVIME release revision for that upstream version and starts at 0.

The release pipeline does three things:

1. Runs a headless smoke test on ubuntu-latest and macos-latest.
2. Builds platform-native artifacts after the smoke test passes.
3. Publishes the generated packages to the GitHub Release for that tag.

Release jobs cache the Neovim install directory and vim.pack data/cache directories. The plugin cache is keyed by OS, architecture, Neovim version, and nvim-pack-lock.json, with a same-version fallback so unchanged plugins can be reused when the lockfile changes.

The packaging job also preloads and verifies Blink native libraries before building artifacts, so packaged installs include the Rust fuzzy matcher for blink.cmp and the native matcher used by blink.pairs.

The workflow can be triggered in three ways:

1. Manually push a tag such as v0.12.1.0.
2. Let the monthly scheduled run check master; on the first day of each month at 00:00 UTC, if there are commits since the previous release tag, it creates the next tag automatically and publishes a release from that commit.
3. Run the workflow manually from GitHub Actions when you need to retry or debug a release.

Example release flow:

git tag v0.12.1.0
git push origin v0.12.1.0

Local helper scripts used by CI:

• scripts/ci-prepare-release.sh: resolves the release version and creates scheduled tags
• scripts/ci-smoke.sh: headless startup validation
• scripts/ci-install-nvim.sh: installs Neovim in CI
• scripts/ci-package.sh: bootstraps plugins and builds release artifacts
• scripts/install-bundle.sh: installs a packaged release locally