Skip to content

A tip for conveniently switching between Neovim configurations

Abstract

Introducing Neovim’s environment variable NVIM_APPNAME for switching between different configurations.

If you use Neovim as your text editor, then maybe my problem sounds familiar to you:

  • I’ve copied code snippets from various people and am hacking together the configuration that fits me perfectly, but it still has rough edges and some things are just broken because I don’t really know what I’m doing.
  • There are fantastic, pre-configured Neovim distributions like LazyVim, maintained by people who know what they’re doing, but they don’t include the customizations I picked up over the time.

Eventually, I will have my own tweaks and configurations sorted out, but I need a working—and not just working but beautiful and enabling—text editor today. I want to be able to switch between LazyVim (as my day-to-day text editor configuration) and my own custom configuration.

Today I learned about the environment variable NVIM_APPNAME that makes this much more convenient than what I’ve been doing until now.

Why this tip is great#

I manage my dotfiles (my configuration files) with GNU Stow. The way Stow creates symbolic links (also referred to as symlinks) makes it cumbersome to replace one ~/.config/nvim directory (for example, the LazyVim configuration) with another ~/.config/nvim directory (for example, my own custom tweaks).

I don’t want to accidentally move files from the one configuration into the other (due to the many symlinks), get error messages when I execute stow nvim, or have to constantly rename the ~/.config/nvim directory to something like ~/.config/nvim_backup.

What I learned today is that you can have multiple Neovim configurations installed in different locations—thus no more competing for the path ~/.config/nvim—and then, depending on whether the environment variable NVIM_APPNAME is set and to what value it is set, you can choose which of those configurations should be launched when you execute the nvim command. All without fiddling with stow or folder names.

How it works in principle#

You could have:

  • ~/.config/nvim for your default Neovim configuration (for example, your own configuration, maintained by yourself)
  • ~/.config/nvim-with-alternative-configuration for, for example, LazyVim

When you don’t want to launch Neovim with your default configuration (meaning the one in ~/.config/nvim) but with an alternative configuration, you just set NVIM_APPNAME to the name of the directory that stores the configuration (here, nvim-with-alternative-configuration). That directory must be within ~/.config (or rather, within $XDG_CONFIG_HOME).

In the documentation, it says:

setting $NVIM_APPNAME to "foo" before starting will cause Nvim to look for configuration files in $XDG_CONFIG_HOME/foo instead of $XDG_CONFIG_HOME/nvim.

Info

Each alternative configuration will have its own directory in ~/.local and ~/.cache to store its data so they don’t interfere with each other.

Example#

I will keep my own configuration in ~/.config/nvim.

I will download LazyVim to ~/.config/lazyvim (which means I will have to set NVIM_APPNAME to lazyvim). Like so:

git clone https://github.com/LazyVim/starter ~/.config/lazyvim

If you want Neovim to default to LazyVim for the entirety of the remaining shell session, you need to export the environment variable, like so:

export NVIM_APPNAME=lazyvim
nvim

You can simplify that to a one-liner (and omit the export) in case you want to launch your alternative configuration just this one time:

NVIM_APPNAME=lazyvim nvim

I prefer this latter option but combine it with aliases.

Info

By exporting NVIM_APPNAME, you’d have to execute unset NVIM_APPNAME if you wanted to go back to using the default ~/.config/nvim. Or close and re-open your terminal emulator, or start a new terminal session in any other way.

An alias for one-off commands#

You could, for example, add this to your ~/.zshrc file:

alias lvim="NVIM_APPNAME=lazyvim nvim"

Then you could use nvim for your default configuration and lvim for LazyVim.

Alternatively, if you want to type nvim to launch LazyVim (due to muscle memory), you can mask the nvim executable with an alias that’s also named nvim:

alias nvim="NVIM_APPNAME=lazyvim nvim"

If you then wanted to use the default configuration instead of LazyVim (that is, just nvim rather than NVIM_APPNAME=lazyvim nvim), you would then type this (a backslash before the alias):

\nvim

Info

If you write \ before an alias, that alias won’t be expanded.

That is, the command \nvim calls the actual nvim instead of executing the command NVIM_APPNAME=lazyvim nvim defined by the alias named nvim.

From zsh’s documentation:

if an alias is defined for the word foo, alias expansion may be avoided by quoting part of the word, e.g. \foo.

Final words#

Today I learned about Neovim’s environment variable NVIM_APPNAME. I can now use LazyVim as my text editor’s default configuration without having to rename directories or fiddling with Stow whenever I want to use my own Neovim configuration. Hopefully, you could learn something from this post too. In any case, be well.

Buy Me A Coffee

Comments