Vim Plugin Overrides, Updating, and Out-of-Tree Overlays in Nixpkgs

Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added: ```nix { deoplete-fish = super.deoplete-fish.overrideAttrs (old: { dependencies = with super; [ deoplete-nvim vim-fish ]; }); } ``` Sometimes plugins require an override that must be changed when the plugin is updated. This can cause issues when Vim plugins are auto-updated but the associated override isn't updated. For these plugins, the override should be written so that it specifies all information required to install the plugin, and running `nix-shell -p vimPluginsUpdater --run vim-plugins-updater` doesn't change the derivation for the plugin. Manually updating the override is required to update these types of plugins. An example of such a plugin is `LanguageClient-neovim`. To add a new plugin, run `nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater add "[owner]/[name]"'`. **NOTE**: This script automatically commits to your git repository. Be sure to check out a fresh branch before running. Finally, there are some plugins that are also packaged in nodePackages because they have Javascript-related build steps, such as running webpack. Those plugins are not listed in `vim-plugin-names` or managed by `vimPluginsUpdater` at all, and are included separately in `overrides.nix`. Currently, all these plugins are related to the `coc.nvim` ecosystem of the Language Server Protocol integration with Vim/Neovim. ## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs} Run the update script with a GitHub API token that has at least `public_repo` access. Running the script without the token is likely to result in rate-limiting (429 errors). For steps on creating an API token, please refer to [GitHub's token documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token). ```sh nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater --github-token=mytoken' # or set GITHUB_TOKEN environment variable ``` Alternatively, set the number of processes to a lower count to avoid rate-limiting. ```sh nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater --proc 1' ``` If you want to update only certain plugins, you can specify them after the `update` command. Note that you must use the same plugin names as the `pkgs/applications/editors/vim/plugins/vim-plugin-names` file. ```sh nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater update "nvim-treesitter" "LazyVim"' ``` ## How to maintain an out-of-tree overlay of vim plugins ? {#vim-out-of-tree-overlays} You can use the updater script to generate basic packages out of a custom vim plugin list: ``` nix-shell -p vimPluginsUpdater --run vim-plugins-updater -i vim-plugin-names -o generated.nix --no-commit ``` with the contents of `vim-plugin-names` being for example: ``` repo,branch,alias pwntester/octo.nvim,, ``` You can then reference the generated vim plugins via: ```nix { myVimPlugins = pkgs.vimPlugins.extend ((pkgs.callPackage ./generated.nix { })); } ```

This section details how overrides are used for Vim plugins in nixpkgs, particularly for plugins with dependencies or custom build steps, giving the example of `deoplete-fish`. It highlights the importance of updating overrides and the special handling of plugins with Javascript build steps, like those in the `coc.nvim` ecosystem. It then explains how to update plugins in nixpkgs using the `vimPluginsUpdater` script with a GitHub API token to avoid rate-limiting, and how to update specific plugins. Finally, it describes how to maintain an out-of-tree overlay of vim plugins by generating basic packages from a custom plugin list.