chapters/43.markdown @ 96cf3ead3c63

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.vim`
  or 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.

[Tim Pope]: http://tpo.pe/
[Pathogen]: http://www.vim.org/scripts/script.php?script_id=2332

Runtimepath
-----------

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
has the `runtimepath` setting which tells it where to find files to load.

Create a `colors` directory on your Desktop.  Create a file in that directory
called `mycolor.vim` (you can leave it empty for this demonstration).  Open Vim
and run this command:

    :color mycolor

Vim will display an error, because it doesn't know to look on your Desktop for
files.  Now run this command:

    :set runtimepath=/Users/sjl/Desktop

You'll need to change the path to match the path of your own Desktop, of course.
Now try the color command again:

    :color mycolor

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.

Pathogen
--------

The Pathogen plugin automatically adds paths to your `runtimepath` when you load
Vim.  Any directories inside `~/.vim/bundle/` will each be added to the
`runtimepath`.

This means that each directory inside `bundle/` should contain some or all of
the standard Vim plugin directories, like `colors/` and `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
your `~/.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
repository into `~/.vim/bundle/` and then update it with a simple `hg pull; hg
update` or `git pull origin master`.

Being Pathogen-Compatible
-------------------------

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!

Exercises
---------

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 directory in `~/.vim/bundle/potion/`.

Create `README` and `LICENSE` files in the repository and commit them.

Push the repository up to Bitbucket or GitHub.

Read `:help runtimepath`.