« Yet Another Vim Setup »

25 December 2013
Sample screenshot editing my .vimrc
Sample screenshot editing my .vimrc

Vim is an excellent text editor. I’ve used it for many years and like most vim users, have collected a fairly large collection of settings in my .vimrc and learned how to grok my vim usage effectively through a lot of trial and error.

To that end, I’ve tried to assemble a useful overview of my experience with vim.

Foreword: Why?

Why would you want to even put in the effort to beef up vim?

  • Portability. Carry your IDE everywhere with minimal effort, possibly even in just a single dotfile. (insert plug for homeshick here)
  • Performance. Your IDE will start in under a second and you won’t lose your mind if it crashes.
  • Improved speed and precision. It takes a long time - don’t get me wrong - but once you learn how to use vim the way it wants to be used, you’ll like it.
  • Vibrant community. This is one of hundreds of community resources for vim. If somebody has ever needed to do $task in vim, somebody has probably figured out a good way to do it.

Prelude: abide by these principles

A few things to keep in mind:

  • Stop working with the new-file-new-tab paradigm. Read this answer on Stack Overflow for more.
  • Don’t start with a pre-built/huge .vimrc. Build gradually to learn what you’re doing.
  • Learn how to learn vim. Be cognizant of what slows you down, update your .vimrc with shortcuts you know, rinse, repeat.

Essential Settings

I mentioned not to get ahead of yourself with a massive .vimrc off the bat, but there are a few settings that you just plain need initially.

  • set nocompatible
    • This will get rid of antiquaited backwards-compatability settings and make vim a bit more usable.
  • set number
    • Turn on line numbers. This one is pretty obvious.
  • set ruler
    • Always display the status line at the bottom of the vim window (column, filename, etc.)
  • syntax on
    • Although other plugins build on this, the basic setting is a must.

Essential Plugins

These are plugins I use every time I open vim.

Ctrl-P

This will change the way you work with files. Stop browsing/pointing and clicking as you look for files and invoke a fuzzy text search for your file instead. Seriously handy.

Vim-Airline

By default vim’s interface isn’t terribly informative. Vim-airline is much more lightweight than other alternatives (like vim-powerline, which requires a lot of configuring) and offers out-of-the-box usefulness. Note that powerline-fonts can be tricky, but the exchange for your effort is an especially pretty interface.

Good-to-have Plugins

Vundle

There are many ways of managing plugins, namely pathogen and vundle. I used pathogen for a long time but now use Vundle as it can automate things a bit more, but either is a good choice and handy if you use many plugins.

Syntastic

Syntastic offers syntax and style checking without being overly complicated. If you’re coding professionally, syntastic is pretty essential as it’ll catch dumb mistakes like syntax errors, functionality that is pretty much taken for granted in a traditional IDE.

Easytags

Tags are a pretty basic function of vim, but using them right can be challenging. To that end, I use vim-easytags to handle the bulk of what can make tags complicated. Again, for professional software development, it’s plum necessary.

NERDTree

Although I mostly use Ctrl-P for navigating files, NERDTree is good to have around to visualize directory structure or when simply browsing code. vim’s built-in netrw has similar functionality but is more finicky.

Putting it together

I’ve mentioned good plugins and settings, but how does it look?

If I were to hand you a template .vimrc, I’d start with this:

" Basic settings
set nocompatible              " Eliminate backwards-compatability
set number                    " Enable line numbers
set ruler                     " Turn on the ruler
syntax on                     " Syntax highlighting

" Plugins
filetype off                  " Req'd for vundle
set rtp+=~/.vim/bundle/vundle " Vundle prelude
call vundle#rc()              " ^

Bundle 'gmarik/vundle'
Bundle 'scrooloose/nerdtree'
Bundle 'kien/ctrlp.vim'
Bundle 'scrooloose/syntastic'
Bundle 'bling/vim-airline'
Bundle 'xolox/vim-misc'
Bundle 'xolox/vim-easytags'

" Post-vundle
filetype plugin indent on     " Req'd for vundle

Then use vundle to install your bundled plugins:

$ git clone https://github.com/gmarik/vundle.git ~/.vim/bundle/vundle
$ vim +BundleInstall +qall

You’re ready to go. Let’s look at a practical example.

Using jekyll (what I’m using to generate this site) as an example, I’ll illustrate how this setup works. First, let’s get the code, enter the code root, and start up vim. Note that we’re starting vim with our working directory at the jekyll root.

$ cd
$ git clone https://github.com/jekyll/jekyll.git jekyll-tmp
$ cd jekyll-tmp
$ vim

You’re looking at the generic vim splash screen. Vim is extremely task-oriented – although you could certainly browse around code using NERDTree, let’s assume that there’s a method you want to refactor in here.

First, recursively generate tags for all files in your current working directory. This only needs to be done once in a new project, every subsequent save you perform will update your global tags file. Thus, within vim:

:UpdateTags -R .

Nice. This uses the easytags plugin. Now, let’s assume you’re been working on a file called build.rb, changing the way jekyll dynamically regnerates changed files. Use Ctrl-P to perform a fuzzy search for build.rb and jump right to it: Hit control-p, type ‘build’, and the file will be highlighted - then hit enter.

<Ctrl-P> build <Enter>

Now you’re in build.rb. You know that jekyll uses a method called watch() to observe your template files, regenerating static HTML if anything changes.

You can get to watch() in a couple of different ways:

  • Just search for it. You may have to hit n a few times to jump to the right “watch” string, but it’s simple and works. /watch<Enter>nnn
  • Use Ctrl-P’s builtin fuzzy tag searcher: :CtrlPTag<enter>watch<enter>
  • Use vim’s builtin tag navigator: :tag watch

Any of those commands will get you to the watch() method. Now, looking inside the method (browse with the hjkl keys), let’s say you want to look more in-depth at the process_site method. Fine - place your cursor over the method call (line 53, column 16 in my build.rb) and hit Ctrl-]:

/process_site<enter><Ctrl-]>

Vim used its tags file as an index to jump to where process_site is defined. From there you can hit Ctrl-T to jump up one level in the tag stack you’re working on.

Back in watch() (use :tags watch to get back there if you aren’t) find a line and create a ruby syntax error (if you want to make the change I did, execute 53gg$x and save the file :w (my errors have a custom unicode character for errors, your error marker may be different.)

Vim errors are highlighted in the sidebar and in vim-airline's status bar
Vim errors are highlighted in the sidebar and in vim-airline's status bar

If syntastic is working (it should) it’ll highlight your syntax error. Many filetypes work by default (like ruby), others like python require more effort (to install the syntax checker binary.) However, that’s just a matter of installing a binary in your $PATH like flake8. Look in ~/.vim/bundle/syntastic/syntax_checkers to figure out what syntax checkers syntastic is looking for.

Also note that vim-airline is integrating with syntastic to show you any errors or warnings in its status bar (it denotes a syntax error – vim-airline will also alert you to whitespace errors and the like.)

As a final demonstration, enter :NERDTree (note that you can tab-complete these vim commands.) NERDTree will open up and you can browse the directory structure from here to get an overview of the the jekyll project. :q closes the window.

Post-exercise

This was a contrived example, but you can extrapolate from here. For example, as fuzzy searching for files is useful, fuzzy searching for tags is even moreso. Ctrl-P has a function for this. Here’s the steps you’d take to implement a shortcut for yourself.

  • Look at Ctrl-P’s help page. :help ctrlp
  • Search for tag support (search for tags with /tags<enter> and hit n a few times before you find what you want)
  • You’ll find that the command :CtrlPTag exists which will search available tags.
  • Create a nice shortcut to invoke the command. The following snippet will work:
nnoremap <leader>t :CtrlPTag<CR>

Now <leader>t will open up Ctrl-P’s tag search window. Leader commands provide you with a good starting point for custom commands – by default, <leader> is mapped to \. Thus the keystroke \t while in normal mode will open up the fuzzy tag search window.

Conclusion

This only scratches the surface of what you can do with vim, and I myself have a big .vimrc with lots of changes not mentioned here. As I mentioned, start with a basic foundation and gradually build up your .vimrc as you think of ways to streamline your workflow or run into nice plugins or settings around the Internet.

ty@tjllgmail.net