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