Order in runtimepath of Vim packages or similar plug-in managers

Question

Vim packages work by updating 'runtimepath' to include the top directories of the plug-ins in each package (and also the after/ directory), but the Vim documentation on packages isn't absolutely clear on which ordering is used to add the packages into 'runtimepath'.

It seems plug-ins are added after the Vim directory in your home (~/.vim or $HOME/vimfiles on Windows) and before the Vim system-wide runtimes (there's actually two directories for those, $VIM/vimfiles and $VIMRUNTIME.) The after/ directories of plug-ins are added after the Vim runtimes.

These general guidelines seem intuitive and make sense, since you typically want the files directly in your home to supercede plug-ins (so come as early as possible), then have plug-ins supercede the Vim runtimes (since you might use a plug-in with a richer or more featureful version of what upstream ships) and the after/ directory exists specifically for when you specifically need to have something as late as possible in 'runtimepath'.

But: What are the exact rules used to splice package plug-in directories into 'runtimepath'?

What if you changed your 'runtimepath', or you're using a non-standard directory for the Vim runtimes?

In the same vein, Vim 8 packages seem to follow on the tracks of pathogen.vim, which started establishing adding plug-in directories to 'runtimepath' as a way to manage plug-ins, which was later embraced by plug-in managers such as Vundle and vim-plug. But it seems none of those is very explicit in documenting the rules for manipulation of 'runtimepath' either.

So: What are the rules for splicing 'runtimepath' used by these popular plug-in managers? Are those the same ones later adopted by Vim packages?

Answer 1

As I don't know where to find the "written" rules, I digged into the source code instead. Also note that there are both Vim and Neovim, but it looks that they still share almost the same code in this regard, so the following applies to both.

Also, let me remind that there is rtp-order and load-order, and they are different, as it becomes clear from comparing the output of :set rtp? and :scriptnames.

So Vim does the following:

1. Execute :h --cmd if any
2. Source startup scripts (like .vimrc and stuff). Note that .vimrc may use :packloadall and such to force early plugins load
3. Save a copy of &rtp
4. Add plugins directories to &rtp (needed to make sure all autoload's are found).
5. Load standard plugins (i.e. plugin/**/*.vim from saved &rtp, except for after)
6. Load user plugins (i.e. pack/*/start/* from &packpath!)
7. Source after-plugins from new (current) &rtp

Now you ask about step (4) explicitly. On this step Vim finds every pack/*/start/* from &packpath and, if it's not yet in &rtp, adds it. The relevant code is in function named add_pack_dir_to_rtp() found in src/scriptfile.c (Vim) or src/ex_cmds2.c (Neovim).

As far as I understand, it simply takes the path prefix (before pack/... part) and tries to find the first match (like strncmp() with the length of the prefix) in the current &rtp and put it just after it. Hence all the user plugins paths normally go after ~/.vim but in reverse order (compared to their natural find-and-load-order). If no match was found then the item is appended to &rtp (with respect to after).