vim-plug/README.md

A single-file Vim plugin manager.

Somewhere between Pathogen and Vundle, but with faster parallel installer.

Pros.

• Easier to setup
• Parallel installation/update (requires +ruby)
• Smallest possible feature set
• Branch/tag support
• On-demand loading
• Dependency resolution using Plugfile (experimental)

Cons.

• Everything else

Usage

Download plug.vim and put it in ~/.vim/autoload

mkdir -p ~/.vim/autoload
curl -fLo ~/.vim/autoload/plug.vim https://raw.github.com/junegunn/vim-plug/master/plug.vim

Edit your .vimrc

call plug#begin('~/.vim/plugged')

" Make sure you use single quotes
Plug 'junegunn/seoul256.vim'
Plug 'junegunn/vim-easy-align'

" On-demand loading
Plug 'scrooloose/nerdtree', { 'on':  'NERDTreeToggle' }
Plug 'tpope/vim-fireplace', { 'for': 'clojure' }

" Using git URL
Plug 'https://github.com/junegunn/vim-github-dashboard.git'

" Plugin options
Plug 'nsf/gocode', { 'tag': 'go.weekly.2012-03-13', 'rtp': 'vim' }

" Locally-managed plugin
Plug '~/.fzf'

call plug#end()

Reload .vimrc and :PlugInstall to install plugins.

Commands

Command	Description
PlugInstall [name ...] [#threads]	Install plugins
PlugUpdate [name ...] [#threads]	Install or update plugins
PlugClean[!]	Remove unused directories (bang version will clean without prompt)
PlugUpgrade	Upgrade vim-plug itself
PlugStatus	Check the status of plugins
PlugDiff	See the updated changes from the previous PlugUpdate

Plug options

Option	Description
branch/tag	Branch or tag of the repository to use
rtp	Subdirectory that contains Vim plugin
do	Post-update hook (string or funcref)
on	On-demand loading: Commands or <Plug>-mappings
for	On-demand loading: File types
frozen	Do not install/update plugin unless explicitly given as the argument

Options for parallel installer

Flag	Default	Description
g:plug_threads	16	Default number of threads to use
g:plug_timeout	60	Time limit of each task in seconds
g:plug_retries	2	Number of retries in case of timeout

Keybindings

• D - PlugDiff
• S - PlugStatus
• R - Retry failed update or installation tasks
• q - Close the window

Example: A small sensible Vim configuration

call plug#begin()
Plug 'tpope/vim-sensible'
call plug#end()

On-demand loading of plugins

" NERD tree will be loaded on the first invocation of NERDTreeToggle command
Plug 'scrooloose/nerdtree', { 'on': 'NERDTreeToggle' }

" Multiple commands
Plug 'junegunn/vim-github-dashboard', { 'on': ['GHDashboard', 'GHActivity'] }

" Loaded when clojure file is opened
Plug 'tpope/vim-fireplace', { 'for': 'clojure' }

" On-demand loading on both conditions
Plug 'junegunn/vader.vim',  { 'on': 'Vader', 'for': 'vader' }

Post-installation/update hooks

There are some plugins that require extra steps after installation or update. In that case, use do option to describe the task to be performed.

Plug 'Valloric/YouCompleteMe', { 'do': './install.sh' }

If you need more control, you can pass a reference to a Vim function that takes a single argument.

function! BuildYCM(info)
  " info is a dictionary with two fields
  " - name: name of the plugin
  " - status: 'installed' or 'updated'
  if a:info.status == 'installed'
    !./install.sh
  endif
endfunction

Plug 'Valloric/YouCompleteMe', { 'do': function('BuildYCM') }

Both forms of post-update hook are executed inside the directory of the plugin.

Make sure to escape BARs when you write do option inline as they are mistakenly recognized as command separator for Plug command.

Plug 'junegunn/fzf', { 'do': 'yes \| ./install' }

But you can avoid the escaping if you extract the inline specification using a variable (or any Vimscript expression) as follows:

let g:fzf_install = 'yes | ./install'
Plug 'junegunn/fzf', { 'do': g:fzf_install }

Dependency resolution

See Dependency Resolution.

Articles

• Writing my own Vim plugin manager
• Thoughts on Vim plugin dependency
• Vim plugins and startup time

FAQ/Troubleshooting

Plugins are not installed/updated in parallel

Your Vim does not support Ruby interface. :echo has('ruby') should print 1. In order to setup Vim with Ruby support, you may refer to this article.

Vim: Caught deadly signal SEGV

If your Vim crashes with the above message, first check if its Ruby interface is working correctly with the following command:

:ruby puts RUBY_VERSION

If Vim crashes even with this command, it is likely that Ruby interface is broken, and you have to rebuild Vim with a working version of Ruby. (brew remove vim && brew install vim or ./configure && make ...)

If you're on OS X, one possibility is that you had installed Vim with Homebrew while using a Ruby installed with RVM or rbenv and later removed that version of Ruby.

Please let me know if you can't resolve the problem. In the meantime, you can set g:plug_threads to 1, so that Ruby installer is not used at all.

Errors on fish shell

If vim-plug doesn't work correctly on fish shell, you might need to add set shell=/bin/sh to your .vimrc.

Refer to the following links for the details:

• http://badsimplicity.com/vim-fish-e484-cant-open-file-tmpvrdnvqe0-error/
• https://github.com/junegunn/vim-plug/issues/12

Freezing plugin version with commit hash

vim-plug does not allow you to freeze the version of a plugin with its commit hash. This is by design. I don't believe a user of a plugin should be looking at its individual commits. Instead, one should be choosing the right version using release tags or versioned branches (e.g. 1.2.3, stable, devel, etc.)

Plug 'junegunn/vim-easy-align', '2.9.2'

If the repository doesn't come with such tags or branches, you should think of it as "unstable" or "in development", and always use its latest revision.

If you really must choose a certain untagged revision, consider forking the repository.

Migrating from other plugin managers

vim-plug does not require any extra statement other than plug#begin() and plug#end(). You can remove filetype off, filetype plugin indent on and syntax on from your .vimrc as they are automatically handled by plug#end().

License

MIT