Neovim Packages and Plugin Management This document provides comprehensive guidance on using, creating, and managing Vim packages in Neovim. Packages are a structured way to organize plugins, enabling easier installation, update, and dependency management. --- Using Vim Packages A package is a directory containing one or more plugins. Advantages over regular plugins: Distributed as archives or version control repositories (git, mercurial). Isolated directories to prevent file conflicts. Can include multiple dependent plugins. Support start plugins (auto-loaded on startup) under pack//start/. Support opt plugins (loaded on demand via :packadd) under pack//opt/. Runtime Search Path Neovim searches for runtime files in: All paths specified in 'runtimepath'. All pack//start/ directories. Note: pack//start/ is not explicitly in 'runtimepath' and won’t appear in :set rtp. APIs: nvimlistruntimepaths() lists all runtime directories. nvimgetruntimefile() queries specific files/folders in the runtime path. --- Installing and Organizing Packages Example: Adding a package from a ZIP archive: Files might be structured as: On startup, plugins in pack//start/ are automatically loaded. Plugins in pack//opt/ are not loaded until explicitly commanded (:packadd). Load all packages manually with :packloadall. Files in optional plugins (opt) can be loaded conditionally (e.g., feature detection). Disabling plugin loading disables automatic loading of start packages (load-plugins option). --- Optional Plugins Use :packadd {plugin-name} to load optional plugins. Use :packadd! {plugin-name} in config for on-startup loading that respects --noplugin. --- Best Practices for File Placement Color schemes: Prefer placing in pack//opt (e.g., ~/.config/nvim/pack/mycolors/opt/dark/colors/verydark.vim). Filetype plugins: Place under pack//start for automatic availability unless multiple competing versions exist. The after directory can be used but is often unnecessary. --- Creating Vim Packages Organize unrelated plugins into separate packages. Distribution via archives or repositories (git preferred for easy updates). Typical package structure: Users can clone repository into ~/.local/share/nvim/site/pack. Use :helptags to generate help tags, allowing direct help access. Handling Dependencies Place shared functionality in a separate autoload directory under start packages, e.g.: --- Built-in Plugin Manager (vim.pack) Work in progress; uses a dedicated managed directory: $XDGDATAHOME/nvim/site/pack/core/opt Requires git ≥ 2.36 and plugin repositories following semver tags (v<major>.<minor>.<patch>). Plugins are managed exclusively within this directory. Key Functions and Workflows Adding plugins** (vim.pack.add()): Accepts a list of plugin specs (string URLs or detailed specs). Installs missing plugins (clone + checkout). Automatically loads them (via :packadd or custom loader). Installation is parallel but blocks until completion.