vim setup on Mac OS X and Remote Hosts

If you want a consistent editor experience editing locally and remotely at the command line, then vim is what you want. This guide will walk you through setting up vim from scratch on Mac OS X for use both locally and over ssh. I’ve been a vim user for about five years. When I started out, I just copied and pasted a bunch of stuff from various other people’s .vimrc files and installed a whole bunch of unnecessary plugins. Over time, my .vimrc file and .vim directory became loaded with crud. So following these steps was a fresh start for me as well. When building up my vim installation, I followed the advice of this excellent tutorial:

Don’t put any lines in your vimrc that you don’t understand.

This is GREAT advice. If you want an editor with a glut of features that you can’t make sense of, use any GUI IDE. The functionality of your vim should start from bare bones and be built up BY YOU according to YOUR SPECIFIC NEEDS. In that spirit, I’m going to walk you through just the basics for my bare bones setup.

Starting Out

I recommend grabbing the latest vim version for Mac OS X using MacPorts:

sudo port install vim

This will also create a symlink from ‘vi’ to ‘vim’, so you just type ‘vi’ as no one would use the actually un-improved ‘vi’ in 2015.

Now, out of the box the MacPorts vim distribution can behave badly on OS X, making it hard to even edit the .vimrc to perform our initial setup! So let’s just add those options in with echo:

echo -e "set nocompatible\nset backspace=2" > .vimrc

Now that vim will actually function, we can use it to edit our .vimrc and add more settings (consult cheat sheet if you are shaky on vim movement):

vi ~/.vimrc

First, we’ll set up our tab and space settings to make editing subsequent blocks of code easier:

set tabstop=4
set shiftwidth=4
set expandtab

Then we’ll turn on syntax highlighting,code indentation, and line numbers:

syntax on
filetype plugin indent on
set number

Save the file,  then quit and reopen it.  We’ll be reloading the .vimrc often as we build it up, so now we’ll make a shortcut to do so. In order to do this, we’ll remap the leader key, which is the key most commonly used to define custom shortcuts. We’ll use the common choice of the comma key:

let mapleader=","
map <leader>rl :source ~/.vimrc

By now, you’ve probably noticed that pressing ‘escape’ repeatedly gets really annoying. Let’s remap that too:

inoremap <leader>jj <Esc>

We’ll also make a shortcut to leave insert mode and save the file, and make it work the same in normal mode and insert mode:

nnoremap <leader>s :w<CR>
inoremap <leader>s <Esc>:w<CR>

don’t worry about the different types of map commands. They’re all just means to the same end of remapping a key combination, and the nuances are irrelevant at this point.

This actually sums up most of the basic functionality we’ll need from our .vimrc – we’ll get most of the remainder from plugins. There are many vim plugin managers out there, and which one to use (or even whether to use one at all) is a contentious topic. Live your life and make your own choices. In this tutorial, we’ll be using Plug. We want plug to auto-install wherever we deploy our .vimrc, so put the following in your .vimrc (credit to qwertyboy of /r/vim for this sick code) :

let firstrun = 0
if !filereadable(expand("~/.vim/autoload/plug.vim"))
    let firstrun = 1
    silent !mkdir -p ~/.vim/{autoload,undo,backups}
    silent !curl -fLo ~/.vim/autoload/plug.vim \
call plug#begin('~/.vim/plugged')
call plug#end()

In between plug#begin and plug#end, let’s add the instructions to install our first plugin, the mustang color scheme:

Plug 'croaker/mustang-vim'

We’ll need to tell vim to use this colorscheme, so place this at the current bottom line of your .vimrc:

colorscheme mustang

Run :PlugInstall and reload your .vimrc to enable the colorscheme.

One of the most annoying features of vim is the poor interaction with the native OS clipboard; copying and pasting text is by default much more difficult than with competing editors (try it if you don’t believe me). Unfortunately, mapping the OS X command key is not possible when vim is run in the terminal (though it is possible in MacVim). As such, we’ll tell vim to use the OS keyboard:

set clipboard=unnamed

Note that ‘clipboard=unnamed’ also lets’ vim copy commands like ‘yank’ write to the os clipboard.

Deploying on Remote Hosts

This tutorial assumes that you want to use vim not just because of the editing speed that it affords, but also for its versatility and universality. You can count on having (or easily install) vim on whatever weird *nix system you are accessing via ssh; it makes editing code and miscellaneous other types of files easy and consistent in any environment. With this emphasis in mind, we’re now going to shift to setting up a dotfiles git repo (google “dotfiles git repo” for a million examples of people using this concept). Our .vimrc will be deployed in this repo. If you aren’t interested in multi-system deployment and just want some more cool plugins, skip ahead to the “more plugins” section.

Let’s add some code to our .vimrc so that we can edit Makefiles  while respecting their annoying tab conventions – we’ll be using Makefiles to deploy our .vimrc on other systems (credit to Shervin Emami on Stackoverflow for this line):

autocmd FileType make set tabstop=8 shiftwidth=8 softtabstop=0 noexpandtab

We’ll let our makefile create a symbolic link to this vimrc, so that whenever we update this dotfiles repo on one of our other hosts, that host will see it automatically without needing to run ‘make’ again. Put this in your ‘Makefile’ in the dotfiles repo.

    ln -s $(shell pwd)/vimrc ~/.vimrc

There you have it; no awful git submodule usage, no hauling around your .vim directory – just .vimrc and a Makefile. You can easily throw your .bash_profile and all the other dotfiles you want in the same repo. Try cloning the repo on a remote host, running make, and opening a file with vi – plugins will automatically install.

Going forward

Now that you have a basic, usable vim setup what you can easily deploy lots of different places, there are literally a million other things you can add to vim. They are, however, beyond the scope of this little document. You look at the .vimrc in my dotfiles for more tricks. I also suggest consulting the following: