< Back to frontpage

Minimal vim configuration with vim-plug


for a barebones starter config

Like many vim configurations, this snippet is based on an amalgamation of other snippets that I have tweaked over 5+ years of full time vim usage. It's battle tested to work across platforms. However, if you see anything here that's not given proper credit, please let me know!

It's based on code I had for NeoBundle, which is another vim package manager. NeoBundle is made by Shougo, a respected name as far as vim plugins are concerned. Recently, he has announced dein.vim, which he claims is faster, and I may create a future article for that.

To build this vim configuration, we're going to use vim-plug. This requires you have git installed via your system's package manager. See git's documentation for more info on installing git.

Your vim configuration file

You can create a file $HOME/.vimrc to keep this in. Vim will automatically it.

You can also create a file at an arbitrary location, like ./myconfig.vim, and open it via $ vim -U <file>:

$ MYVIMRC=./myconfig.vim vim -u ./myconfig.vim

On more modern shells, you can also do:

$ env MYVIMRC=./vimconfig.vim vim -u $MYVIMRC

First line, disabling vi-compatible

Our first line is to turn off Vim's compatibility with plain-old vi:

set nocompatible

If you omit this, vim will freak out when handling stuff like line continuations in vimscript.

Bootstrapping vim-plug automatically

Upon first starting vim, the plugin manager should install itself.

To do this, we will check for a directory or file of the plugin manager script when vim starts. If the plugin manager isn't installed, we'll clone it. Simple enough, we find this snippet on vim-plug's wiki, keep this at the tippy top of your vim config:

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

Special note, source $MYVIMRC is analogous to source ~/.vimrc.

Recent versions of Vim don't update $MYVIMRC to respect -u. So remember to set MYVIMRC=./yourconfig.vim if you're using $ vim -u ./yourconfig.vim.

Plugin directory and starting vim-plug

Two things at once, plug#begin will start up vim-plug, and it's where the plugin directory (where all the plugins/packages are cloned to) is specified:

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

You can replace ~/.vim/plugged/ with whatever you want.

Automatically install plugins

After bootstrapping the package manager, we still have no plugins installed yet. Let's use an autocmd to run PlugInstall if there's no plugins found:

" Automatically install missing plugins on startup
if !empty(filter(copy(g:plugs), '!isdirectory(v:val.dir)'))
  autocmd VimEnter * PlugInstall | q
endif

The one above is thanks to junegunn, vim-plug's creator.

Putting it all together

set nocompatible

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

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

" Automatically install missing plugins on startup
if !empty(filter(copy(g:plugs), '!isdirectory(v:val.dir)'))
  autocmd VimEnter * PlugInstall | q
endif

Putting it into action

From here on in, you can use the Plug function to add GitHub repos. For instance, take vim-airline/vim-airline:

Plug 'vim-airline/vim-airline'

After your plugins, cap it off with this:

call plug#end()

A full example of a minimal config:

set nocompatible

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

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

" Automatically install missing plugins on startup
if !empty(filter(copy(g:plugs), '!isdirectory(v:val.dir)'))
  autocmd VimEnter * PlugInstall | q
endif

" My plugins
Plug 'vim-airline/vim-airline'

call plug#end()

Continued usage

After automated installation, you can proceed to close vim via :qa, or open new file buffers with :e filename.

To install new plugins, update your vim configuration file with new Plug 'github_username/github_repo' packages between call plug#begin('plugindir') and call plugin#end():

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

" Automatically install missing plugins on startup
if !empty(filter(copy(g:plugs), '!isdirectory(v:val.dir)'))
 autocmd VimEnter * PlugInstall | q
endif

" My plugins
Plug 'vim-airline/vim-airline'
Plug 'klen/python-mode'

call plug#end()

Then use this :PlugInstall vim command to install the new plugins.

In this instance, with klen/python-mode you can immediately proceed to open python files (for instance :e samplepython.py and get autocompletion, and have access to its documentation via :help python-mode.

For updating the vim plugins, use :PlugUpdate.

For self-updating the vim-plug plugin manager, use :PlugUpgrade.

More pointers

For further research on vim-plug, check out its wiki.

For other plugins, after your plugin is installed, you can immediately proceed to use their help documentation. For instance, for vim-airline's documentation, you can type :help vim-airline, which opens the equivalent of doc/airline.txt (link), in addition to viewing its own README on GitHub.