Managing Vim Scripts with a Vimball

I am a vim user. The thing I like about vim is it's speed, how universal it is, and it's customizations. These customizations can come in the form of plugins, syntax files, compilers, and code completion utilities; all of which are scripts. Scripts can be a single file like MiniBufExplorer or can encompass multiple files like vjde.

Single file scripts are fairly easy to manage. If you notice a new version of your script is released, then simply replace your file with the new version. Likewise, it's very easy to remove the script if you want to just try it out. However, scripts spanning multiple files are much harder to manage. For one, the script's files get merged in with all of your other script files.

To help know what files are apart of what plugin, I manage my vim scripts in git. Another way to keep track of things is to use a vimball.

What Are Vimballs?

Vimballs are essential vim script installers. Each vimball contains all of the files that are needed for the script to work. Not only that, but it also has a hook for you to easily uninstall the script as well.

Tail Bundle is a script that mimics tail -f for vim. The downloadable artifact is a vba file. That file is the vimball. To actually install the file:

1. `vim tail-03.vba`
2. `:so %`
3. `:q`

So what that all means is that you're opening the vimball in vim. From there, you're executing the instructions that are in the file. Lastly, you're just quiting. You see, a vimball is a vim script in of itself. So executing it writes everything out to where it's supposed to go.

While the tail bundle makes use of the vimball, not every script does. Luckily, it's easy to make vimballs out of most script downloads.

Converting Scripts to a Vimball

In order to make a vimball, it's quite easy. List out all of the files you want to include in your bundle, relative to where your current directory is. For instance:

doc/myawesomeplugin.txt
plugin/myawesomeplugin.vim
syntax/myawesomeplugin.vim

Next thing, while in visual mode, type ggVG:MkVimball myawesomeplugin. The ggVG is a akin to doing a "select all".

This will create your install file named myawesomeplugin.vba. Now just install it like any other vimball.

You don't have to just make vimballs for your own scripts. I love xpt, but there are so many files to manage. Well, you can make the vimball script even when the author does not.

Open a new buffer and use the command :r! find . -type f. This will find all of the files and print them out into the buffer. If you want to do any cleanup, like remove blank lines and removing the extra ./ before each entry, feel free to do so. Now that you easily got a list of all the files, create the vimball from that.

Now you have records of what went in with the script and you have a super easy way of uninstalling the script too. Speaking of which...

Removing Scripts

To remove a vimball script, simply execute :RmVimball myawesomeplugin. That will go through and delete all files created by the plugin.

After figuring this out, I now know that when I want to use and install vim scripts, I'm going to do so via vimballs. It's too easy not to, and the benefit of having a way to back-out scripts is just too tempting.