-
-
Notifications
You must be signed in to change notification settings - Fork 1.9k
faq
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
endifNote 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.)
Download plug.vim in autoload directory
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vimand 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')Use plain "if" statement to conditionally activate plugins:
if has('mac')
Plug 'junegunn/vim-xmark'
endifThe 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'
endifAlternatively, 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' })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/' }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 ENDYes, 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.
"Premature optimization is the root of all evil."
You most likely don't need them at all. A properly implemented Vim plugin should already load lazily without any help from the plugin manager (:help autoload). There are very few cases where those options actually make much sense. On-demand loading should only be used as the last resort. It is basically a hacky workaround and is not always guaranteed to work.
Before applying the options, make sure that you're tackling the right problem by breaking down the startup of time of Vim using --startuptime. See if there are plugins that take more than a few milliseconds to load.
vim --startuptime /tmp/logThere 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 | PlugUpgradeYou can save some keystrokes by defining a custom command like follows:
command! PU PlugUpdate | PlugUpgradeIf 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/autoloadand 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 PlugUpgradeUnlike PlugUpgrade, you'll have to restart Vim after vim-plug is updated.
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.
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:
- Using full git url:
Plug 'https://github.com/junegunn/seoul256.vim.git' - Or define
g:plug_url_formatfor the plugins that you need to work on.
let g:plug_url_format = '[email protected]:%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.
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.
Parallel installer is only enabled when at least one of the following conditions is met:
- Vim with Ruby support:
has('ruby')/ Ruby 1.8.7 or above - Vim with Python support:
has('python') or has('python3')/ Python 2.6 or above - Neovim with job control:
exists('*jobwait')
For more help, see the requirements.
If your Vim crashes with the above message, first check if its Ruby interface is working correctly with the following command:
:ruby puts RUBY_VERSIONIf 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 vimIf 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.
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 (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.
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.
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.
There are two possible causes we've encountered.
-
Bad escaping. On Windows, if you use '<', '>' or '|' in the file path, vim-plug is known to fail. Any other chars should be fine.
-
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 AutoRunIf 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: