Installing plugins using packages

#69

Run time:

Packages are a new feature in version 8 of Vim. In this video, we’ll see how we can use packages to easily install Vim plugins. The process will be familiar if you’ve used pathogen.

Shownotes

It’s easy to confuse the terms package and plugin, so let’s start by defining the terminology: A plugin is a directory containing one or more scripts. A package is a directory containing one or more plugins.

If that makes sense, you can skip the next two sections. Otherwise, read on…

What’s a Plugin?

A plugin is a directory containing one or more scripts (usually with documentation). The purpose of a plugin is to add new functionality to Vim, or to modify Vim’s existing functionality. A demo-plugin containing one script and an accompanying documentation file might look like this:

demo-plugin
├── doc
│   └── demo.txt
└── plugin
    └── demo.vim

To install this plugin, you would add the top-level demo-plugin directory to Vim’s runtimepath. You could manipulate the runtimepath by hand:

set runtimepath+=~/.vim/arbitrary/demo-plugin

Vim has supported plugins since version 6, but until recently there was no convenient way of managing the runtimepath. You had to do it by hand, or you had to install a plugin such as pathogen to automate the runtimepath management. With version 8, Vim released the packages feature to fill this gap.

What’s a Package?

A package is a directory that contains one or more plugins. When you organise your plugins in a package, Vim can automatically add those plugins to your runtimepath on startup.

By convention, you create packages within a .vim/pack directory. Your package should contain a subdirectory called start, which is where you install the plugins that you want to load when Vim starts up.

You can create as many packages as you like. For example, you might create one package called bundle where you install plugins written by other people. Then you might create another package called myplugins where you keep the plugins that you maintain by yourself.

Creating a ‘bundle’ package

Create a package called bundle where you’ll install your plugins:

mkdir -p ~/.vim/pack/bundle/start
mkdir -p ~/.vim/pack/bundle/opt

Any plugins that you install in the start directory will be added to your runtimepath when Vim starts up.

The opt directory is for optional plugins. You can add these to your runtime path when you need them by using the :packadd command.

Installing plugins to the ‘bundle’ package

Let’s install some tpope plugins: surround, unimpaired, and scriptease. Change to the bundle/start directory, and clone the surround and unimpaired repositories there:

cd ~/.vim/pack/bundle/start
git clone https://github.com/tpope/vim-surround.git
git clone https://github.com/tpope/vim-unimpaired.git

If you start a fresh instance of Vim, these plugins will be available for you to use right away. (If you’re already running an instance of Vim, you’ll have to restart to use these plugins.)

Next, clone the scriptease plugin to the bundle/opt directory:

cd ~/.vim/pack/bundle/opt
git clone https://github.com/tpope/vim-scriptease.git

If you start a fresh instance of Vim, you won’t be able to use the scriptease plugin right away. First, you have to activate it by running:

:packadd vim-scriptease

That adds the plugin to your runtimepath and makes the features of scriptease available to you. (To see for yourself, try running :Scriptnames.)

Indexing plugin documentation

Most plugins include documentation, which you can view using the same :help command that you use for Vim’s built-in documentation. Before you can look up the documentation for a newly installed plugin, you have to index its documentation. You can do so by running:

:helptags ~/.vim/pack

You only need to do this one time after installing (or updating) a plugin.

Further reading

Comments

Level-up your Vim

Training

Boost your productivity with a Vim training class. Join a public class, or book a private session for your team.

Drew hosted a private Vim session for the shopify team that was one of the best workshops I have ever attended.

John Duff, Director of Engineering at Shopify

Publications

Make yourself a faster and more efficient developer with the help of these publications, including Practical Vim (Pragmatic Bookshelf 2012), which has over 50 five-star reviews on Amazon.

After reading it, I've switched to vim as my default editor on a daily basis with no regrets. ★★★★★

Javier Collado

Learn to use Vim efficiently in your Ruby projects

In association with thoughtbot, one of the most well respected Rails consultancies in the world, I've produced a series of screencasts on how to make navigating your Ruby projects with Vim ultra-efficient. Along the way, you’ll also learn how to make Ruby blocks a first-class text object in Vim. This lets you edit Ruby code at a higher level of abstraction. Available to buy from thoughtbot..