Vim Tutorial: The Vimrc File

Table of Contents

1. The Basics
2. Vimrc
   1. How to Read A Vimrc
   2. Some Basic and Sane Options
   3. Plugins
   4. Getting More Advanced
   5. Writing Your Own Commands
   6. Summary
3. Intermediate Vim

The Vimrc File

One of the most important things you will ever do with vim is write a vimrc file. These are very personal files, yet people often make them public. For example here is mine. This file is personal because it is how you will interact with your editor. This, like all rc files, are curated to you and you alone. For this reason it is generally not suggested to just copy paste someone’s, because you never know what it is going to do. It is also suggested that you upload it somewhere where you can grab it easily for when you work on different machines. That’s why many of us use git, essentially keeping all our editors identical across machines.

How to Read A Vimrc

Before we look at mine, let’s talk about how you should be reading it. Vim has one of the best written documentation around, it is worth using (even before you google something). Most of these files are not commented well (I try, but we all get lazy), so it is important to look up commands that you don’t know. If you don’t know something type :help command. Let’s try it!

:help help

Awesome! But now we have a problem! It opened up within vim and now I don’t know how to get out! This is called a pane, we will talk about these in a later section, but don’t worry, you can use :q to quit just that pane.

A Quick Lesson in Pane Movements

<C-w> k     Move to the pane above
<C-w> j     Move to the pane below
:on         Focus only on the currently selected pane
:q          Quit the pane

We’ll talk more about panes later, but these will help you now. You may notice that you have the same hjkl movements with panes, just prepended with <C-w>.

Some Basic and Sane Options

Here’s a pretty basic rc file, save it to ~/.vimrc. We’ll go through each part step by step.

syntax on
colorscheme peachpuff
set t_Co=256
set nocompatible
set lazyredraw
set showcmd
set number rule
set showmode
set scrolloff=5
set spell
hi clear SpellBad
hi SpellBad cterm=underline,bold ctermfg=white

Pretty simple, right? That’s the majority of MY vimrc file (it is only 81 lines!). So let’s go through these.

First we are in the 21st century and have color on our monitors, so let’s prettify this up and enable syntax highlighting. We’ll then pick a colorscheme. You can find a ton of them at vimcolors.com but I use a slightly modified version of TPope’s vividchalk (tpope is one of the vim wizards, you will likely run into his work. Be sure to tell him thanks).

Next is nocompatible which the documentation directory reads “This option has the effect of making Vim enter more Vi-compatible, or make Vim behave in a more useful way.” This should always be near the top of your file because it changes other options.

Lazy redraw will make things run a little faster. The rest should be fairly readable and if you can’t I’ll leave it as an exercise to the reader to figure out what they do.

Plugins

There’s a bunch of different plugin managers, this is something people frequently argue over. Here’s people on stackoverflow arguing. Honestly just pick one. I use Vundle so we will talk about that and whichever you use will be similar.

For Vundle we just need to clone and then edit our a few options in our rc file

git clone https://github.com/VundleVim/Vundle.vim.git ~/.vim/bundle/Vundle.vim

filetype off
set rtp+=~/.vim/bundle/Vundle.vim
call vundle#begin()
    Plugin 'VundleVim/Vundle.vim
call vundle#end()

Let’s edit this with a few plugins and see it in action

filetype off
set rtp+=~/.vim/bundle/Vundle.vim
call vundle#begin()
    Plugin 'VundleVim/Vundle.vim
    Plugin 'scroloose/nerdtree'
    Plugin 'godlygeek/tabular'
    Plugin 'airblade/vim-gitgutter'
call vundle#end()
map <Leader> nt :NERDTreeToggle<CR>

Nerd tree gives us a convenient way to explore our file system. Tabular allows us to align things by tabs pretty easily (:/Tab symbol), and Git Gutter shows us info about what has changed on the left side. These are pretty common plugins.

First we need to install them. After you have this added type :PluginInstall. You’ll see a pane open up on the left and stuff install. Great! Now we can use them. So let’s use Nerd Tree. Type \nt (we mapped this to :NERDTreeToggle in that extra line we added, we’ll talk about maps later). You should notice a file system browser appear on the left side. You can again use \nt to get rid of it or use any of the pane movements we talked about above.

The keen readers may also be looking at those plugins and be asking “Are those GitHub repositories?” If you asked that, you’re completely correct! Now we can search GitHub for new plugins and quickly install them.

Here’s a quick list of Vundle commands

:PluginInstall
:PluginClean
:PluginList
:PluginSearch foo

For more information on Vundle see :help vundle

Getting More Advanced

Let’s talk about some more features and commands. Let’s set up auto indenting and line wrapping.

set autoindent
set expandtab
set smarttab
set shiftwidth=4
set softtabstop=4
set wrap
set tw=80
set colorcolumn=81

We turn on auto indenting and set our tabs to 4 spaces. That’s right! We’re using spaces and not tabs!

Even though it isn’t the 1980’s anymore, we’re going to set our lines to wrap at the 80th column and we’re putting a vertical line at the 81st column so we can see it. You might find this silly now, but you’ll find it really useful when we start using panes and buffers.

Now let’s get a bit crazy.

set path+=**

set noerrorbells
set novisualbell
set t_vb=  "_ we can even type comments!

set incsearch
set hlsearch
set showmatch
set ignorecase
set smartcase

The first command is really the only tricky one here. path is a list of directories which will be searched when looking for other files. The double wildcard means that vim will look infinitely forward. This I have found is usually really nice but can get cumbersome.

The next section we turn off the error bells. Then we add commands for highlighting our searching (/foo), making it case insensitive, and to be smart about it.

Another thing you may notice at the top of my vimrc file is the two source commands. These are essentially include commands. I know I said my vimrc was only 81 lines but

This is a great way to keep things organized. Just like we wouldn’t put all our code into a single main file, we can source other files. I keep my custom commands in one file and commands and settings for plugins in another.

Writing Your Own Commands

Now we’re going to write our own commands!

Say we’re working on a project that won’t let us merge if we have trailing whitespaces. We could set Vim to remove trailing spaces on every write (:w)

autocmd BufWrite * :%s/\s\+$//g

But that might slow things down a lot of the file is large. So let’s instead write a command to just clean the whole file. We want this command to happen in normal mode. Custom commands must start with a capital letter (damn capitalists). Because we’re so creative and great at naming things we’ll call the command “CleanFile”

command CleanFile normal! :%s/\s\+$//g<CR>

Here we’re telling the command that we want to act in normal mode. The second part says that we want to search the whole file (%s) and then replace \s\+$ with nothing, and then that we want to do this for every instance (the g). Finally we have a carriage return.

We can even write terminal commands! For example we could write a command to add the current file to git.

command Add normal! :!git add %<CR>

The bang (!) here means that we’re calling a terminal command. % means the current file.

Now we know how to write a normal command! But wait, we actually know how to write two types of commands. Remember this guy?

map <leader>nt NERDTreeToggle<CR> 

It is basically the same thing! Leader just means “", but we can also remap that if we want. We also snuck in an autocommand in our first example. These are pretty much the types of commands you will be writing.

Speaking of autocommands, we can write one to return our cursor to the last position we were at when we last opened the file (or buffer).

autocmd BufReadPost *   
    \ if line("'\"") > 0 && line("'\"") <= line("$") |
    \ exe "normal! g`\"" |
    \ endif

Checkout my rc file for more ideas.

Summary

Wow, you’ve made it really far. At this point you can impress people with your vim skills and knowledge. Your friends will look up to you and think you know so much. To keep up it is highly recommend to keep using the :help command. Read more vimrcs and find out what works best for you. I’m fairly minimal, but there are plenty of others who like to have tons of plugins and huge rc files. The beauty of it is that it is up to you. It is your editor, do it your way.

We’ll next work on Intermediate Vim