A New Hope: Plugin Layout with Pathogen
Vim's vanilla layout for plugin files makes sense if you're just adding a file here and there to customize your own Vim experience, but turns into a mess when you want to use plugins other people have written.
In the past, when you wanted to use a plugin someone else wrote you would download the files and place them, one-by-one, into the appropriate directories. You could also use zip or tar to do the placing for you.
There are a few significant problems with this approach:
- What happens when you want to update a plugin? You can overwrite the old files, but how do you know if the author deleted a file that you now need to delete by hand?
- What if two plugins happen to have a file with the same name (like
utils.vimor something generic like that)? Sometimes you can simply rename it, but if it's in
autoload/or another directory where the names matter you've got to edit the plugin yourself. Not fun.
People came up with several hacks to try to make things easier, like Vimballs. Luckily we don't need to suffer through these ugly hacks any more. Tim Pope created the wonderful Pathogen plugin that makes managing multiple plugins a breeze, as long as plugin authors structure their plugins in a sane way.
Let's take a quick look at how Pathogen works and what we need to do to make our plugin compatible.
When Vim looks for files in a specific directory, like
syntax/, it doesn't
just look in a single place. Much like
PATH on Linux/Unix/BSD systems, Vim
runtimepath setting which tells it where to find files to load.
colors directory on your Desktop. Create a file in that directory
mycolor.vim (you can leave it empty for this demonstration). Open Vim
and run this command:
Vim will display an error, because it doesn't know to look on your Desktop for files. Now run this command:
You'll need to change the path to match the path of your own Desktop, of course. Now try the color command again:
This time Vim doesn't throw an error, because it was able to find the
mycolor.vim file. Because the file was blank it didn't actually do
anything, but we know it was found because it didn't throw an error.
The Pathogen plugin automatically adds paths to your
runtimepath when you load
Vim. Any directories inside
~/.vim/bundle/ will each be added to the
This means that each directory inside
bundle/ should contain some or all of
the standard Vim plugin directories, like
syntax/. Vim can now
load files from each of those directories, which makes it simple to keep each
plugin's files in its own directory.
This makes it trivial to update plugins. You can simply blow away the old
plugin's directory entirely and replace it with the new version. If you keep
~/.vim directory under version control (and you should) you can use
Mercurial's subrepos or Git's submodules to directly check out each plugin's
~/.vim/bundle/ and then update it with a simple
hg pull; hg
git pull origin master.
When we write our Potion plugin we want to let our users use it with Pathogen. Doing this is simple: we simply put our files in the appropriate directories inside the plugin's repository!
Our plugin's repository will wind up looking like this:
potion/ README LICENSE docs/ potion.txt ftdetect/ potion.vim ftplugin/ potion.vim syntax/ potion.vim ... etc ...
We can put this on GitHub or Bitbucket and users can simply clone it down into
bundle/ and everything will just work!
Install Pathogen if you haven't already done so.
Create a Mercurial or Git repository for your plugin, called
potion. You can
put it anywhere you like and symlink it into
~/.vim/bundle/potion/ or just put
it directly in
LICENSE files in the repository and commit them.
Push the repository up to Bitbucket or GitHub.