Introduction

The vim text editor is a versatile and extremely powerful tool for manipulating plain text, managing system configuration files, and creating code. While the modal editing design focus and the elegant grammar of the editor itself is loved by its users, its interface and functionality sometimes lacks the niceties that some users would like.

Luckily, vim also includes a plugin, or script, system which can be used to extend the editor in various ways. These are implemented as simple configuration files that are stored in subdirectories under the ~.vim directory according to their function. As you add more plugins, these can get quite messy and it can be difficult to keep these plugins separate and to manage them effectively.

For this reason, quite a few plugin managers have been made for vim to help make this task simpler. The plugin manager that we will be talking about in this guide, called vundle, is incredibly useful for keeping all of these pieces in line.

We will be exploring how to use vundle on an Ubuntu 12.04 VPS instance. However, most distributions should be able to use these instructions without much additional work.

Install the Utility Software

Before we can start exploring how to use vundle to manage vim plugins, we need to install all of the necessary components.

First, we need to update our local package index, and then we need to ensure that vim is installed (that would be useful!) and that git is available to acquire additional components:

sudo apt-get update
sudo apt-get install vim git

Now that we have vim and git installed (you probably already had vim installed if you are reading this article), we will take a momentary break before installing vundle to talk about how plugins traditionally work and how vundle works to manage them.

How does Vundle Work?

Traditionally, vim is configured on a per-user basis in each user's home directory, with fall-back defaults configured by the system administrator and finally the software itself. These personal settings are stored in a hidden file called ~/.vimrc.

Plugins and additional configuration files that add functionality are conventionally added into a hidden directory at ~/.vim. Inside, most plugins are organized into subdirectories based on the functionality that they provide. These could be things like autoload, plugin, colors, etc.

So if you are using the builtin vim plugin system, your home directory might look a bit like this:

ls -AR ~

---

/home/demouser:
.bash_history  .bash_logout  .bashrc  .profile  .vim  .vimrc

/home/demouser/.vim:
autoload  bitmaps  colors  doc  plugin  syntax

/home/demouser/.vim/autoload:
plugin1.vim  plugin2.vim

/home/demouser/.vim/bitmaps:
plugin1.png

/home/demouser/.vim/colors:
plugin2.vim

/home/demouser/.vim/doc:
plugin1.txt  plugin2.txt

/home/demouser/.vim/plugin:
plugin1.vim

/home/demouser/.vim/syntax:
plugin1.vim

The vundle tool is actually built on a different plugin manager called pathogen and provides a superset of functionality. The pathogen manager simplifies plugin management by creating a separate plugin directory tree for each individual plugin.

This means that rather than having each plugin throw different files into different directories, mixing them with other plugins, each plugin will instead recreate the needed directory structure inside of a subdirectory specific to the plugin.

These are kept in a subdirectory called bundle. Your directory structure instead would look something like this:

ls -AR ~

---

justin@vundle:~$ ls -AR ~
/home/justin:
.bash_history  .bash_logout  .bashrc  .profile  .vim  .vimrc

/home/justin/.vim:
autoload  bundle

/home/justin/.vim/autoload:
plugin1.vim  plugin2.vim

/home/justin/.vim/bundle:
plugin1  plugin2

/home/justin/.vim/bundle/plugin1:
autoload  bitmaps  doc  plugin  syntax

/home/justin/.vim/bundle/plugin1/autoload:
plugin1.vim

/home/justin/.vim/bundle/plugin1/bitmaps:
plugin1.png

. . .

This creates a deeper nesting system, but it allows us to easily manage our plugins as a unit. If we don't want to use "plugin1" anymore, we can just do something like this:

rm -rf ~/.vim/bundle/plugin1

This simplifies our management scheme greatly. This is basically what pathogen accomplishes.

What vundle does is add a management interface inside of vim itself that let's you acquire more plugins, update plugins, etc. It adds the "management" portion on top of what some people would say is pathogen's organization improvements.

Start Clean and Install Vundle

Now that you understand a little bit about how the underlying vundle system works, we can get started.

First, if you have a current ~/.vimrc file and a ~/.vim directory, we are going to back them up and start fresh. This will help us minimize incompatibilities and potential issues:

if [ -e .vimrc ]; then mv .vimrc .vimrc_bak; fi
if [ -e .vim ]; then mv .vim .vim_bak; fi

Afterwards, we can clone the vundle plugin directly from GitHub, which will recreate some of our ~/.vim directory structure:

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

Next, we'll have to recreate our ~/.vimrc file to tell vim to use our new package management system.

vim ~/.vimrc

Inside, we need a few things to start us off. First, we need to make sure that vim is not attempting to retain compatibility with vi, its predecessor. This is a vundle requirement. When vim attempts to be compatible, it disables most of the features that make it worth using over vi.

We also want to turn off the default "filetype" controls for now because the way that vim caches filetype rules at runtime interferes with the way that vundle alters the runtime environment. We will change this back later:

set nocompatible
filetype off

Next, we'll need to then adjust vim's runtime path to include the vundle location we cloned from GitHub. After that, we will call the vundle initialization function:

set nocompatible
filetype off
set rtp+=~/.vim/bundle/vundle/
call vundle#rc()

Now, our vundle system is initialized and we can add in the plugins that we wish to manage. While vundle can manage local plugins, one of its strengths is the ability to tie local versions to online versions, which allows you to auto update, etc.

We can do this by pointing to GitHub repositories, vim scripts, other remote git repositories, and local git repositories.

First of all, we must manage the vundle package itself with vundle. Then we can add whatever additional plugins we'd like:

set nocompatible
filetype off
set rtp+=~/.vim/bundle/vundle/
call vundle#rc()

" This is the Vundle package, which can be found on GitHub.
" For GitHub repos, you specify plugins using the
" 'user/repository' format
Plugin 'gmarik/vundle'

" We could also add repositories with a ".git" extension
Plugin 'scrooloose/nerdtree.git'

" To get plugins from Vim Scripts, you can reference the plugin
" by name as it appears on the site
Plugin 'Buffergator'

" Now we can turn our filetype functionality back on
filetype plugin indent on

Notice how at the end, we re-establish the "filetype" functionality that we previously turned on. All plugins must be declared between the call vundle#rc() line and the filetype plugin indent on directive.

After this section of our ~/.vimrc, we can add any additional vim settings that we need.

When you are finished, save and close the file ( ":wq" or "ZZ").

Install and Update Plugins with Vundle

Now, we just need to tell vundle to install all of the plugins that we added to the file. Start vim:

vim

Now, issue the :PluginInstall command:

:PluginInstall

This will open a new split window in vim and run through the installation of each of the new plugins. When it is complete, you can close the new buffer and window by typing:

:bdelete

The plugins that you added to your ~/.vimrc file are now installed!

If you wish to update your plugins, you can use one of these two commands:

:PluginUpdate

Or

:PluginInstall!

The "!" at the end of the :PluginInstall! command basically tells vundle to reinstall all of the plugins (it checks if any action is needed), which will get the newest versions.

After an update, you can see what plugins were actually affected by typing "u" in the vundle plugin window. If you want to see a full log of the operations that took place during either an update or an installation, type "l" to view the complete log.

Manage Plugins with Vundle

Now that you've gotten the hang of how to install plugins, let's go over some other functionality that can help you get more out of vundle.

Acquiring New Plugins

One of the most useful functions of vundle is the ability to find and install more plugins.

We can list every plugin that vundle can find on the Vim Scripts site by typing:

:Plugins

Or

:PluginSearch!

The "!" at the end of the command refreshes the local list from the Vim Scripts site.

If we want to search for a specific plugin, we can use this same syntax like this:

:PluginSearch! plugin_query

This will open a new window with the results of our query. If you've recently refreshed the local database, you can leave off the "!" from the command. So if you search for "markdown", you may get something like this:

PluginSearch markdown

---

"Keymap: i - Install plugin; c - Cleanup; s - Search; R - Reload list
"Search results for: markdown
Plugin 'instant-markdown.vim'
Plugin 'MarkdownFootnotes'
Plugin 'Markdown'
Plugin 'Markdown-syntax'

As you can see on the top, you can easily install any of the plugins by moving to the line with the plugin and typing "i".

This will download and install the plugin, but it will not update your ~/.vimrc to make it autoload correctly.

So, to install the "MarkdownFootnotes" plugin, we would move our cursor to that line press 'i':

"Keymap: i - Install plugin; c - Cleanup; s - Search; R - Reload list
"Search results for: markdown
Plugin 'instant-markdown.vim'
Plugin 'MarkdownFootnotes'  # move here and press "i"
Plugin 'Markdown'
Plugin 'Markdown-syntax'

You can delete the vundle buffer when the installation is complete:

:bdelete

Afterwards, edit your ~/.vimrc by typing:

:e ~/.vimrc

Add the new plugin line:

set nocompatible
filetype off
set rtp+=~/.vim/bundle/vundle/
call vundle#rc()

Plugin 'gmarik/vundle'

Plugin 'scrooloose/nerdtree.git'

Plugin 'Buffergator'

Plugin 'MarkdownFootnotes'

filetype plugin indent on

You can save and close the file at this point.

Managing Installed Plugins

Once you have some plugins installed, you can manage them with vundle.

To see all of your installed plugins, type this:

:PluginList

---

" My Plugins
Plugin 'gmarik/vundle'
Plugin 'scrooloose/nerdtree.git'
Plugin 'Buffergator'
Plugin 'MarkdownFootnotes'

If you need to remove a plugin, this needs to be accomplished in two steps.

You can delete the plugin files by listing them, and then hitting the "D" key when your cursor is on the plugin you wish to delete. So to delete our "MarkdownFootnotes" plugin, we can select it and hit "D":

" My Plugins
Plugin 'gmarik/vundle'
Plugin 'scrooloose/nerdtree.git'
Plugin 'Buffergator'
Plugin 'MarkdownFootnotes'   # Press "D" when selected

At this point, vundle still has this plugin in its configuration, but the plugin's files are not installed. You could reinstall the files again by typing:

:PluginInstall

We won't do this though. Instead, we will remove the entry from our ~/.vimrc file:

:e ~/.vimrc

---

set nocompatible
filetype off
set rtp+=~/.vim/bundle/vundle/
call vundle#rc()

Plugin 'gmarik/vundle'

Plugin 'scrooloose/nerdtree.git'

Plugin 'Buffergator'

filetype plugin indent on

This will complete the removal of the plugin from your system.

An easier way of doing this though is to remove it from the ~/.vimrc file first.

After you've removed it, you can call this command, which deletes any plugins that are not in your ~/.vimrc file automatically (it will ask you to confirm):

:PluginClean

---

" Removing Plugins:
Plugin 'MarkdownFootnotes'

. . .
Continue? [Y/n]:

You can type "Y" to remove all unreferenced plugins.

Conclusion

By this point, you should be able to easily manage your plugins through the vundle interface. The advantages of having a good plugin manager for vim may not be apparent at first glance, especially if you do not use many plugins.

However, one of the greatest benefits that this gives you is the ability to easily experiment with new plugins. When the process is clean and simple, you are more likely to explore different plugins and try to integrate functionality when otherwise you would maybe suck it up and do things in a more complicated fashion.