Neovim: Difference between revisions

From NixOS Wiki
m →‎See also: Link to Neovim heading on Tree-sitter page
Unabomberlive (talk | contribs)
Marked this version for translation
 
(13 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[https://neovim.io Neovim] is a fork of [[Vim]] aiming to improve the codebase, allowing for easier implementation of APIs, improved user experience and plugin implementation.
<languages/>
<translate>
<!--T:1-->
[https://neovim.io/ Neovim]<ref>Neovim Team, "Home - Neovim", Neovim Official Website, N/A. https://neovim.io/</ref> is a highly extensible and open source text editor that aims to improve upon and modernize the popular [[Vim]]<ref>NixOS Wiki, Vim. https://wiki.nixos.org/wiki/Vim</ref> editor. It's designed to be a drop-in replacement for Vim, maintaining compatibility with most Vim plugins and configurations while offering additional features and improvements. Neovim focuses on extensibility, usability, and performance.


Due to the large number of plugins, it is possible to extend and configure neovim to fit the exact needs of the user. Many users start working with neovim with a preconfigured neovim distribution (such as [https://www.lazyvim.org/ LazyVim], [https://astronvim.com/ AstroVim], [https://nvchad.com/ NVChad]) or use the preconfigured NixOS package for [[LunarVim]]. This way you can learn what is possible. Experienced users often advise to familiarize themselves with neovim and then create their own configuration from scratch.
<!--T:2-->
It introduces a powerful plugin architecture that allows for asynchronous plugin execution, which can significantly improve performance for certain operations. It also includes a built-in terminal emulator, allowing users to run shell commands directly within the editor. The project emphasizes code quality and maintainability, with a clean, well-documented codebase that makes it easier for developers to contribute.


For people who like the modal text editors in a terminal but don't want to spend so much time configuring it, the [[Helix]] editor might be the right choice.
== Installation == <!--T:3-->


== Installation ==
==== Using nix-shell ==== <!--T:4-->


=== System-wide ===
</translate>
<syntaxhighlight lang="bash" start="3">
nix-shell -p neovim
</syntaxhighlight>
<translate>
 
==== Using Global Configuration ==== <!--T:5-->
 
</translate>
<syntaxhighlight lang="text">
environment.systemPackages = [
  pkgs.neovim
];
</syntaxhighlight>
<translate>
 
<!--T:37-->
After modifying your configuration, apply the changes by running:


If you do not use Home Manager, you can use the following code in your NixOS configuration:
</translate>
<syntaxhighlight lang="bash">
sudo nixos-rebuild switch
</syntaxhighlight>
<translate>


<syntaxhighlight lang="nix">
==== Using Home Configuration ==== <!--T:6-->
programs.neovim = {
 
   enable = true;
</translate>
  defaultEditor = true;
<syntaxhighlight lang="text">
};
home.packages = [
   pkgs.neovim
];
</syntaxhighlight>
</syntaxhighlight>
<translate>


You can also manually add Neovim to your packages. This should only be used if the two version above do not work for you.
<!--T:38-->
After updating your configuration, apply the changes by running:


<syntaxhighlight lang="nix">
</translate>
environment.systemPackages = [ pkgs.neovim ];
<syntaxhighlight lang="bash">
home-manager switch
</syntaxhighlight>
</syntaxhighlight>
<translate>


=== With Home Manager ===
== Configuration == <!--T:7-->


[[Home Manager]] has a module for Neovim, which can be enabled via
==== Basic ==== <!--T:8-->


</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
<translate>
<!--T:39-->
# Global Configuration
</translate>
programs.neovim = {
  enable = true;
  defaultEditor = true;
};
<translate>
<!--T:40-->
# Home Configuration
</translate>
programs.neovim = {
programs.neovim = {
   enable = true;
   enable = true;
Line 36: Line 81:
};
};
</syntaxhighlight>
</syntaxhighlight>
<translate>


More information about the module can be found here: [https://nix-community.github.io/home-manager/options.xhtml#opt-programs.neovim.enable Home Manager Manual].
==== Advanced ==== <!--T:10-->
 
== Configuration ==
 
Neovim shares most of its configuration with Vim. See the [[Vim|Vim page]] for more details on the use of both.
=== System-wide ===
 
The NixOS module does not have an <code>extraConfig</code> option as the Home Manager module does.
Instead, you can use the <code>programs.neovim.configure</code> option as described [https://search.nixos.org/options?show=programs.neovim.configure&type=packages&query=neovim here].
 
The following example configures RC commands and enables the plugin <code>ctrlp</code> to support fuzzy file search (see [https://github.com/ctrlpvim/ctrlp.vim homepage] on how to use it)


</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
<translate>
<!--T:41-->
# Global Configuration
</translate>
programs.neovim = {
programs.neovim = {
   enable = true;
   enable = true;
  defaultEditor = true;
  viAlias = true;
  vimAlias = true;
   configure = {
   configure = {
     customRC = ''
     customRC = ''
Line 67: Line 111:
   };
   };
};
};
</syntaxhighlight>


To set Neovim as your default editor:
<translate>
 
<!--T:42-->
<syntaxhighlight lang="nix">
# Home Configuration
programs.neovim = {
# You have to add the line below to set it as the default editor:
  defaultEditor = true;
</translate>
};
environment.variables.EDITOR = "nvim";
</syntaxhighlight>
</syntaxhighlight>
<translate>


Further, the NixOS module does also expose options to automatically add <code>vi</code> and <code>vim</code> aliases.
== Tips and Tricks == <!--T:12-->
To use them, add the following to your NixOS configuration:


<syntaxhighlight lang="nix">
==== Location of Options ==== <!--T:13-->
programs.neovim = {
  viAlias = true;
  vimAlias = true;
};
</syntaxhighlight>
=== With Home Manager ===


The Home Manager module does not expose many configuration options. Therefore, the easiest way to get started is to use the [https://nix-community.github.io/home-manager/options.html#opt-programs.neovim.extraConfig extraConfig] option.
<!--T:43-->
You can copy your old config or directly load your default Neovim config via:
The home manager options are defined in the following [https://nix-community.github.io/home-manager/options.xhtml#opt-programs.neovim.enable Home Manager Options Manual]<ref>Nix Community, "Home Manager Option Search", Nix Community GitHub Pages, N/A. https://nix-community.github.io/home-manager/options.xhtml#opt-programs.neovim.enable</ref>.


<syntaxhighlight lang="nix">
<!--T:14-->
programs.neovim.extraConfig = lib.fileContents ../path/to/your/init.vim;
The global options are listed on [https://mynixos.com/search?q=nixpkgs%2Foption%2Fprograms.neovim MyNixOS]<ref>MyNixOS Team, "Search: nixpkgs/option/programs.neovim", MyNixOS, N/A. https://mynixos.com/search?q=nixpkgs%2Foption%2Fprograms.neovim</ref>.
</syntaxhighlight>


To use Neovim as your default editor, you can set the <code>EDITOR</code> [https://search.nixos.org/options?show=environment.variables&type=packages&query=environment.variables environmental variable] to "nvim" by adding the following to your NixOS configuration:
==== Package Variations ==== <!--T:15-->


<syntaxhighlight lang="nix">
<!--T:44-->
environment.variables.EDITOR = "nvim";
Have a look at the [https://github.com/nix-community/neovim-nightly-overlay Neovim Nightly Overlay]<ref>Nix Community, "neovim-nightly-overlay", GitHub, N/A. https://github.com/nix-community/neovim-nightly-overlay</ref> to install the most recent current nightly version of Neovim.
</syntaxhighlight>


The Home Manager module does also expose options to automatically add <code>vi</code> and <code>vim</code> aliases.
<!--T:16-->
To use them, add the following to your Home Manager configuration:
You can run the master version via the following command:
 
<syntaxhighlight lang="nix">
programs.neovim = {
  viAlias = true;
  vimAlias = true;
};
</syntaxhighlight>


==== Installing Plugins ====
<!--T:17-->
nix run "github:nix-community/neovim-nightly-overlay"


Plugins can be installed using the <code>programs.neovim.plugins</code> option.
==== Plugin Management ==== <!--T:21-->
You can add only the plugin, or the plugin with its corresponding config:


</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
programs.neovim.plugins = [
plugins = [
<translate>
  <!--T:49-->
# Example Plugin: nvim-tree-lua
</translate>
   pkgs.vimPlugins.nvim-tree-lua
   pkgs.vimPlugins.nvim-tree-lua
<translate>
  <!--T:50-->
# Example Plugin: vim-startify with configuration
</translate>
   {
   {
     plugin = pkgs.vimPlugins.vim-startify;
     plugin = pkgs.vimPlugins.vim-startify;
     config = "let g:startify_change_to_vcs_root = 0";
     config = "let g:startify_change_to_vcs_root = 0";
   }
   }
];
</syntaxhighlight>


If you only add the plugin, you can add the configuration as described above.
<translate>
  <!--T:51-->
# Example Plugin: nvim-colorizer-lua with Lua config
  # Due to how the runtimepath for Lua modules is processed, your configuration may require
  # packadd! plugin-name to require a module. A home-manager example:
</translate>
  {
    plugin = pkgs.vimPlugins.nvim-colorizer-lua;
    config = ''
      packadd! nvim-colorizer.lua
      lua << END
        require 'colorizer'.setup {
          '*';<translate> <!--T:52--> -- Highlight all files, but customize some others.</translate>
          '!vim';<translate> <!--T:53--> -- Exclude vim from highlighting.</translate>
        }
      END
    '';
  }
 
<translate>
  <!--T:54-->
# Example Plugin: nvim-treesitter with Lua config
</translate>
  {
    plugin = pkgs.vimPlugins.nvim-treesitter;
    config = ''
      packadd! nvim-treesitter
      lua <<EOF
        require'nvim-treesitter.configs'.setup {
          highlight = {
            enable = true,              <translate><!--T:55--> -- false will disable the whole extension</translate>
            disable = {},              <translate><!--T:56--> -- list of languages that will be disabled</translate>
          },
          incremental_selection = {
            enable = true,
            keymaps = {
              init_selection = "gnn",
              node_incremental = "grn",
              scope_incremental = "grc",
              node_decremental = "grm",
            },
          },
          textobjects = {
            select = {
              enable = true,
              lookahead = true,
              keymaps = {
                ["af"] = "@function.outer",
                ["if"] = "@function.inner",
                ["ac"] = "@class.outer",
                ["ic"] = "@class.inner",
              },
            },
          },
        }
      EOF
    '';
  }


An index of official packages can be found in on [https://search.nixos.org/packages?from=0&size=50&sort=relevance&type=packages&query=vimPlugins search.nixos.org].
<translate>
In addition to the official packages, there are several user maintained repositories, such as [https://github.com/m15a/flake-awesome-neovim-plugins awesome-neovim-plugins] or [https://github.com/NixNeovim/NixNeovimPlugins NixNeovimPlugins]. Plugins which are
  <!--T:57-->
not available in any of these repositories may be integrated using the <code>vimUtils.buildVimPlugin</code> function from Nixpkgs:
# Installing grammars for tree-sitter
  # Option 1: Install all grammar packages
  pkgs.vimPlugins.nvim-treesitter.withAllGrammars
 
  # Option 2: Install specific grammar packages
  # (pkgs.vimPlugins.nvim-treesitter.withPlugins (p: [ p.c p.java ]))


<syntaxhighlight lang="nix">
  <!--T:58-->
pkgs.vimUtils.buildVimPlugin {
# Option 3: Installing grammars without Nix
   pname = "whatever";
   # Installing grammar packages through the built-in command can lead to errors.
   version = "whatever";
   # The following Neovim command will install syntax highlighting for the C programming language: :TSInstall c
  src = builtins.fetchGit {
</translate>
    url = "https://github.com/example/whatever.git";
];
    ref = "whatever";
  };
  buildScript = ":";
}
</syntaxhighlight>
</syntaxhighlight>
<translate>


==== Frameworks ==== <!--T:18-->


<!--T:45-->
If you prefer not to configure your system manually, NixOS offers several predefined configurations and community-supported options. Here are a few of them:


== Tips and tricks ==
<!--T:19-->
 
* [https://www.lazyvim.org/ LazyVim]<ref>LazyVim Team, "LazyVim", LazyVim Official Website, N/A. https://www.lazyvim.org/</ref>
=== Neovim Nightly ===
 
You can also use the [https://github.com/nix-community/neovim-nightly-overlay Neovim Nightly Overlay] to install the most recent current nightly version of neovim.


You can run the master version via the following command:
<!--T:46-->
* [https://astronvim.com/ AstroVim]<ref>AstroNvim Team, "AstroNvim", AstroNvim Official Website, N/A. https://astronvim.com/</ref>


nix run "github:nix-community/neovim-nightly-overlay"
<!--T:47-->
* [https://nvchad.com/ NVChad]<ref>NvChad Team, "NvChad", NvChad Official Website, N/A. https://nvchad.com/</ref>


==== Developing / Building ====
<!--T:48-->
Another excellent option is [https://www.lunarvim.org/docs/installation LunarVim]<ref>LunarVim Team, "Installation", LunarVim Documentation, N/A. https://www.lunarvim.org/docs/installation</ref>. The development community describes it as "an IDE layer for Neovim with sane defaults." LunarVim includes an installer/updater for LSP modules and other features. It can be installed via the <code>lunarvim</code> package from <code>nixpkgs</code> and is started with the <code>lvim</code> command.


If you want to develop neovim, you may use
<!--T:20-->
The configuration for LunarVim is stored in <code>./config/lvim</code>.


  nix develop "github:nix-community/neovim-nightly-overlay"
== Troubleshooting == <!--T:59-->


to acquire a suitable environment.
== References == <!--T:27-->


=== Note on Lua plugins  ===
</translate>
 
Due to how the `runtimepath` for Lua modules is [https://github.com/nanotee/nvim-lua-guide#a-note-about-packages processed], your configuration may require <code>packadd! plugin-name</code> to require a module. A home-manager example:
 
<syntaxhighlight lang="nix">
programs.neovim = {
  plugins = [
    {
      plugin = pkgs.vimPlugins.nvim-colorizer-lua;
      config = ''
        packadd! nvim-colorizer.lua
        lua << END
require 'colorizer'.setup {
  '*'; -- Highlight all files, but customize some others.
  '!vim'; -- Exclude vim from highlighting.
}
END
      '';
    }
  ];
}
</syntaxhighlight>
 
== See Also ==
* [[Vim]]
* [[Tree-sitter#Neovim|Tree-sitter for Neovim]]


[[Category:Applications]]
[[Category:Applications]]
[[Category:Text Editor]]
[[Category:Text Editor]]

Latest revision as of 05:29, 16 August 2024

Neovim[1] is a highly extensible and open source text editor that aims to improve upon and modernize the popular Vim[2] editor. It's designed to be a drop-in replacement for Vim, maintaining compatibility with most Vim plugins and configurations while offering additional features and improvements. Neovim focuses on extensibility, usability, and performance.

It introduces a powerful plugin architecture that allows for asynchronous plugin execution, which can significantly improve performance for certain operations. It also includes a built-in terminal emulator, allowing users to run shell commands directly within the editor. The project emphasizes code quality and maintainability, with a clean, well-documented codebase that makes it easier for developers to contribute.

Installation

Using nix-shell

nix-shell -p neovim

Using Global Configuration

environment.systemPackages = [
  pkgs.neovim
];

After modifying your configuration, apply the changes by running:

sudo nixos-rebuild switch

Using Home Configuration

home.packages = [ 
  pkgs.neovim 
];

After updating your configuration, apply the changes by running:

home-manager switch

Configuration

Basic

# Global Configuration
programs.neovim = {
   enable = true;
   defaultEditor = true;
};

# Home Configuration
programs.neovim = {
  enable = true;
  extraConfig = ''
    set number relativenumber
  '';
};

Advanced

# Global Configuration
programs.neovim = {
  enable = true;
  defaultEditor = true;
  viAlias = true;
  vimAlias = true;
  configure = {
    customRC = ''
      set number
      set cc=80
      set list
      set listchars=tab:→\ ,space:·,nbsp:␣,trail:•,eol:¶,precedes:«,extends:»
      if &diff
        colorscheme blue
      endif
    '';
    packages.myVimPackage = with pkgs.vimPlugins; {
      start = [ ctrlp ];
    };
  };
};

# Home Configuration
# You have to add the line below to set it as the default editor:
environment.variables.EDITOR = "nvim";

Tips and Tricks

Location of Options

The home manager options are defined in the following Home Manager Options Manual[3].

The global options are listed on MyNixOS[4].

Package Variations

Have a look at the Neovim Nightly Overlay[5] to install the most recent current nightly version of Neovim.

You can run the master version via the following command:

nix run "github:nix-community/neovim-nightly-overlay"

Plugin Management

plugins = [
  # Example Plugin: nvim-tree-lua
  pkgs.vimPlugins.nvim-tree-lua

  # Example Plugin: vim-startify with configuration
  {
    plugin = pkgs.vimPlugins.vim-startify;
    config = "let g:startify_change_to_vcs_root = 0";
  }

  # Example Plugin: nvim-colorizer-lua with Lua config
  # Due to how the runtimepath for Lua modules is processed, your configuration may require 
  # packadd! plugin-name to require a module. A home-manager example:
  {
    plugin = pkgs.vimPlugins.nvim-colorizer-lua;
    config = ''
      packadd! nvim-colorizer.lua
      lua << END
        require 'colorizer'.setup {
          '*'; -- Highlight all files, but customize some others.
          '!vim'; -- Exclude vim from highlighting.
        }
      END
    '';
  }

  # Example Plugin: nvim-treesitter with Lua config
  {
    plugin = pkgs.vimPlugins.nvim-treesitter;
    config = ''
      packadd! nvim-treesitter
      lua <<EOF
        require'nvim-treesitter.configs'.setup {
          highlight = {
            enable = true,              -- false will disable the whole extension
            disable = {},               -- list of languages that will be disabled
          },
          incremental_selection = {
            enable = true,
            keymaps = {
              init_selection = "gnn",
              node_incremental = "grn",
              scope_incremental = "grc",
              node_decremental = "grm",
            },
          },
          textobjects = {
            select = {
              enable = true,
              lookahead = true,
              keymaps = {
                ["af"] = "@function.outer",
                ["if"] = "@function.inner",
                ["ac"] = "@class.outer",
                ["ic"] = "@class.inner",
              },
            },
          },
        }
      EOF
    '';
  }

  # Installing grammars for tree-sitter
  # Option 1: Install all grammar packages
  pkgs.vimPlugins.nvim-treesitter.withAllGrammars
  
  # Option 2: Install specific grammar packages
  # (pkgs.vimPlugins.nvim-treesitter.withPlugins (p: [ p.c p.java ]))

  # Option 3: Installing grammars without Nix
  # Installing grammar packages through the built-in command can lead to errors. 
  # The following Neovim command will install syntax highlighting for the C programming language: :TSInstall c
];

Frameworks

If you prefer not to configure your system manually, NixOS offers several predefined configurations and community-supported options. Here are a few of them:

Another excellent option is LunarVim[9]. The development community describes it as "an IDE layer for Neovim with sane defaults." LunarVim includes an installer/updater for LSP modules and other features. It can be installed via the lunarvim package from nixpkgs and is started with the lvim command.

The configuration for LunarVim is stored in ./config/lvim.

Troubleshooting

References

  1. Neovim Team, "Home - Neovim", Neovim Official Website, N/A. https://neovim.io/
  2. NixOS Wiki, Vim. https://wiki.nixos.org/wiki/Vim
  3. Nix Community, "Home Manager Option Search", Nix Community GitHub Pages, N/A. https://nix-community.github.io/home-manager/options.xhtml#opt-programs.neovim.enable
  4. MyNixOS Team, "Search: nixpkgs/option/programs.neovim", MyNixOS, N/A. https://mynixos.com/search?q=nixpkgs%2Foption%2Fprograms.neovim
  5. Nix Community, "neovim-nightly-overlay", GitHub, N/A. https://github.com/nix-community/neovim-nightly-overlay
  6. LazyVim Team, "LazyVim", LazyVim Official Website, N/A. https://www.lazyvim.org/
  7. AstroNvim Team, "AstroNvim", AstroNvim Official Website, N/A. https://astronvim.com/
  8. NvChad Team, "NvChad", NvChad Official Website, N/A. https://nvchad.com/
  9. LunarVim Team, "Installation", LunarVim Documentation, N/A. https://www.lunarvim.org/docs/installation