quiet misdreavus microblog

migrating from vim-pathogen to native vim packages

2020-03-15

I recently was messing around with my Vim configuration (as one does) and realized that i had an opportunity to change how i loaded the plugins i use. I was previously using pathogen, but as i had upgraded all my Vim installations to version 8¹, i could start to use the built-in package support. This post describes my journey toward this migration.

about vim plugins

It’s worth talking about the Vim 8 package layout because it differs slightly from how Vim plugins are normally structured. A Vim plugin tends to be structured as a set of Vim scripts in folders much like the .vim/vimfiles² directory: autoload/, ftplugin/, colors/, syntax/, and so on. Initially, these were meant to be integrated into your own Vim configuration so that in the end you would create one assembled unit of Vim code.

Over time, as people created more and more things with Vim, many different ways of keeping these Vim extensions apart appeared³. The core idea of any of these is like this: Rather than merging all these files/folders into your main Vim configuration, separate them into different directories so they can be managed separately. You can also provide different ways of specifying what plugins you use, how they get loaded, how they get installed and updated, and so on.

Eventually, Vim 8 (and Neovim before it) included a way to include these collections of scripts in a way that they could be managed separately and also automatically included in your configuration. However, they structured it a little differently than just “a bunch of copies of .vim/vimfiles”, so when i looked into it i was a little confused.

about vim 8 packages

Vim 8 packages take the idea of “a bunch of copies of .vim/vimfiles” and add in the idea of bundling several of these together into a cohesive package. They added a new pack/ folder that it checks in .vim/vimfiles, and the things that go in this folder work differently than bundle or plugged or the like:

.vim/
- pack/
  - some-package-name/
    - start/
    |  - some-plugin/
    - opt/
       - some-other-plugin/

When Vim sees items in the pack/ folder, it looks inside for start/ and opt/ subfolders. Items in the start/ subfolder are treated just like Pathogen treats items in the bundle/ folder: It adds that directory to 'runtimepath' when Vim is launched. This causes that plugin to be available for further use.

The interesting part comes in for plugins in the opt/ folder. Those aren’t loaded right away, but they are made available for the new :packadd command. This way, plugins can be lazily loaded only when they’re needed, for example by running that in an auto-command or with a wrapper command.

migrating from pathogen

Anyway, with this detail out of the way, how do you actually migrate over from Pathogen? The short answer:

$ mkdir -p pack/asdf
$ git mv bundle pack/asdf/start

You can call the package folder whatever you’d like: Your username, the word plugins, some dummy text, whatever. You could even go one step farther and separate out plugins based on their functionality, like color schemes or syntax definitions. (This is what i wound up doing.).

Since Vim 8 packages are relatively new on the scene compared to the existing solutions, i’m not sure how popular it will be to actually distribute things in that specific format. But i like the fact that that automatic 'runtimepath' management is now built-in, and that it has the capability to optionally load things after startup. Since i was already using Pathogen and manually-tracked Git submodules for my plugins, this works nicely for my purposes.