pyrox.dev
1# Vim {#vim}
2
3Vim can be configured to include your favorite plugins and additional libraries.
4
5Loading can be deferred; see examples.
6
7At the moment we support two different methods for managing plugins:
8
9- Vim packages (*recommended*)
10- vim-plug (vim only)
11
12Right now two Vim packages are available: `vim` which has most features that require extra
13dependencies disabled and `vim-full` which has them configurable and enabled by default.
14
15::: {.note}
16`vim_configurable` is a deprecated alias for `vim-full` and refers to the fact that its
17build-time features are configurable. It has nothing to do with user configuration,
18and both the `vim` and `vim-full` packages can be customized as explained in the next section.
19:::
20
21## Custom configuration {#vim-custom-configuration}
22
23Adding custom .vimrc lines can be done using the following code:
24
25```nix
26vim-full.customize {
27 # `name` optionally specifies the name of the executable and package
28 name = "vim-with-plugins";
29
30 vimrcConfig.customRC = ''
31 set hidden
32 '';
33}
34```
35
36This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`.
37You can also omit `name` to customize Vim itself. See the
38[definition of `vimUtils.makeCustomizable`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-utils.nix#L408)
39for all supported options.
40
41
42## Managing plugins with Vim packages {#managing-plugins-with-vim-packages}
43
44To store your plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:
45
46```nix
47vim-full.customize {
48 vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
49 # loaded on launch
50 start = [
51 youcompleteme
52 fugitive
53 ];
54 # manually loadable by calling `:packadd $plugin-name`
55 # however, if a Vim plugin has a dependency that is not explicitly listed in
56 # opt that dependency will always be added to start to avoid confusion.
57 opt = [
58 phpCompletion
59 elm-vim
60 ];
61 # To automatically load a plugin when opening a filetype, add vimrc lines like:
62 # autocmd FileType php :packadd phpCompletion
63 };
64}
65```
66
67
68The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
69
70```nix
71{
72 packageOverrides =
73 pkgs: with pkgs; {
74 myVim = vim-full.customize {
75 # `name` specifies the name of the executable and package
76 name = "vim-with-plugins";
77 # add here code from the example section
78 };
79 myNeovim = neovim.override {
80 configure = {
81 # add code from the example section here
82 };
83 };
84 };
85}
86```
87
88After that you can install your special grafted `myVim` or `myNeovim` packages.
89
90### What if your favourite Vim plugin isn’t already packaged? {#what-if-your-favourite-vim-plugin-isnt-already-packaged}
91
92If one of your favourite plugins isn't packaged, you can package it yourself:
93
94```nix
95{ config, pkgs, ... }:
96
97let
98 easygrep = pkgs.vimUtils.buildVimPlugin {
99 name = "vim-easygrep";
100 src = pkgs.fetchFromGitHub {
101 owner = "dkprice";
102 repo = "vim-easygrep";
103 rev = "d0c36a77cc63c22648e792796b1815b44164653a";
104 hash = "sha256-bL33/S+caNmEYGcMLNCanFZyEYUOUmSsedCVBn4tV3g=";
105 };
106 };
107in
108{
109 environment.systemPackages = [
110 (pkgs.neovim.override {
111 configure = {
112 packages.myPlugins = with pkgs.vimPlugins; {
113 start = [
114 vim-go # already packaged plugin
115 easygrep # custom package
116 ];
117 opt = [ ];
118 };
119 # ...
120 };
121 })
122 ];
123}
124```
125
126If your package requires building specific parts, use instead `pkgs.vimUtils.buildVimPlugin`.
127
128## Managing plugins with vim-plug {#managing-plugins-with-vim-plug}
129
130To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
131plugins the following example can be used:
132
133```nix
134vim-full.customize {
135 vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
136 # loaded on launch
137 plug.plugins = [
138 youcompleteme
139 fugitive
140 phpCompletion
141 elm-vim
142 ];
143 };
144}
145```
146
147Note: this is not possible anymore for Neovim.
148
149
150## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs}
151
152Nix 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/utils/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).
153
154When the vim updater detects an nvim-treesitter update, it also runs [`nvim-treesitter/update.py $(nix-build -A vimPlugins.nvim-treesitter)`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/utils/update.py) to update the tree sitter grammars for `nvim-treesitter`.
155
156Some 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:
157
158```nix
159{
160 deoplete-fish = super.deoplete-fish.overrideAttrs (old: {
161 dependencies = with super; [
162 deoplete-nvim
163 vim-fish
164 ];
165 });
166}
167```
168
169Sometimes 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`.
170
171To 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.
172
173Finally, 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.
174
175## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs}
176
177Run 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).
178
179```sh
180nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater --github-token=mytoken' # or set GITHUB_TOKEN environment variable
181```
182
183Alternatively, set the number of processes to a lower count to avoid rate-limiting.
184
185```sh
186nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater --proc 1'
187```
188
189To update only specific plugins, list them after the `update` command:
190
191```sh
192nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater update "nvim-treesitter" "mini.nvim" "mini-nvim"'
193```
194
195The updater script accepts plugin arguments in different formats:
196
197- `"mini.nvim"` := The GitHub repository name, the raw plugin name, or the alias defined in `vim-plugin-names`.
198- `"mini-nvim"` := The normalized plugin name, which matches the attribute name generated in `generated.nix`
199
200## How to maintain an out-of-tree overlay of vim plugins? {#vim-out-of-tree-overlays}
201
202You can use the updater script to generate basic packages out of a custom vim
203plugin list:
204
205```
206nix-shell -p vimPluginsUpdater --run vim-plugins-updater -i vim-plugin-names -o generated.nix --no-commit
207```
208
209with the contents of `vim-plugin-names` being for example:
210
211```
212repo,branch,alias
213pwntester/octo.nvim,,
214```
215
216You can then reference the generated vim plugins via:
217
218```nix
219{
220 myVimPlugins = pkgs.vimPlugins.extend ((pkgs.callPackage ./generated.nix { }));
221}
222```
223