what should i set the environment variables $vim and $vimruntime to

Take you ever wonder what was The Offset of All Things™?

In other words: have y'all always wonder what Vim is doing when you start information technology? What files are sourced, why, and in what order? If you don't really care, I encourage you to reconsider your position. Knowing what Vim is doing at startup lets you speed it up, overwrites some defaults from the plugins you've installed, or even creates your ain filetypes. In brusque, information technology gives you even more power to customize Vim to your precise needs.

In this article, nosotros'll expect at two main ideas:

What happens during Vim's startup.
What are the runtime paths, what'south sourced from in that location, and when.

This commodity assumes that you have some advanced knowledge about Vim. If yous don't, you tin read my serial of article to learn Vim from the ground up. More specifically, a lot of knowledge in this article is built on Vim for Expert Users.

Have your headlamp and a proficient rope, we'll go exploring today many paths in our filesystems.

Vim'south Startup

When yous start Vim, many things happen behind the mantle before your favorite cursor is displayed on the screen. I describe here a simplified version, trying to underline the most of import steps.

Startup's Order

Here's what Vim will do when you lot run it:

Set the shell options (useful for the command :!, and for Vim'due south last).
Process the arguments given to the CLI. Buffers are created for all files given as arguments.
The value of the surroundings variable $VIMINIT (an Ex command) is executed.
Source the user's vimrc file.
The value of the environment variable $EXINIT (an Ex command) is executed.
If the choice "exrc" is gear up, Vim will try to observe and load a vimrc in the working directory. Go along in mind nonetheless that setting "exrc" is not secure.
Source filetypes, filetype plugins, and indent plugins. We'll see them beneath.
Source syntax highligting scripts.
Source plugin'southward scripts.
Load runtime's and plugin's scripts from the "after" binder.
Source the shada file (for Neovim) or the viminfo file (for Vim).
Execute the options given to Vim affecting the startup.

Let'south add more precisions:

If you want to run more than one control using $VIMINIT, you tin can split them with the symbol |.
Your vimrc file can be:
- In Vimscript for Vim (located at $HOME/.vimrc).
- In Lua or Vimscript for Neovim (located in $HOME/.config/nvim/init.vim, or $XDG_CONFIG_HOME/nvim/init.vim if $XDG_CONFIG_HOME is set).
Setting the option exrc can be dangerous: Vim can load potentially unsecure vimrc files you might have downloaded with other files.
You tin can use the selection -u <another_vimrc> when you run Vim in your terminal, to load another vimrc file instead of the default one. You tin too use of of these value instead of a vimrc for debug purposes:
- NORC - Don't load any vimrc but load your plugins.
- NONE - Don't load any vimrc nor plugins.
You can run whatever command using the options -c or +. For example: vim +"set shiftwidth=four|repeat 'hello'"

Profiling Vim's Startup

If Vim does terrible things at startup and you don't understand how to fix information technology, y'all can utilise the option -V to take more details about the startup process.

If you're startup is too slow and y'all desire to find the bottleneck, you tin can profile it with vim --startuptime <file>. Information technology volition write every files loaded (with timestamps) in the file <file>.

Special Environment Variables

Two surroundings variables are only defined when Vim starts:

$VIM - Used to locate various user files.
$VIMRUNTIME - Used to locate various support files for Vim. We'll speak more about the runtime below.

You can look at the value of these variable with the control :repeat $VIM for example. If yous define these environs variables in your shell, Vim won't overwrite them.

:help startup
:aid slow-first
:help 'shell'
:aid $VIM
:help $VIMRUNTIME

The Runtime Path

The runtime path is similar to the surroundings variable PATH in Unix-based systems. Vim will search in these paths to locate and source many different files during startup. To run across all of these paths, you can look at the value of the pick runtimepath, by running the control :set runtimepath?.

If you lot apply Vim, it's probable that y'all'll see $Dwelling house/.vim as the first path of the list. If you're a Neovim adept, information technology will be $HOME/.config/nvim.

The subdirectories of the runtime paths have different meanings according to their names. The Vimscript files inside these directories will be sourced at dissimilar times during startup, sometimes in different ways.

Important Runtime Paths

Hither are some of import runtime paths. Vim will parse them in this order:

For Vim:

$HOME/.vim
$VIM/vimfiles
$VIM/vimfiles/after
$Domicile/.vim/after

For Neovim:

$XDG_CONFIG_HOME/nvim (or ~/.config/nvim if $XDG_CONFIG_HOME is not fix)
$VIMRUNTIME
$XDG_CONFIG_HOME/nvim/after

It's important to notice that every runtime file in your user directory will exist sourced before the default ones. It means that Vim's defaults can overwrite your own runtime files. That'south why it's oft improve to put all your custom runtime files in the directory later on, sourced after everything. More than on that below.

Subdirectories of the Runtime Paths

Equally I was writing to a higher place, the configuration files in the runtime paths contains different things depending of the subdirectory they're in. Here'due south an overview of the near useful of these subdirectories, and how you can use them to customize Vim even further.

I encourage you to look at the default configuration files to understand the pregnant of these subdirectories. They are in the directory set in the variable $VIMRUNTIME. Don't forget that you can simply read the value of $VIMRUNTIME after launching Vim.

You can also detect examples in my own dotfiles.

Keep in mind that whatever subdirectory you lot'll create in your user runtime directory will be sourced earlier the gl

ftplugin

The subdirectory ftplugin (for filetype plugin) allow you to load pieces of configuration each fourth dimension you open a buffer with a specific filetype.

For example, let's say that you demand a couple of mappings simply for markdown files. Yous can:

Open a markdown file and verify that the filetype is indeed markdown, by running the command :set filetype?.
Create the file markdown.vim in $HOME/.vim/ftplugin for Vim, or $XDG_CONFIG_HOME/nvim/ftplugin for Neovim.
Add together options and mappings only for markdown files in there. For case: setlocal spell will enable spelling each time you open a markdown file.

You need to continue in heed, yet, that each time a buffer with the filetype markdown is created, the file ftplugin/markdown.vim will exist sourced. As a effect, you demand to brand sure that:

You reset whatsoever autocommand each fourth dimension the file is sourced (using an autocommand group and :au!).
Every mapping you're creating have the special statement <buffer>; for example, map <buffer> <leader>h echo "howdy".
Y'all're using setlocal instead of prepare to set options.
Yous're using the -buffer argument for any user command.

If you lot don't respect these rules, your pieces of configuration won't simply exist loaded for the buffers with a precise filetype, only for every buffer, globally.

autoload

The subdirectory autoload is also very useful. It lets you load your custom functions when you phone call them, instead of loading them when Vim starts. As a upshot, it can significantly speed upwardly Vim'due south startup. These functions need to begin with the path of the file they're written in, for Vim to know where to notice them when you call them.

For example, yous tin create a new file autoload/general.vim and apply it to declare a new custom function MyFunction. This part needs to be called general#MyFunction, because it'due south alleged in the file full general.vim. To call it, you can run :telephone call general#MyFunction.

You can too create subdirectories in the directory autoload. For example, you can create the file autoload/path/to/full general.vim. In that instance, you need to call your function path#to#general#MyFunction, describing the location of the file itself.

I encourage you to put all your custom functions in the "autoload" subdirectory.

syntax

The subdirectory syntax lets you create your own syntax files. They're used for code highlighting for example. You can commencement create a syntax grouping matching some regex, and and then you link your syntax group to highlight groups. These highlight groups will decide of the text's color displayed.

Vim supports many syntaxes by default (you can run into them in the directory $VIMRUNTIME/syntax), I never had to create my own syntax groups. It'southward however good to know that you lot tin can do it in instance you lot need it.

colors

You can create highlight groups in the subdirectory colors. Each file represents a different color scheme. Over again, y'all'll detect different examples in the directory $VIMRUNTIME/colors. To modify the color scheme of your highlighting, you tin can use the control :colour <my_color_scheme>.

ftdetect

Accept you ever dreamed to create your own filetypes? That'due south great, considering Vim is a dream machine. You can create your filetypes in the subdirectory "ftdetect".

For example, if y'all have a agglomeration of file with the extension "new" and you desire to create a filetype for them, yous can:

Create the file ftdetect/new.vim
Write au BufRead,BufNewFile *.new set filetype=new in it.

You can also link some filetypes with other ones. For example, I wanted the files with the extension .yaml.dist to take the yaml filetype. So I've:

Created the file ftdetect/yaml.dist.vim
Written autocmd BufNewFile,BufRead *.yml.dist set filetype=yaml in it.

compiler

In Vim, yous tin use the command :brand to run a specific compiler, depending of the filetype of your current buffer.

Nether the hood, Vim volition search a file named after the filetype of your electric current buffer, in the "compiler" directory. For example, if if you want to run the Golang compiler with precise options, you can create the file compiler/go.vim and add whatever you demand.

The Directory after

The subdirectory "after" is a special one. Yous tin think of it every bit some other runtime path in the runtime path, where yous can add the same subdirectories we saw to a higher place.

Everything in the subsequently directory will exist loaded later everything else. You tin can also see it when you lot look at the social club of the most important runtime path at the showtime of this section.

From there, you can override anything you lot desire: indentation, filetype plugins, or even the external plugins you've installed. For example, I tin override Lisp indentation by creating the file after/indent/lisp.vim and setting whatever options or variables I want to modify.

I didn't cover the subdirectory indent by the way, simply I'm sure yous tin can figure out its purpose.

The Runtime Command

If you want to source manually some files from your runtime path, you lot can employ the command :runtime <file>. For example, if you want to load every files from the colors subdirectory, you tin run :runtime colors/**/*.vim.

You can also employ :runtime! (with a bang !) to source everything.

:help 'runtimepath'
:aid autoload
:help ftplugin
:assistance syntax
:help new-filetype
:help after-directory

Disabling Runtime Files

Finally, if you want to debug one of your runtime files, you lot can disable some of them by sourcing these specific files:

:source $VIMRUNTIME/ftoff.vim - Disable the detection of filetypes
:source $VIMRUNTIME/ftplugin.vim - Enable ftplugin
:source $VIMRUNTIME/ftplugof.vim - Disable ftplugin
:source $VIMRUNTIME/indent.vim - Enable indentation
:source $VIMRUNTIME/indoff.vim - Disable indentation

The Startup Has Been Revealed

Now that you know what Vim's doing when it's starting, you can add your pieces of configuration in the expert runtime subdirectory for more flexibility. Yous tin can also try to speed up your startup if you observe it besides slow.

What did we run across in this article?

Vim load specific configuration files and environment variables at startup
You can use the options -Five or --startuptime to get more than details regarding Vim's startup.
The surround variable $VIM and $VIMRUNTIME are set during startup.
The subdirectories in the runtime path take a meaning, sometimes affecting directly how they're loaded at startup, and when.
The runtime path subdirectory "afterwards" is a special one: it's a runtime path as well (accepting the same subdirectories), and you can overwrite every other loaded config files in in that location.
The control :runtime allows y'all to manually load config files from your runtime paths.

I encourage you lot to experiment with all these configuration files to ameliorate your config. Personally, I observe the subdirectories "autoload" and "ftplugin" specially handy.

dahlincanconse.blogspot.com

Source: https://thevaluable.dev/vim-runtime-guide-example/