[Vim Directory Structure, Start-up and Debugging]

Tags: #vim #directory #structure #startup #debugging #debug

Vim Directory Structure, Start-up and Debugging.md

The vim documentation explains all the various steps that are gone through during ‘start-up’, see :h startup.

In short, Vim executes :runtime! plugin/**/*.vim meaning any directories listed in the runtime path (:h set runtimepath?) will be searched for a plugin sub-directory and all files ending in “.vim” will be sourced (in alphabetical order per directory).

Note: if you want to debug the start-up process: vim --startuptime some_log_filename.

~/.vim/autoload/... (:h autoload)
~/.vim/plugin/... (:h plugin)
~/.vim/ftplugin/... (:h ftplugin)
~/.vim/after/... (:h after-directory)

the `after` directory

The after directory is used by vim ‘users’ and by vim ‘plugin authors’ to override specific plugin configuration (that could be either ~/.vim/plugin/... or ~/.vim/ftplugin/...).

For example, the vim plugin author for vim-polyglot adds this file: ~/.vim/plugin/vim-polyglot/after/ftdetect/rspec.vim which overrides the filetype configuration for rspec files.

Where as a vim user might want to override the behaviour of a plugin they’re using (e.g. the FZF plugin) by adding the file ~/.vim/after/plugin/config/fzf.vim, and due to how vim loads ‘after’ scripts, that file would get loaded. Although it’s important to add a guard into the code to ensure it only executes if the FZF plugin actually is loaded (otherwise this after script could cause an error)…

" include guard; quit if fzf isn't loaded
if ! exists(':FZF')
    finish
endif

Debugging

To check a specific setting and who (i.e. which plugin or script) last modified it, use :verbose set <setting>?

For example, :verbose set shiftwidth? returns…

shiftwidth=2
      Last set from ~/.vimrc

You can also see what mappings have been configured using the map command.

For example, to see all mappings with the leader key…

:verbose map <leader>

x  \y            :Buffers<CR>
        Last set from ~/.vimrc
   \t            :FZF<CR>
        Last set from ~/.vimrc
        
n  \z            :ALEPrevious<CR>
        Last set from ~/.vimrc
n  \x            :ALENext<CR>
        Last set from ~/.vimrc

Note: see :h map-listing for the various modes (n = normal, x = visual, etc).

The same principle works with other mappings like <Ctrl-k> and <Ctrl-j…

:verbose map <c-k>

n  <C-K>         <Plug>MoveLineUp
        Last set from ~/.vim/plugged/vim-move/plugin/move.vim
v  <C-K>         <Plug>MoveBlockUp
        Last set from ~/.vim/plugged/vim-move/plugin/move.vim

:verbose map <c-j>

n  <NL>          <Plug>MoveLineDown
        Last set from ~/.vim/plugged/vim-move/plugin/move.vim
v  <NL>          <Plug>MoveBlockDown
        Last set from ~/.vim/plugged/vim-move/plugin/move.vim

Note: vim also has a debugger you can use vim -D ~/.vimrc (see reference below for details).

Lastly, there is a the -V<N> flag that sets the verbosity of vim output when starting up…

" >= 1  When the viminfo file is read or written.
" >= 2  When a file is ":source"'ed.
" >= 5  Every searched tags file and include file.
" >= 8  Files for which a group of autocommands is executed.
" >= 9  Every executed autocommand.
" >= 12 Every executed function.
" >= 13 When an exception is thrown, caught, finished, or discarded.
" >= 14 Anything pending in a ":finally" clause.
" >= 15 Every executed Ex command (truncated at 200 characters).

Note: see :h vbs for details.

Usage example: vim -V9 ~/.vimrc, but you can also write the output to a log file instead (pro tip: use the log file approach) such as vim -V9foo ~/.vimrc which will write the output to the log file foo.

[Vim Directory Structure, Start-up and Debugging]