vim plugin directories priority

Question

On Debian plugins are in /usr/share/vim/vim80 but also in users home ~/.vim. How are conflicts handled? Let's say there is /usr/share/vim/vim80/ftplugin/tex.vim and there is ~/.vim/ftplugin/tex.vim, which gets loaded? Or what would be the correct way to modify the given plugin (e.g. tex.vim) - modify the one in /usr/... or copy the one in /usr/... to ~/.vim/ and modify it there (I want to avoid the changes being overwritten when package is updated).

@phd From the link 'The result is that all directories in the 'runtimepath' option will be searched for the "plugin" sub-directory and all files ending in ".vim" will be sourced (in alphabetical order per directory), also in subdirectories.' I have not found any other information there. This does not answer the question in what order the directories are processed, and thus the files and what happens if two conflicting plugins are reached, does the sourcing completely redefine what is in that plugin? — atapaka, Dec 19 '18 at 19:08
Obviously, the directories are processed in the **order of the 'runtimepath'** option. **All files `.vim`** are sourced. Clear and complete answer. — phd, Dec 19 '18 at 20:14

score 2 · Answer 1 · answered Dec 20 '18 at 07:42

Vim configuration has a certain structure (plugin/, syntax/, etc. subdirectories), and there can be multiple base directories that host those config trees. The 'runtimepath' option enumerates all base directories, and Vim searches them sequentially from start to end, as described by :help load-plugins.

There's usually a user-specific base directory (~/.vim/) as well as the default Vim runtime (what's in /usr/share/vim/vim80 for you), and sometimes also other system-wide places. The user's config comes first, so it gets priority.

plugin conflicts

So, what happens if you install the same plugin for your user (in ~/.vim/plugin/) that already exists elsewhere (e.g. the built-in netrw plugin)?

Both ~/.vim/plugin/netrwPlugin.vim and /usr/share/vim/vim80/plugin/netrwPlugin.vim are executed, one after the other. (You can check with :scriptnames.) So, what will happen?

Note that most plugins have an multiple inclusion guard at the top, always in a similar form:

" Load Once: {{{1
if &cp || exists("g:loaded_netrwPlugin")
    finish
endif
let g:loaded_netrwPlugin = "v156"

The plugin defines a guard variable (g:loaded_netrwPlugin) the first time it is run. On the next run, that global variable is already defined, and the script execution stops at :finish. This means that the user-defined plugin "wins" (as it's first in 'runtimepath'), and you're able to override the system-wide one (e.g. with a newer version that you've downloaded).

The same applies to pack plugins or plugin directories added by a package manager. Something similar exists for syntax plugins (b:current_syntax) and filetype plugins (b:did_ftplugin), with the distinction that those are not loaded once on startup, but every time a file is opened (so they use a buffer-scoped variable, and omit the plugin name there).

Modifying a plugin

In order to modify a plugin, you indeed place a copy in ~/.vim/. This is better than directly modifying the plugin source that ships with Vim (as it would be overwritten by updates to Vim). Even if you want to apply the change system-wide (not just for your user), it's better to add another base directory (e.g. via a global /etc/vimrc file) to 'runtimepath' and copy the plugin there.

Note that (permanently) modifying a plugin should rarely be necessary: For common tasks (like extending a syntax plugin or changing options of a filetype plugin), there's a built-in way through the after-directory (which is yet another manipulation of 'runtimepath', as described above). Plugins usually are configurable through (documented) variables or :help using-<Plug>. If you're missing a way to influence the plugin (but think yours is a common and sensible use case), asking the plugin's author for a configuration option is a good idea.

vim plugin directories priority

1 Answers1

plugin conflicts

Modifying a plugin