2021-01-01 17:45:43 +00:00
# Vim {#vim}
2016-06-25 19:36:44 +00:00
2018-09-09 08:45:45 +00:00
Both Neovim and Vim can be configured to include your favorite plugins
and additional libraries.
2017-01-30 17:27:44 +00:00
Loading can be deferred; see examples.
2016-06-25 19:36:44 +00:00
2022-06-25 17:35:48 +00:00
At the moment we support two different methods for managing plugins:
2018-09-09 08:45:45 +00:00
2022-07-08 05:22:52 +00:00
- Vim packages (*recommended*)
2022-09-01 22:53:55 +00:00
- vim-plug (vim only)
2016-06-25 19:36:44 +00:00
2022-12-04 10:18:38 +00:00
Right now two Vim packages are available: `vim` which has most features that require extra
dependencies disabled and `vim-full` which has them configurable and enabled by default.
::: {.note}
`vim_configurable` is a deprecated alias for `vim-full` and refers to the fact that its
build-time features are configurable. It has nothing to do with user configuration,
and both the `vim` and `vim-full` packages can be customized as explained in the next section.
:::
2021-06-05 19:22:45 +00:00
## Custom configuration {#custom-configuration}
2017-06-22 12:09:56 +00:00
Adding custom .vimrc lines can be done using the following code:
2019-07-15 00:13:34 +00:00
```nix
2022-12-04 10:18:38 +00:00
vim-full.customize {
2022-03-19 08:41:32 +00:00
# `name` optionally specifies the name of the executable and package
2017-06-22 12:09:56 +00:00
name = "vim-with-plugins";
vimrcConfig.customRC = ''
set hidden
'';
}
```
2019-07-15 00:13:34 +00:00
This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins` .
2022-03-19 08:41:32 +00:00
You can also omit `name` to customize Vim itself. See the
[definition of `vimUtils.makeCustomizable` ](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-utils.nix#L408 )
for all supported options.
2018-10-24 15:02:54 +00:00
2018-09-09 08:45:45 +00:00
For Neovim the `configure` argument can be overridden to achieve the same:
2019-07-15 00:13:34 +00:00
```nix
2018-09-09 08:45:45 +00:00
neovim.override {
configure = {
customRC = ''
# here your custom configuration goes!
'';
};
}
```
2019-07-15 00:13:34 +00:00
If you want to use `neovim-qt` as a graphical editor, you can configure it by overriding Neovim in an overlay
2022-07-08 05:22:52 +00:00
or passing it an overridden Neovim:
2019-01-05 12:58:00 +00:00
2019-07-15 00:13:34 +00:00
```nix
2019-01-05 12:58:00 +00:00
neovim-qt.override {
neovim = neovim.override {
configure = {
customRC = ''
# your custom configuration
'';
};
};
}
```
2021-06-05 19:22:45 +00:00
## Managing plugins with Vim packages {#managing-plugins-with-vim-packages}
2017-06-22 12:09:56 +00:00
2022-07-08 05:22:52 +00:00
To store your plugins in Vim packages (the native Vim plugin manager, see `:help packages` ) the following example can be used:
2017-06-22 12:09:56 +00:00
2019-07-15 00:13:34 +00:00
```nix
2022-12-04 10:18:38 +00:00
vim-full.customize {
2017-06-22 12:09:56 +00:00
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
start = [ youcompleteme fugitive ];
# manually loadable by calling `:packadd $plugin-name`
2019-07-15 00:13:34 +00:00
# however, if a Vim plugin has a dependency that is not explicitly listed in
# opt that dependency will always be added to start to avoid confusion.
2017-06-22 12:09:56 +00:00
opt = [ phpCompletion elm-vim ];
# To automatically load a plugin when opening a filetype, add vimrc lines like:
# autocmd FileType php :packadd phpCompletion
2018-09-09 08:45:45 +00:00
};
}
2017-06-22 12:09:56 +00:00
```
2018-12-24 12:13:59 +00:00
`myVimPackage` is an arbitrary name for the generated package. You can choose any name you like.
2018-09-20 07:05:33 +00:00
For Neovim the syntax is:
2018-09-09 08:45:45 +00:00
2019-07-15 00:13:34 +00:00
```nix
2018-09-09 08:45:45 +00:00
neovim.override {
configure = {
customRC = ''
# here your custom configuration goes!
'';
packages.myVimPackage = with pkgs.vimPlugins; {
# see examples below how to use custom packages
start = [ ];
2019-07-15 00:13:34 +00:00
# If a Vim plugin has a dependency that is not explicitly listed in
2018-12-24 12:13:59 +00:00
# opt that dependency will always be added to start to avoid confusion.
2018-09-09 08:45:45 +00:00
opt = [ ];
};
};
}
```
The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
2019-07-15 00:13:34 +00:00
```nix
2018-09-09 08:45:45 +00:00
{
packageOverrides = pkgs: with pkgs; {
2022-12-04 10:18:38 +00:00
myVim = vim-full.customize {
2018-10-24 15:02:54 +00:00
# `name` specifies the name of the executable and package
2018-09-09 08:45:45 +00:00
name = "vim-with-plugins";
# add here code from the example section
};
myNeovim = neovim.override {
configure = {
2022-07-08 05:22:52 +00:00
# add code from the example section here
2018-09-09 08:45:45 +00:00
};
};
};
}
```
After that you can install your special grafted `myVim` or `myNeovim` packages.
2021-06-05 19:22:45 +00:00
### What if your favourite Vim plugin isn’ t already packaged? {#what-if-your-favourite-vim-plugin-isnt-already-packaged}
2021-04-20 20:28:06 +00:00
If one of your favourite plugins isn't packaged, you can package it yourself:
2021-07-14 12:00:00 +00:00
```nix
2021-04-20 20:28:06 +00:00
{ config, pkgs, ... }:
let
2022-11-14 18:19:20 +00:00
easygrep = pkgs.vimUtils.buildVimPluginFrom2Nix {
2021-04-20 20:28:06 +00:00
name = "vim-easygrep";
src = pkgs.fetchFromGitHub {
owner = "dkprice";
repo = "vim-easygrep";
rev = "d0c36a77cc63c22648e792796b1815b44164653a";
doc: use sri hash syntax
The nixpkgs manual contains references to both sri hash and explicit
sha256 attributes. This is at best confusing to new users. Since the
final destination is exclusive use of sri hashes, see nixos/rfcs#131,
might as well push new users in that direction gently.
Notable exceptions to sri hash support are builtins.fetchTarball,
cataclysm-dda, coq, dockerTools.pullimage, elixir.override, and
fetchCrate. None, other than builtins.fetchTarball, are fundamentally
incompatible, but all currently accept explicit sha256 attributes as
input. Because adding backwards compatibility is out of scope for this
change, they have been left intact, but migration to sri format has been
made for any using old hash formats.
All hashes have been manually tested to be accurate, and updates were
only made for missing upstream artefacts or bugs.
2022-12-03 19:49:00 +00:00
hash = "sha256-bL33/S+caNmEYGcMLNCanFZyEYUOUmSsedCVBn4tV3g=";
2021-04-20 20:28:06 +00:00
};
};
in
{
environment.systemPackages = [
(
pkgs.neovim.override {
configure = {
packages.myPlugins = with pkgs.vimPlugins; {
start = [
vim-go # already packaged plugin
easygrep # custom package
];
opt = [];
};
# ...
};
}
)
];
}
```
2022-11-14 18:19:20 +00:00
If your package requires building specific parts, use instead `pkgs.vimUtils.buildVimPlugin` .
2023-03-27 20:39:11 +00:00
### Specificities for some plugins {#vim-plugin-specificities}
#### Treesitter {#vim-plugin-treesitter}
2021-07-14 12:00:00 +00:00
By default `nvim-treesitter` encourages you to download, compile and install
2022-07-08 05:22:52 +00:00
the required Treesitter grammars at run time with `:TSInstall` . This works
2021-07-14 12:00:00 +00:00
poorly on NixOS. Instead, to install the `nvim-treesitter` plugins with a set
of precompiled grammars, you can use `nvim-treesitter.withPlugins` function:
```nix
(pkgs.neovim.override {
configure = {
packages.myPlugins = with pkgs.vimPlugins; {
start = [
(nvim-treesitter.withPlugins (
plugins: with plugins; [
2022-10-30 05:33:40 +00:00
nix
python
2021-07-14 12:00:00 +00:00
]
))
];
};
};
})
```
2022-10-30 05:33:40 +00:00
To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars` .
2021-07-14 12:00:00 +00:00
2021-06-05 19:22:45 +00:00
## Managing plugins with vim-plug {#managing-plugins-with-vim-plug}
2018-09-20 07:05:33 +00:00
2018-09-20 07:20:11 +00:00
To use [vim-plug ](https://github.com/junegunn/vim-plug ) to manage your Vim
plugins the following example can be used:
2018-09-20 07:05:33 +00:00
2019-07-15 00:13:34 +00:00
```nix
2022-12-04 10:18:38 +00:00
vim-full.customize {
2018-09-20 07:05:33 +00:00
vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
# loaded on launch
plug.plugins = [ youcompleteme fugitive phpCompletion elm-vim ];
};
}
```
2022-09-01 22:53:55 +00:00
Note: this is not possible anymore for Neovim.
2018-09-20 07:05:33 +00:00
2021-06-05 19:22:45 +00:00
## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs}
2018-09-09 08:46:35 +00:00
2023-04-14 20:02:17 +00:00
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 ).
2019-07-14 23:38:00 +00:00
2022-10-30 05:33:40 +00:00
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` .
2022-02-16 14:55:43 +00:00
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:
2019-07-15 00:13:34 +00:00
2021-03-13 23:30:36 +00:00
```nix
2019-07-14 23:38:00 +00:00
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 `./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` .
2023-04-14 20:02:17 +00:00
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.
2018-09-09 08:46:35 +00:00
2022-09-01 22:53:55 +00:00
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.
2020-09-03 17:29:29 +00:00
2021-06-05 19:22:45 +00:00
## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs}
2020-10-28 20:47:00 +00:00
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
2022-02-16 14:55:43 +00:00
GITHUB_API_TOKEN=my_token ./pkgs/applications/editors/vim/plugins/update.py
2020-10-28 20:47:00 +00:00
```
Alternatively, set the number of processes to a lower count to avoid rate-limiting.
```sh
2022-02-16 14:55:43 +00:00
./pkgs/applications/editors/vim/plugins/update.py --proc 1
2020-10-28 20:47:00 +00:00
```
2023-03-27 20:39:11 +00:00
## How to maintain an out-of-tree overlay of vim plugins ? {#vim-out-of-tree-overlays}
2016-06-25 19:36:44 +00:00
2021-06-11 23:08:24 +00:00
You can use the updater script to generate basic packages out of a custom vim
plugin list:
2022-09-01 22:53:55 +00:00
2021-06-11 23:08:24 +00:00
```
pkgs/applications/editors/vim/plugins/update.py -i vim-plugin-names -o generated.nix --no-commit
```
2022-09-01 22:53:55 +00:00
with the contents of `vim-plugin-names` being for example:
2021-06-11 23:08:24 +00:00
```
repo,branch,alias
pwntester/octo.nvim,,
```
You can then reference the generated vim plugins via:
2022-09-01 22:53:55 +00:00
2021-06-11 23:08:24 +00:00
```nix
myVimPlugins = pkgs.vimPlugins.extend (
(pkgs.callPackage generated.nix {})
);
```
2016-06-25 19:36:44 +00:00