Bundle Up

Vim started as a text editor, but it long ago evolved into an ecosystem of plugins that number in the hundreds. These plugins, in turn, have created the demand for easy ways to manage them. Vundle (Vim Bundles) [1] is one of the most popular managers. The tool works with the GitHub [2] and Vim script [3] sites and uses a combination of editing the vim configuration file .vimrc and running four basic commands within Vim. Vundle bills itself – with only minor exaggeration – as "the Vim package manager."

Vim needs a package manager because plugins are not always easy to manage. The subdirectories to install to are not consistent, and you can only update and delete plugins manually from outside Vim.

Vundle is an enhancement of Pathogen [4], a plugin manager that improves on Vim's default file structure by placing all the files for each plugin in a subdirectory of ~/.vim/bundle, instead of dumping all the help files in ~/.vim/doc and all the plugins in ~/.vim/plugins. This change makes locating the help and the script for each plugin much easier than in default Vim structure. Vundle uses Pathogen's directory structure, while adding automatic updates as well as management utilities that work within Vim.

Because Pathogen and Vundle both use the bundle directory, they use the word "bundle" interchangeably for "plugin or script" – a usage similar to software managers using "packages" to refer to both the applications and the scripts needed to install it.

Setting Up Vundle

If Vim is already installed on your system, delete the .vim and .vimrc files in your home directory, or at the very least rename them. Creating new, empty versions of these files will make installation far easier.

The easiest way to obtain Vundle is to use Git [5] to clone the Vundle repository from GitHub on your local machine. Git is used in so many different free software projects that most major distributions carry it. Thus, you can easily install it if you have not done so already. Then, clone the Vundle software repository in your home directory with the command:

git clone https://github.com/gmarik/vundle.git ~/.vim/bundle/vundle

The next step is to prepare – and, if necessary, create – .vimrc for using Vundle. The quickest and most error-proof way to prepare .vimrc is to copy and paste the sample file in ~/.vim/bundle/vundle/README.md, which is one of the files and directories added when you cloned the Git repository.

However, you might not want all of the plugins or repositories listed in the sample. If nothing else, some of the paths in the sample may be obsolete and will only produce error messages when you try to update them. Although you could always remove unwanted or obsolete entries later, if you learn from the sample, you can configure .vimrc more to your liking.

The section for Vundle in the .vimrc configuration file must begin with the commands for calling Vundle:

set nocompatible
filetype off
set rtp+=/.vim/bundle/vundle

These lines are followed by the last two directories on the path on GitHub to each script that you have downloaded. You must manually add them to .vimrc, but make sure that Vundle is always the first entry, so that Vundle treats itself as another bundle:

Bundle  'gmarik/vundle'

The other plugins are entered below, one per line, each with the last two directories in its GitHub path enclosed in single quotation marks. You might need to look up a repository's web page, either on the web or from within Vim using one of Vundle's utilities.

The sample .vimrc uses comments to organize the listing of plugins into original repositories on GitHub, vim-script repos, and local Git repos. You might follow this same structure, although many users may be satisfied with only GitHub repositories. Although GitHub may not include repositories for every Vim plugin ever published, it does include all the best-known ones.

The last line needed in .vimrc to run Vundle is:

filetype plugin indent on

Below that, the sample includes a summary of Vundle's commands. As you can tell from the fact that its lines are commented out, this section of the sample is for convenience only; from within Vim, you can always enter the command :h vundle (Figure 1).

Figure 1: Vundle is by far the most thoroughly documented of the available Vim managers.

Once .vimrc is organized the way you want it, start Vim, checking for error messages that might be caused by typos in .vimrc. Then, run :BundleInstall to configure Vundle to monitor itself to keep the plugin current, as well as any other plugins you might have added (see below).

Installing and Updating Plugins

To install additional plugins, clone their GitHub repositories, just as you did with Vundle. Alternatively, you can download and extract plugins so that they conform to the structure of the subdirectories below ~/.vim/bundle – one subdirectory per plugin, with /doc for the help file and /plugin for the executable.

Either way, open .vimrc and add the plugin's repository any place below the bundle entry for Vundle itself. Save .vimrc and, from within Vim itself, run :BundleInstall (Figure 2).

Figure 2: The :BundleInstall tool is one of Vundle's four utilities for configuring plugins from within Vim.

When the command is followed by the name of a plugin (e.g., :Bundleinstall abolish.vim), the command installs and activates the command. When run with an exclamation mark at the end (e.g., :BundleInstall!), the command updates all configured plugins.

In both cases, the command opens a new window, in which the entry currently being updated is indicated by a highlighted first letter and an arrow in the margin. When the updates are complete, a message appears at the bottom of the buffer. You can then press l (lowercase el) to view the log for the command, jumping to highlighted commands to read any error messages (Figure 3). As with any buffer, the command :q closes it.

Figure 3: The :BundleInstall log shows the utility's output.

The :BundleInstall utility runs automatically when you start Vim. However, you can also use it after you have added a new plugin or script in order to update Vim without logging out and back in again.

Listing Configured Plugins

To see which plugins are installed in Vim using Vundle, just look at the names of the subdirectories below ~/.vim/bundle.

However, Vundle makes viewing configured plugins even easier with :BundleList (Figure 4). This command opens a window listing the plugins that are configured on the current installation of Vim. Note that a plugin may be configured and working in Vim, but not activated  – that is, not listed in .vimrc to receive automatic updates.

Figure 4: The :BundleList command displays the plugins installed with Vundle.