pyrox.dev
1# Vim {#vim}
2
3Both Neovim and Vim can be configured to include your favorite plugins
4and additional libraries.
5
6Loading can be deferred; see examples.
7
8At 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
15Adding custom .vimrc lines can be done using the following code:
16
17```nix
18vim_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
28This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`.
29You 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)
31for all supported options.
32
33For Neovim the `configure` argument can be overridden to achieve the same:
34
35```nix
36neovim.override {
37 configure = {
38 customRC = ''
39 # here your custom configuration goes!
40 '';
41 };
42}
43```
44
45If you want to use `neovim-qt` as a graphical editor, you can configure it by overriding Neovim in an overlay
46or passing it an overridden Neovim:
47
48```nix
49neovim-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
62To store your plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:
63
64```nix
65vim_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.
80For Neovim the syntax is:
81
82```nix
83neovim.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
99The 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
118After 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
122If one of your favourite plugins isn't packaged, you can package it yourself:
123
124```nix
125{ config, pkgs, ... }:
126
127let
128 easygrep = pkgs.vimUtils.buildVimPluginFrom2Nix {
129 name = "vim-easygrep";
130 src = pkgs.fetchFromGitHub {
131 owner = "dkprice";
132 repo = "vim-easygrep";
133 rev = "d0c36a77cc63c22648e792796b1815b44164653a";
134 sha256 = "0y2p5mz0d5fhg6n68lhfhl8p4mlwkb82q337c22djs4w5zyzggbc";
135 };
136 };
137in
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
158If your package requires building specific parts, use instead `pkgs.vimUtils.buildVimPlugin`.
159
160### Specificities for some plugins
161#### Treesitter
162
163By default `nvim-treesitter` encourages you to download, compile and install
164the required Treesitter grammars at run time with `:TSInstall`. This works
165poorly on NixOS. Instead, to install the `nvim-treesitter` plugins with a set
166of precompiled grammars, you can use `nvim-treesitter.withPlugins` function:
167
168```nix
169(pkgs.neovim.override {
170 configure = {
171 packages.myPlugins = with pkgs.vimPlugins; {
172 start = [
173 (nvim-treesitter.withPlugins (
174 plugins: with plugins; [
175 nix
176 python
177 ]
178 ))
179 ];
180 };
181 };
182})
183```
184
185To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars`.
186
187## Managing plugins with vim-plug {#managing-plugins-with-vim-plug}
188
189To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
190plugins the following example can be used:
191
192```nix
193vim_configurable.customize {
194 vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
195 # loaded on launch
196 plug.plugins = [ youcompleteme fugitive phpCompletion elm-vim ];
197 };
198}
199```
200
201Note: this is not possible anymore for Neovim.
202
203
204## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs}
205
206Nix 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`.
207
208After 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`.
209
210Some 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:
211
212```nix
213deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
214 dependencies = with super; [ deoplete-nvim vim-fish ];
215});
216```
217
218Sometimes 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`.
219
220To 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.
221
222Finally, 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.
223
224## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs}
225
226Run 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).
227
228```sh
229GITHUB_API_TOKEN=my_token ./pkgs/applications/editors/vim/plugins/update.py
230```
231
232Alternatively, set the number of processes to a lower count to avoid rate-limiting.
233
234```sh
235./pkgs/applications/editors/vim/plugins/update.py --proc 1
236```
237
238## How to maintain an out-of-tree overlay of vim plugins ?
239
240You can use the updater script to generate basic packages out of a custom vim
241plugin list:
242
243```
244pkgs/applications/editors/vim/plugins/update.py -i vim-plugin-names -o generated.nix --no-commit
245```
246
247with the contents of `vim-plugin-names` being for example:
248
249```
250repo,branch,alias
251pwntester/octo.nvim,,
252```
253
254You can then reference the generated vim plugins via:
255
256```nix
257myVimPlugins = pkgs.vimPlugins.extend (
258 (pkgs.callPackage generated.nix {})
259);
260```
261