doc/languages-frameworks/vim.section.md

   1 # Vim {#vim}
   2
   3 Both Neovim and Vim can be configured to include your favorite plugins
   4 and additional libraries.
   5
   6 Loading can be deferred; see examples.
   7
   8 At the moment we support two different methods for managing plugins:
   9
  10 - Vim packages (*recommended*)
  11 - vim-plug (vim only)
  12
  13 ## Custom configuration {#custom-configuration}
  14
  15 Adding custom .vimrc lines can be done using the following code:
  16
  17 ```nix
  18 vim_configurable.customize {
  19   # `name` optionally specifies the name of the executable and package
  20   name = "vim-with-plugins";
  21
  22   vimrcConfig.customRC = ''
  23     set hidden
  24   '';
  25 }
  26 ```
  27
  28 This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`.
  29 You can also omit `name` to customize Vim itself. See the
  30 [definition of `vimUtils.makeCustomizable`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-utils.nix#L408)
  31 for all supported options.
  32
  33 For Neovim the `configure` argument can be overridden to achieve the same:
  34
  35 ```nix
  36 neovim.override {
  37   configure = {
  38     customRC = ''
  39       # here your custom configuration goes!
  40     '';
  41   };
  42 }
  43 ```
  44
  45 If you want to use `neovim-qt` as a graphical editor, you can configure it by overriding Neovim in an overlay
  46 or passing it an overridden Neovim:
  47
  48 ```nix
  49 neovim-qt.override {
  50   neovim = neovim.override {
  51     configure = {
  52       customRC = ''
  53         # your custom configuration
  54       '';
  55     };
  56   };
  57 }
  58 ```
  59
  60 ## Managing plugins with Vim packages {#managing-plugins-with-vim-packages}
  61
  62 To store your plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:
  63
  64 ```nix
  65 vim_configurable.customize {
  66   vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
  67     # loaded on launch
  68     start = [ youcompleteme fugitive ];
  69     # manually loadable by calling `:packadd $plugin-name`
  70     # however, if a Vim plugin has a dependency that is not explicitly listed in
  71     # opt that dependency will always be added to start to avoid confusion.
  72     opt = [ phpCompletion elm-vim ];
  73     # To automatically load a plugin when opening a filetype, add vimrc lines like:
  74     # autocmd FileType php :packadd phpCompletion
  75   };
  76 }
  77 ```
  78
  79 `myVimPackage` is an arbitrary name for the generated package. You can choose any name you like.
  80 For Neovim the syntax is:
  81
  82 ```nix
  83 neovim.override {
  84   configure = {
  85     customRC = ''
  86       # here your custom configuration goes!
  87     '';
  88     packages.myVimPackage = with pkgs.vimPlugins; {
  89       # see examples below how to use custom packages
  90       start = [ ];
  91       # If a Vim plugin has a dependency that is not explicitly listed in
  92       # opt that dependency will always be added to start to avoid confusion.
  93       opt = [ ];
  94     };
  95   };
  96 }
  97 ```
  98
  99 The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
 100
 101 ```nix
 102 {
 103   packageOverrides = pkgs: with pkgs; {
 104     myVim = vim_configurable.customize {
 105       # `name` specifies the name of the executable and package
 106       name = "vim-with-plugins";
 107       # add here code from the example section
 108     };
 109     myNeovim = neovim.override {
 110       configure = {
 111       # add code from the example section here
 112       };
 113     };
 114   };
 115 }
 116 ```
 117
 118 After that you can install your special grafted `myVim` or `myNeovim` packages.
 119
 120 ### What if your favourite Vim plugin isn’t already packaged? {#what-if-your-favourite-vim-plugin-isnt-already-packaged}
 121
 122 If one of your favourite plugins isn't packaged, you can package it yourself:
 123
 124 ```nix
 125 { config, pkgs, ... }:
 126
 127 let
 128   easygrep = pkgs.vimUtils.buildVimPlugin {
 129     name = "vim-easygrep";
 130     src = pkgs.fetchFromGitHub {
 131       owner = "dkprice";
 132       repo = "vim-easygrep";
 133       rev = "d0c36a77cc63c22648e792796b1815b44164653a";
 134       sha256 = "0y2p5mz0d5fhg6n68lhfhl8p4mlwkb82q337c22djs4w5zyzggbc";
 135     };
 136   };
 137 in
 138 {
 139   environment.systemPackages = [
 140     (
 141       pkgs.neovim.override {
 142         configure = {
 143           packages.myPlugins = with pkgs.vimPlugins; {
 144           start = [
 145             vim-go # already packaged plugin
 146             easygrep # custom package
 147           ];
 148           opt = [];
 149         };
 150         # ...
 151       };
 152      }
 153     )
 154   ];
 155 }
 156 ```
 157
 158 ### Specificities for some plugins
 159 #### Treesitter
 160
 161 By default `nvim-treesitter` encourages you to download, compile and install
 162 the required Treesitter grammars at run time with `:TSInstall`. This works
 163 poorly on NixOS.  Instead, to install the `nvim-treesitter` plugins with a set
 164 of precompiled grammars, you can use `nvim-treesitter.withPlugins` function:
 165
 166 ```nix
 167 (pkgs.neovim.override {
 168   configure = {
 169     packages.myPlugins = with pkgs.vimPlugins; {
 170       start = [
 171         (nvim-treesitter.withPlugins (
 172           plugins: with plugins; [
 173             nix
 174             python
 175           ]
 176         ))
 177       ];
 178     };
 179   };
 180 })
 181 ```
 182
 183 To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars`.
 184
 185 ## Managing plugins with vim-plug {#managing-plugins-with-vim-plug}
 186
 187 To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
 188 plugins the following example can be used:
 189
 190 ```nix
 191 vim_configurable.customize {
 192   vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
 193     # loaded on launch
 194     plug.plugins = [ youcompleteme fugitive phpCompletion elm-vim ];
 195   };
 196 }
 197 ```
 198
 199 Note: this is not possible anymore for Neovim.
 200
 201
 202 ## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs}
 203
 204 Nix expressions for Vim plugins are stored in [pkgs/applications/editors/vim/plugins](https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/editors/vim/plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`./update.py`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/update.py). This creates a [generated.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-plugin-names). Plugins are listed in alphabetical order in `vim-plugin-names` using the format `[github username]/[repository]@[gitref]`. For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
 205
 206 After running `./update.py`, if nvim-treesitter received an update, also run [`nvim-treesitter/update.py`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/update.py) to update the tree sitter grammars for `nvim-treesitter`.
 207
 208 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:
 209
 210 ```nix
 211 deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
 212   dependencies = with super; [ deoplete-nvim vim-fish ];
 213 });
 214 ```
 215
 216 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 `./update.py` 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`.
 217
 218 To add a new plugin, run `./update.py --add "[owner]/[name]"`. **NOTE**: This script automatically commits to your git repository. Be sure to check out a fresh branch before running.
 219
 220 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 `update.py` 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.
 221
 222 ## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs}
 223
 224 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).
 225
 226 ```sh
 227 GITHUB_API_TOKEN=my_token ./pkgs/applications/editors/vim/plugins/update.py
 228 ```
 229
 230 Alternatively, set the number of processes to a lower count to avoid rate-limiting.
 231
 232 ```sh
 233 ./pkgs/applications/editors/vim/plugins/update.py --proc 1
 234 ```
 235
 236 ## How to maintain an out-of-tree overlay of vim plugins ?
 237
 238 You can use the updater script to generate basic packages out of a custom vim
 239 plugin list:
 240
 241 ```
 242 pkgs/applications/editors/vim/plugins/update.py -i vim-plugin-names -o generated.nix --no-commit
 243 ```
 244
 245 with the contents of `vim-plugin-names` being for example:
 246
 247 ```
 248 repo,branch,alias
 249 pwntester/octo.nvim,,
 250 ```
 251
 252 You can then reference the generated vim plugins via:
 253
 254 ```nix
 255 myVimPlugins = pkgs.vimPlugins.extend (
 256   (pkgs.callPackage generated.nix {})
 257 );
 258 ```
 259