faq

Junegunn Choi edited this page Jan 20, 2017 · 73 revisions
Clone this wiki locally

Tips

Automatic installation

Place the following code in your .vimrc before plug#begin() call

if empty(glob('~/.vim/autoload/plug.vim'))
  silent !curl -fLo ~/.vim/autoload/plug.vim --create-dirs
    \ https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
  autocmd VimEnter * PlugInstall --sync | source $MYVIMRC
endif

Note that --sync flag is used to block the execution until the installer finishes.

(If you're behind an HTTP proxy, you may need to add --insecure option to the curl command. In that case, you also need to set $GIT_SSL_NO_VERIFY to true.)

Migrating from other plugin managers

Download plug.vim in autoload directory

curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
    https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

and update your .vimrc as needed.

With Vundle.vim Equivalent vim-plug configuration
filetype off
set rtp+=~/.vim/bundle/Vundle.vim
call vundle#begin()
Plugin 'VundleVim/Vundle.vim'
Plugin 'junegunn/seoul256.vim'
Plugin 'junegunn/goyo.vim'
Plugin 'junegunn/limelight.vim'
call vundle#end()
filetype plugin indent on
syntax enable
call plug#begin('~/.vim/plugged')
Plug 'junegunn/seoul256.vim'
Plug 'junegunn/goyo.vim'
Plug 'junegunn/limelight.vim'
call plug#end()

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#begin() and plug#end().

Since all the other major plugin managers store plugins in "bundle" directory, you might want to pass it to plug#begin() if you do not wish to reinstall plugins.

" For Mac/Linux users
call plug#begin('~/.vim/bundle')

" For Windows users
call plug#begin('~/vimfiles/bundle')

Conditional activation

Use plain "if" statement to conditionally activate plugins:

if has('mac')
  Plug 'junegunn/vim-xmark'
endif

The caveat is that when the condition is not met, PlugClean will try to remove the plugin. This can be problematic if you share the same configuration across terminal Vim, GVim, and Neovim.

" When started with plain Vim, the plugin is not registered
" and PlugClean will try to remove it
if has('nvim')
  Plug 'benekastah/neomake'
endif

Alternatively, you can pass an empty on or for option so that the plugin is registered but not loaded by default depending on the condition.

Plug 'benekastah/neomake', has('nvim') ? {} : { 'on': [] }

A helper function can improve the readability.

function! Cond(cond, ...)
  let opts = get(a:000, 0, {})
  return a:cond ? opts : extend(opts, { 'on': [], 'for': [] })
endfunction

" Looks better
Plug 'benekastah/neomake', Cond(has('nvim'))

" With other options
Plug 'benekastah/neomake', Cond(has('nvim'), { 'on': 'Neomake' })

Gist as plugin

vim-plug does not natively support installing small Vim plugins from Gist. But there is a workaround if you really want it.

Plug 'https://gist.github.com/952560a43601cd9898f1.git',
    \ { 'as': 'xxx', 'do': 'mkdir -p plugin; cp -f *.vim plugin/' }

Loading plugins manually

With on and for options, vim-plug allows you to defer loading of plugins. But if you want a plugin to be loaded on an event that is not supported by vim-plug, you can set on or for option to an empty list, and use plug#load(names...) function later to load the plugin manually. The following example will load ultisnips and YouCompleteMe first time you enter insert mode.

" Load on nothing
Plug 'SirVer/ultisnips', { 'on': [] }
Plug 'Valloric/YouCompleteMe', { 'on': [] }

augroup load_us_ycm
  autocmd!
  autocmd InsertEnter * call plug#load('ultisnips', 'YouCompleteMe')
                     \| autocmd! load_us_ycm
augroup END

FAQ

Does vim-plug generate help tags for my plugins?

Yes, it automatically generates help tags for all of your plugins whenever you run PlugInstall or PlugUpdate. But you can regenerate help tags only with plug#helptags() function.

Shouldn't vim-plug update itself on PlugUpdate like Vundle?

There is a separate PlugUpgrade command and there are valid reasons behind the decision. A detailed discussion can be found here.

So if you want to make sure that you have the latest version of vim-plug after PlugUpdate, just run PlugUpgrade after PlugUpdate.

PlugUpdate | PlugUpgrade

You can save some keystrokes by defining a custom command like follows:

command! PU PlugUpdate | PlugUpgrade

If you really, really want to use PlugUpdate only, you can set up vim-plug like follows:

# Manually clone vim-plug and symlink plug.vim to ~/.vim/autoload
mkdir -p ~/.vim/{autoload,plugged}
git clone https://github.com/junegunn/vim-plug.git ~/.vim/plugged/vim-plug
ln -s ~/.vim/plugged/vim-plug/plug.vim ~/.vim/autoload

and in your .vimrc:

call plug#begin('~/.vim/plugged')
Plug 'junegunn/vim-plug'
" ...
call plug#end()
" The caveat is that you should *never* use PlugUpgrade
delc PlugUpgrade

Unlike PlugUpgrade, you'll have to restart Vim after vim-plug is updated.

Managing dependencies

vim-plug no longer handles dependencies between plugins and it's up to the user to manually specify Plug commands for dependent plugins.

Plug 'SirVer/ultisnips'
Plug 'honza/vim-snippets'

Some users prefer to use | separators or arbitrary indentation to express plugin dependencies in their configuration files.

" Vim script allows you to write multiple statements in a row using `|` separators
" But it's just a stylistic convention. If dependent plugins are written in a single line,
" it's easier to delete or comment out the line when you no longer need them.
Plug 'SirVer/ultisnips' | Plug 'honza/vim-snippets'
Plug 'junegunn/fzf', { 'do': './install --all' } | Plug 'junegunn/fzf.vim'

" Using manual indentation to express dependency
Plug 'kana/vim-textobj-user'
  Plug 'nelstrom/vim-textobj-rubyblock'
  Plug 'whatyouhide/vim-textobj-xmlattr'
  Plug 'reedes/vim-textobj-sentence'
  • Ordering of plugins only matters when overriding an earlier plugin's commands or mappings, so putting the dependency next to the plugin that depends on it or next to other plugins' dependencies are both okay.
  • In the rare case where plugins do overwrite commands or mappings, vim-plug requires you to manually reorder your plugins.

What's the deal with git::@ in the URL?

When vim-plug clones a repository, it injects git::@ into the URL (e.g. https://git::@github.com/junegunn/seoul256.vim.git) which can be an issue when you want to push some changes back to the remote. So why?

It's a little hack to avoid username/password prompt from git when the repository doesn't exist. Such thing can happen when there's a typo in the argument, or when the repository is removed from GitHub. It looks kind of silly, but doing so is the only way I know that works on various versions of git. However, Git 2.3.0 introduced $GIT_TERMINAL_PROMPT which can be used to suppress user prompt, and vim-plug takes advantage of it and removes git::@ when Git 2.3.0 or above is found.

Also, there are two ways to override the default URL pattern:

  1. Using full git url: Plug 'https://github.com/junegunn/seoul256.vim.git'
  2. Or define g:plug_url_format for the plugins that you need to work on.
let g:plug_url_format = 'git@github.com:%s.git'
Plug 'junegunn/vim-easy-align'
Plug 'junegunn/seoul256.vim'

unlet g:plug_url_format
Plug 'tpope/vim-surround'
Plug 'tpope/vim-repeat'

See #168, #161, #133, #109, #56 for more details.

I'm getting `Cannot find color scheme '...'. Does vim-plug support color schemes?

Yes, color schemes are not any different from other plugins. A common mistake is to put :colorscheme NAME before call plug#end(). Plugins are not activated before plug#end(), so make sure to load your color scheme after it.

Troubleshooting

Plugins are not installed/updated in parallel

Parallel installer is only enabled when at least one of the following conditions is met:

  1. Vim with Ruby support: has('ruby') / Ruby 1.8.7 or above
  2. Vim with Python support: has('python') or has('python3') / Python 2.6 or above
  3. Neovim with job control: exists('*jobwait')

For more help, see the requirements.

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 reinstall 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. Thus, it is safer to build Vim with system ruby.

rvm use system
brew reinstall vim

If you're on Windows using cygwin and the above ruby command fails with: cannot load such file -- rubygems.rb (LoadError). It means cygwin is missing the rubygems package. Install it using the setup.exe that came with cygwin.

Please let me know if you can't resolve the problem. In the meantime, you can put let g:plug_threads = 1 in your vimrc, to disable the parallel installers.

Python 2.7.11 Windows Registry Bug

Due to a bug that slipped into this release, the registry entries and python.dll do not align. A simple work around is explained here.

YouCompleteMe timeout

YouCompleteMe (YCM) is a huge project and you might run into timeouts when trying to install/update it with vim-plug.

The parallel installer of vim-plug (ruby or python) times out only when the stdout of the process is not updated for the designated seconds (default 60). Which means even if the whole process takes much longer than 60 seconds to complete, if the process is constantly printing the progress to stdout (10%, 11%, ...) it should never time out. Nevertheless, we still experience problems when installing YCM :(

Workarounds are as follows:

  • Increase g:plug_timeout
  • Install YCM exclusively with :PlugInstall YouCompleteMe
    • In this case single-threaded vimscript installer, which never times out, is used
  • Asynchronous Neovim installer does not implement timeout.

Installing YouCompleteMe manually

YouCompleteMe is an exceptionally large plugin that can take a very long time to download and compile. For this reason, one may want to download and update YouCompleteMe manually only when it is needed. Install it on any directory you prefer and pass the name of the directory to the Plug command.

" Assuming that you have installed (or will install) YCM
" in ~/.vim/plugged/YouCompleteMe
Plug '~/.vim/plugged/YouCompleteMe'

vim-plug will load the plugin, but it will not try to install or update YouCompleteMe.

fatal: dumb http transport does not support --depth

Apparently the git option --depth 1 requires SSL on the remote Git server. It is now default, to reduce download size. To get around this, you can:

Disable Shallow Cloning

Add let g:plug_shallow = 0 to your .vimrc.

Mirror the repository on a Git server with https (i.e. Github or BitBucket).

Then just add it normally with the new URI.

Mark the plugin as local/unmanaged

a) Clone it locally to ~/.vim/plugged/plugin_name

b) Add to the vimrc with Plug '~/.vim/plugged/plugin_name'.

The leading tilda tells vim-plug not to do anything other than rtp for plugin_name.

Windows System Error E484

There are two possible causes we've encountered.

  1. Bad escaping. On Windows, if you use '<', '>' or '|' in the file path, vim-plug is known to fail. Any other chars should be fine.

  2. System changes due to AutoRun commands executed on cmd.exe startup. See docs.

To see if your system suffers this second problem, run these reg queries. If either one returns a path to a bat file, you should carefully read it. You may have to edit/disable it to get vim-plug working.

REG QUERY "HKCU\Software\Microsoft\Command Processor" /v AutoRun
REG QUERY "HKLM\Software\Microsoft\Command Processor" /v AutoRun

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: