kevin/vim-plug
1
Fork 0
mirror of https://github.com/junegunn/vim-plug.git synced 2024-12-19 18:47:29 -07:00
Code Issues Packages Projects Releases Wiki Activity

Updated faq (markdown)

Jeremy Pallats/starcraft.man 2016-01-06 11:44:02 -05:00
parent bae5a36ce9
commit 3a98cac30e
1 changed files with 109 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

235
faq.md

@ -1,14 +1,41 @@
## FAQ/Troubleshooting
## Tips
### Requirements
### Automatic installation
#### Vim
Place the following code in your .vimrc before `plug#begin()` call
vim-plug is known to work with Vim 7.0 or above. But it is strongly recommended that you use 7.3 or above.
```vim
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 | source $MYVIMRC
endif
```
#### Git
### Loading plugins manually
Most of the features should work with Git 1.7 or above. However, installing plugins with tags is [known to fail](https://github.com/junegunn/vim-plug/issues/174) if Git is older than 1.7.10. Please use Git 1.8 or above.
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](https://github.com/SirVer/ultisnips) and [YouCompleteMe](https://github.com/Valloric/YouCompleteMe) first time you enter insert mode.
```vim
" Load on nothing
Plug 'SirVer/ultisnips', { 'on': [] }
Plug 'Valloric/YouCompleteMe', { 'on': [] }
augroup load_us_ycm
autocmd!
autocmd InsertEnter * call plug#load('ultisnips', 'YouCompleteMe')
\| call youcompleteme#Enable() | autocmd! load_us_ycm
augroup END
```
### Gist as plugin
Unlike [NeoBundle](https://github.com/Shougo/neobundle.vim), vim-plug does not natively support installing small Vim plugins from Gist. But there is a workaround if you really want it.
```vim
Plug 'https://gist.github.com/952560a43601cd9898f1.git',
\ { 'dir': g:plug_home.'/xxx/plugin', 'rtp': '..' }
```
### Migrating from other plugin managers
@ -22,7 +49,7 @@ curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
and update your .vimrc as needed.
<table>
<thead>
<th>
<tr>
<th>
With Vundle.vim
@ -58,10 +85,9 @@ call plug#end()
</tr>
</table>
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()`.
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.
@ -74,16 +100,11 @@ call plug#begin('~/.vim/bundle')
call plug#begin('~/vimfiles/bundle')
```
### Plugins are not installed/updated in parallel
## FAQ
Parallel installer is only enabled when any of the following conditions is met
### Does vim-plug generate help tags for my plugins?
1. Vim with Ruby support: `has('ruby')` / Ruby 1.8.7 or above
2. Vim with Python support: `has('python')` / Python 2.6 or above
3. Neovim with job control: `exists('*jobwait')`
In order to setup Vim with Ruby support, you may refer to [this
page](https://github.com/junegunn/vim-plug/wiki/ruby).
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?
@ -112,101 +133,6 @@ delc PlugUpgrade
Unlike `PlugUpgrade`, you'll have to restart Vim after vim-plug is updated.
### Automatic installation
Place the following code in your .vimrc before `plug#begin()` call
```vim
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 | source $MYVIMRC
endif
```
### *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:
```vim
: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](http://brew.sh/) while using a Ruby installed with
[RVM](http://rvm.io/) or [rbenv](https://github.com/sstephenson/rbenv) and later
removed that version of Ruby. Thus, it is safer to build Vim with system ruby.
```sh
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. After that, vim-plug should be able to use the ruby installer.
[Please let me know](https://github.com/junegunn/vim-plug/issues) 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.
### YouCompleteMe timeout
[YouCompleteMe (YCM)](https://github.com/Valloric/YouCompleteMe) 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.
### 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
" Branch
Plug 'rdnetto/YCM-Generator', { 'branch': 'stable' }
" Tag
Plug 'junegunn/vim-easy-align', { 'tag': '2.9.2' }
" Commit hash
Plug 'junegunn/fzf.vim', { 'commit': '9a45d70' }
```
### 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.
### 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](https://github.com/SirVer/ultisnips) and [YouCompleteMe](https://github.com/Valloric/YouCompleteMe) first time you enter insert mode.
```vim
" Load on nothing
Plug 'SirVer/ultisnips', { 'on': [] }
Plug 'Valloric/YouCompleteMe', { 'on': [] }
augroup load_us_ycm
autocmd!
autocmd InsertEnter * call plug#load('ultisnips', 'YouCompleteMe')
\| call youcompleteme#Enable() | autocmd! load_us_ycm
augroup END
```
### 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?
@ -230,28 +156,61 @@ Plug 'tpope/vim-repeat'
See [#168](https://github.com/junegunn/vim-plug/issues/168), [#161](https://github.com/junegunn/vim-plug/issues/161), [#133](https://github.com/junegunn/vim-plug/issues/133), [#109](https://github.com/junegunn/vim-plug/issues/109), [#56](https://github.com/junegunn/vim-plug/issues/56) for more details.
### Gist as plugin
## Troubleshooting
Unlike [NeoBundle](https://github.com/Shougo/neobundle.vim), vim-plug does not natively support installing small Vim plugins from Gist. But there is a workaround if you really want it.
### 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
1. Vim with Python support: `has('python') or has('python3')` / Python 2.6 or above
1. Neovim with job control: `exists('*jobwait')`
For more help, see the [requirements](https://github.com/junegunn/vim-plug/wiki/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:
```vim
Plug 'https://gist.github.com/952560a43601cd9898f1.git',
\ { 'dir': g:plug_home.'/xxx/plugin', 'rtp': '..' }
:ruby puts RUBY_VERSION
```
### Windows System Error E484
There are two possible causes we've encountered.
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 ...`)
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.
If you're on OS X, one possibility is that you had installed Vim with
[Homebrew](http://brew.sh/) while using a Ruby installed with
[RVM](http://rvm.io/) or [rbenv](https://github.com/sstephenson/rbenv) and later
removed that version of Ruby. Thus, it is safer to build Vim with system ruby.
1. System changes due to AutoRun commands executed on cmd.exe startup. See [docs](https://technet.microsoft.com/en-us/library/cc779439%28v=ws.10%29.aspx).
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.
```batch
REG QUERY "HKCU\Software\Microsoft\Command Processor" /v AutoRun
REG QUERY "HKLM\Software\Microsoft\Command Processor" /v AutoRun
```sh
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](https://github.com/junegunn/vim-plug/issues) 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.
### YouCompleteMe timeout
[YouCompleteMe (YCM)](https://github.com/Valloric/YouCompleteMe) 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.
### 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:
@ -271,3 +230,25 @@ 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.
1. System changes due to AutoRun commands executed on cmd.exe startup. See [docs](https://technet.microsoft.com/en-us/library/cc779439%28v=ws.10%29.aspx).
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.
```batch
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:
- http://badsimplicity.com/vim-fish-e484-cant-open-file-tmpvrdnvqe0-error/
- https://github.com/junegunn/vim-plug/issues/12