This week I will be presenting at Agile Staffordshire with Paul Williams providing an introduction to the Vi text editor. This post is to detail all the resources that may be of use to anyone wanting to use Vi or Vim more productively. Apologies in advance for any typos or grammatical errors. I was struggling for time when I wrote this post.

What Makes Vim More Than Just A Text Editor?

Vi/Vim is highly extendable and has a large number of plug ins written to support everything from GIT integration to syntax highlighting. It is on the almost all unix and linux environment and if not can be installed VERY easily. It remains fast and lightweight.

It is also support portable configurations, once it is setup just how you like it, it can be scripted and deployed on any machine quickly. With this in mind it’s also worth mentioning how well it works over SSH and TELNET connections, making it great for server administration as well as development on remote machines such as virtual servers in the cloud.

One of the key advantages a lot of users of VIM promote is that you never need to touch the mouse. Full interaction can be achieved from the keyboard and repetitive actions can be automated easily.

Useful Features

The presentation I will be giving this week will cover some very basic VIM usage (this will be delivered by Paul) and then I will move on to some more advanced features, plugins and scripted configurations. The basic VIM commands are out of the scope of this blog post.

Code Formatting

If you’re using VIM for any scripting or programming tasks one great feature that I use on a regular basis is formatting code files. If I paste some code into a file or for some reason the formatting of the code I’m working on isn’t quite right I can quickly correct this.

The key combination that I would use is ggvG=. Basically the gg moves the cursor to the top of the file, the v changes to visual selection mode, the G navigates to the end of the file (by this point everything is selected, think of it like ‘Select All’) and the = formats the selection.

This may seem long winded but it very quickly becomes second nature.

Spell Check

Anyone who is going to write documents using VIM, whether that be blog posts or notes, will find the spell check features that exist in VIM very useful. By default these are enabled however once set up they are very useful.

To enable spell check within VIM the following commands would need to be run, these could be added to the vimrc file to enable them permanently:
:set spell_lang=en_gb :set spell

Then to navigate the following key combinations can be used:

[s and ]s Go to previous and next spelling error z= will show the suggested corrections

I have configured my instances of VIM to only use spell check on markdown files, in order to do this I would add the following to my vimrc file:

autocmd BufRead,BufNewFile *.md setlocal spell

Searching

Basic searching within Vim is very simple. Using just the / character followed by what you want to look for before hitting enter. This will take you to the next occurrence of the search term. If I then want to navigate the occurrences of this search time I can use n and N to go to the next and previous occurrences.

Replacing

Another common task within a text editor is to ‘find and replace’ some text. In order to achieve this VIM uses regular expressions. A simple example of performing a find and replace in a file is as follows:

:%s/findthis/replacewiththis/g

This will replace all occurrences of find this and replace them with replacewiththis. This searches the entire file you’re currently working in. To limit this to the current line only, remove the % from the command. This functionality can be extended using full regular expression support however this is out of the scope of this post.

When using vim for editing scripts or code files it can be useful to navigate to the matching bracket, brace or quote. This could be used to find the start of a method or function when at the end or to easily navigate hashes or arrays in a json file. Vim has this functionality by default and can be used by hitting %. This will navigate to the matching bracket/brace/quote for the one current under the cursor.

Buffers, Windows And Tabs

Buffers

Buffers represent open files within VIM. They don’t have to be currently visible and by default changes that are made must be saved before they can be hidden. This can be easily overridden by using :set hidden either in your vimrc file or setting this directly in vim.

Using :e somefile.txt will load the specified file into a new buffer and adding extra file parameters to the command will open each file in a new buffer. The plugin ‘CTRL-P’ also loads files into new buffers.

Listing all current buffers can be achieved by using the command :ls and changing buffers can be achieved by using :b followed by the id of the buffer as listed in the previous command.

Windows

A window is a view onto a single buffer and you can have one or more windows all displaying the same buffer. Windows are great for displaying multiple files at the same time and this is when commands such as :split and :vsplit come in useful. You can also pass filenames to these two commands and that will open these files into buffers before splitting the screen.

Once you have several windows displayed it’s useful to be able to navigate between them! You will need to use the same keys as you would for moving the cursor normally, j, k, h and l however prefixed with CTRL-w.

The other key requirement of windows is the ability to resize them, without this it wouldn’t be a very useful feature. The commands that exist to do this are :resize and :vertical resize, you can pass the exact number of lines as parameters to these methods e.g. :resize 50 would resize a window to 50 lines in height however you can also use + and - to relatively resize windows, for example :vertical resize +5. This would increase the width of a window by 5 characters.

Tabs

Tabs are a collection of one or more windows. They are an easy way to group related windows. New tabs be created using the :tabnew command. You are then able to navigate between tabs using the :tabn and :tabp commands.

Plugins

A great resource for seeing what plugins are available for VIM is the http://vimawesome.com/ website. I’d highly recommend installing Pathogen as this makes installation as easy as cloning a git repo. This is what making scripting your vim configuration so easy (more on this shortly). There are a couple of plugins which I will cover at Agile Staffs and these are detailed below.

CTRL-P

Ctrl P is my favourite vim plugin. It’s a full path, fuzzy file and buffer tool. It’s so simple to use and quickly you start to depend on it.

To start using ctrl-p just hit Ctrl-P within VIM. You’ll get a little bar that pops up at the bottom of the screen. This is where you begin typing your search term.

As you can see below it matches the search criteria in real time:

To open a file I can use the arrow keys to move up and down the list and hit enter. I can also open multiple files, this is achieved by tagging the files to open using CTRL-z and then pressing CTRL-o to open all the files tagged.

Another function is to switch between path and just filename searching, this is accomplished by hitting CTRL-d.

Surround

Surround is a plugin for replacing surrounding quotes, braces, brackets and tags etc..

The two main key combinations to remember are cs and ds.

The first command is used to change what surrounds some text. For instance I could change "Hello world" to 'Hello world' by using cs"' on the first ". The second command, is for removing surrounding characters. ds" would change "Hello World" into Hello World.

Supertab

This plugin very simply provides tab autocompletion that uses words that are in any open buffer and allows your to quickly auto complete words as you type by hitting tab.

Endwise

Endwise is a great plugin for ruby developers. It doesn’t do anything mind blowing, it just automatically inserts the end keyword when you define a method or an if statement etc..

Markdown

Syntax highlighting and folding for markdown documents. What more can I say??

Scripted Vim Configuration

So you’ve got your VIM configured just how you like it? By scripting your VIM configuration, if you sit down at a new machine or jump onto a new server you can get it all setup just by running a bash script.

I host my VIM config on Github so I can just clone it and run the script.

There are two parts, your .vimrc file containing your customisations and a bash script that installs pathogen and clones all the appropriate plugin git repositories. The contents of these two files are below.

.vimrc

execute pathogen#infect()

  set nocompatible               " be iMproved

  filetype indent plugin on                   " required!
  syntax on

  "set background=dark
  "colorscheme jellybeans
  set hidden
  set autoindent
  set ruler
  set nostartofline
  set laststatus=2

  set confirm
  set visualbell
  set mouse=a
  set number

  set shiftwidth=2
  set softtabstop=2
  set expandtab
  set spelllang=en_gb


 au VimEnter * RainbowParenthesesToggleAll

 "Indent guide
 let g:indent_guides_auto_colors = 0
 let g:vim_markdown_folding_disabled=1
 autocmd VimEnter,Colorscheme * :hi IndentGuidesOdd  guibg=red   ctermbg=3
 autocmd VimEnter,Colorscheme * :hi IndentGuidesEven guibg=green ctermbg=4
 autocmd BufRead,BufNewFile *.md setlocal spell

 if has("win32")
      set directory=c:\\tmp,c:\\temp
    elseif has("unix")
         set directory=/tmp
 endif

configureVim.sh

#!/bin/bash

mkdir ~/.vim

#Check if curl is installed
command -v curl >/dev/null 2>&1 || { echo "I require curl but it's not installed. Aborting." >&2; exit 1; }

#Install pathogen
mkdir -p ~/.vim/autoload ~/.vim/bundle; \  
  curl -LSso ~/.vim/autoload/pathogen.vim \
      https://raw.github.com/tpope/vim-pathogen/master/autoload/pathogen.vim

#Backup vimrc

if [ -f ~/.vimrc ]  
then  
  cp ~/.vimrc ~/.vimrc_backup
  rm ~/.vimrc
fi

#Check git is installed
command -v git >/dev/null 2>&1 || { echo "I require git but it's not installed. Aborting." >&2; exit 1; }

cp vimrc ~/.vimrc

#get plugins

cd ~/.vim/bundle  
git clone https://github.com/kien/ctrlp.vim.git  
git clone https://github.com/sjl/gundo.vim.git  
git clone https://github.com/scrooloose/nerdtree.git  
git clone https://github.com/kien/rainbow_parentheses.vim.git  
git clone https://github.com/scrooloose/syntastic.git  
#git clone https://github.com/altercation/vim-colors-solarized.git
git clone https://github.com/Lokaltog/vim-easymotion.git  
git clone https://github.com/tpope/vim-fugitive.git  
git clone https://github.com/nathanaelkane/vim-indent-guides.git  
git clone https://github.com/plasticboy/vim-markdown.git  
git clone https://github.com/tpope/vim-endwise.git  
git clone https://github.com/tpope/vim-surround.git  
git clone https://github.com/nanotech/jellybeans.vim