My Vimrc

bairui, y u no?

I've been asked before why my ~/.vimrc is not available online.

I guess, deep down, there are probably feelings of apprehension about releasing something so personal and close to one's heart; that insensitive malcontents might throw stones through the windows and graffiti the walls.

A bigger and more real concern is that of the endemic affliction known as Cargo Culting. Vim is like a martial art. Mastery comes from years of rigorous, dedicated practice, lots of trials and accidents and occasional brilliant successes, study at the feet of other masters and plain old Time at the coal-face. There is no short-cutting this process. You can speed it along with the right approach, but you can not just dump a master's vimrc file at $HOME and think you're playing with the big boys now. That will only lead to tear-stained keyboards and hosed code.

Heh... I'm distorting the truth only slightly here, but I was just told a funny story that allegorises this tragedy: A good friend and fellow vimmer had his Vim set up with :cursorcolumn=80 to remind him where to constrain his code lines. A colleague passing by gasped, "Oh no! Your monitor is broken!". Upon explaining that everything was ok, that the monitor was indeed working fine and that Ti... er, I mean, my friend wanted the line there, the enquirer left mollified and quietly envious of this awesome feature that his Ec, er, I mean, editor didn't have. A week later, my friend discovered his colleague's computer had a dark red line too; only, his was drawn on a transparent plastic strip sticky-taped to the monitor.

:-)

In fairness... the colleague was mocking my friend, so this is not really a story of Cargo Culting, but it shows the phenomenon well, I think. Someone sees something awesome in another person's setup and blindly copies it in the vain hopes it will bring them equal fortune too.

While not a Vim Master, I do have the occasional sharp implement that is best kept away from curious beginners. To that end, I am not just pushing my vimrc up for you to copy blindly. I give you here a snapshot in time. I have annotated it in the hope that it shows you why I chose a certain option or implemented a particular solution. It is my intention that you learn how to wield this cutting edge tool with ample guidance and clear models.

So much for the What and Why. Now a little bit about the How. An expert is not born expert. Years of training go into the growth of his skills, techniques, tools and knowledge. My vimrc has grown over the years in the same way, from humble beginnings through proud days of development and embarrassing times of foolishness all the while with unremitting hubris.

You can see examples of that growth in the snapshot below. In various places I note pieces that might eventually grow to the point of becoming their own plugin. When they do, they will be cut out of my vimrc and put into a standalone plugin of their own. Doing this helps keep the core vimrc down to a manageable size. It also allows me to share it more easily with others.

Finally, the process of cleaning up my vimrc for public release was quite a long and intellectually grueling one. It generated the philosophical challenge: what is my Vim configuration? By this I mean, it occurred to me that my vimrc was not the entirety of my Vim configuration. I have extracted and encapsulated within plugins many times over productive growths from my vimrc throughout the years. They serve me well still, sitting mostly quietly at the sides, doing their jobs unnoticeably well. To forget these pieces and not include them in my configuration would be disingenuous. They provide many of the commands that my muscle memory relies on within Vim today. They are my Vim configuration; certainly as much as my vimrc can claim to be, anyway.

My Vimrc

" ~/.vim/vimrc_common
" Barry Arthur

" My 'office' has several people using Vim who would like to have a pleasant
" configuration without needing a neckbeard to get it. Sharing all of my vimrc
" with them would not only give them unicorns and rainbows, but would also
" leave them with dangerous sharps and nasty unexpecteds. To solve this
" problem, the vimrc is split into three parts:
"
" * A common shared by all (this file)
" * A $USER pre for things that the common depends on (like mapleader)
" * A $USER post for things that the user would like to override

" Use Vim not vi
"----------------
set nocompatible


" Initialize Plugin Manager
"---------------------------
" https://github.com/Raimondi/vim-pathogen
" Raimondi's pathogen allows multiple bundle dirs and
" provides a command interface to interrogate, enable and
" disable plugins.

call pathogen#infect('bundle/shared', 'bundle/local')

" bundle/shared contains plugins used by all
" bundle/local is for personal plugins


" Filetype & Syntax Highlighting
"--------------------------------
filetype plugin indent on
syntax on


" User Pre File
"---------------
" For things like (:help mapleader)
" Note: use <leader>gf to jump to the file
source $HOME/.vim/vimrc_${USER}_pre


" Options
"---------
" Use :help 'option (including the ' character) to learn more about each one.

" Buffer (File) Options
set hidden                     " Edit multiple unsaved files at the same time
set confirm                    " Prompt to save unsaved changes when exiting
set viminfo='1000,f1,<500,:100,/100,h  " Keep various histories between edits

" Search Options
set hlsearch                   " Highlight searches. See below for more
set ignorecase                 " Do case insensitive matching
set smartcase                  "   except when using capital letters
set incsearch                  " Incremental search

" Insert (Edit) Options
set backspace=indent,eol,start " Better handling of backspace key
set autoindent                 " Sane indenting when filetype not recognised
set nostartofline              " Emulate typical editor navigation behaviour
set nopaste                    " Start in normal (non-paste) mode
set showmode                   " Necessary to show paste state in insert mode
set pastetoggle=<f11>          " Use <F11> to toggle between 'paste' and 'nopaste'

" Indentation Options
set shiftwidth=2               " Number of spaces for each indent level
set softtabstop=2              " Even when using <Tab>'s
set expandtab                  " When pressing <Tab>, replace with spaces

" Status / Command Line Options
set wildmenu                   " Better commandline completion
set wildmode=list:full         " Expand match on first Tab complete
set showcmd                    " Show (partial) command in status line
set laststatus=2               " Always show a status line
set cmdheight=2                " Prevent "Press Enter" message after most commands
set statusline=%f%m%r%h%w\ [%n:%{&ff}/%Y]%=[0x\%04.4B][%03v][%p%%\ line\ %l\ of\ %L]

" Interface Options
set number                     " Display line numbers at left of screen
set visualbell                 " Flash the screen instead of beeping on errors
set t_vb=                      " And then disable even the flashing
set mouse=a                    " Enable mouse usage (all modes) in terminals
set ttimeout ttimeoutlen=200   " Quickly time out on keycodes
set notimeout                  "   but never time out on mappings
set list                       " Show tabs and trailing whitespace
set listchars=tab:⇥\ ,trail:·  " with nicer looking chars
set shortmess=atI              " Limit Vim's "hit-enter" messages


" Key Maps, Functions, Commands and Abbreviations
"-------------------------------------------------

" General Editing
""""""""""""""""""

" Help terms can include characters typically not considered within keywords.
function! ExpandHelpWord()
  let iskeyword = &iskeyword
  set iskeyword=!-~,^),^*,^\|,^",192-255
  let word = expand('<cword>')
  let &iskeyword = iskeyword
  return word
endfunction

" F1 to show context sensitive help for keyword under cursor
" Deliberately left off the terminating <cr> to allow modification.
" Moves the cursor to the beginning of the term for contextual markup.
" (:help help-context)
nnoremap <F1> :help <c-r>=ExpandHelpWord()<cr><c-left>

" F9 to show VimL function list
nnoremap <silent> <F9> :help function-list<cr>

" Grep help files for a pattern
command! -nargs=* -complete=help HG helpgrep <args>


" Resize windows
nnoremap <leader>h :exe "resize " winheight(0) / 2<cr>
nnoremap <leader>H :exe "resize " winheight(0) * 2<cr>
nnoremap <leader>w :exe "vertical resize " winwidth(0) / 2<cr>
nnoremap <leader>W :exe "vertical resize " winwidth(0) * 2<cr>

" Move between windows
nnoremap <a-left>    <c-w>h
nnoremap <a-down>    <c-w>j
nnoremap <a-up>      <c-w>k
nnoremap <a-right>   <c-w>l


" Move up and down visually across wrapped lines
nnoremap <Down>  gj
nnoremap <Up>    gk

" Move left and right across whole (:help WORD)s
nnoremap <Left>  B
nnoremap <Right> W


" Execute current line
nnoremap <silent> <leader>E :exe getline('.')<cr>

" Toggle list mode
nnoremap <silent> <leader>L :set invlist list?<cr>

" Reformat paragraph
nnoremap <silent> Q gqap

" F2 to toggle spelling
nnoremap <F2> :set invspell spell?<cr>

" F3 to trigger snipmate
" Note: This map might change in the future; it's
" currently part of an extended <Tab> experiment.
let snips_trigger_key = '<F3>'

" F6 to Toggle the TagBar
nnoremap <silent> <F6> :TagbarToggle<cr>


" Diffing
"~~~~~~~~~
" Note: This is begging to be moved into a Diffing plugin

" View changes made to a buffer since it was last saved
" storing original line in global g:diffline because it's used by several
" different diff commands - do and dc
function! DiffOriginal()
  let g:diffline = line('.')
  vertical new
  set buftype=nofile
  " 0read prevents a blank line at the top of the buffer
  " ++edit retains current option values for read operation
  " # is the alternate buffer (:help :_#)
  0read ++edit #
  diffthis
  exe "normal! " . g:diffline . "G"
  wincmd p
  diffthis
  wincmd p
endfunction

" Demonstration of creating a command that calls a function.
command DiffOrig :call DiffOriginal()<cr>

" Demonstration of a map calling a command.
nnoremap <silent> <leader>do :DiffOrig<cr>

" Close a DiffOrig session
nnoremap <silent> <leader>dc :q<cr>:diffoff<cr>:exe "norm! ".g:diffline."G"<cr>


" Highlighting
"~~~~~~~~~~~~~~
" Note: These might move into the SearchParty plugin

" Temporarily clear highlighting
nnoremap <silent> <c-l> :nohlsearch<cr><c-l>

" Toggle search highlighting (:help set-inv  :help E518)
nnoremap <c-Bslash> :set invhlsearch hlsearch?<cr>

" F8 to highlight all occurrences of word under cursor
" Note: Needs a better key. <F8> seems arbitrary
nnoremap <silent> <F8> :let @/='\<'.expand('<cword>').'\>'<bar>set hlsearch<cr>


" Make
"~~~~~~
" Note: Again, a candidate for extraction into an external plugin

function! QuietMake()
  write
  silent! make
  copen
  if empty(len(filter(getqflist(), 'v:val["valid"]')))
    cclose
  else
    wincmd w
  endif
  redraw!
endfunction

" Demonstration of calling a function from a map
nnoremap <silent> <leader>ma :call QuietMake()<cr>


" Find-in-Files
"~~~~~~~~~~~~~~~
" (:help :abbrev :lvimgrep :lwindow)
cabbrev lvim
      \ lvimgrep /\<lt><c-r><c-w>\>/gj
      \ *<c-r>=(expand("%:e")=="" ? "" : ".".expand("%:e"))<cr>
      \ <bar> lwindow <c-left><c-left><c-left><right>


" Plugins
"---------

" Matchit - comes with Vim but needs to be enabled (:help matchit-activate)
runtime macros/matchit.vim

" Third-party plugins:

"" https://github.com/tpope/vim-surround.git
"" https://github.com/scrooloose/nerdcommenter.git
"" https://github.com/scrooloose/nerdtree.git
"" https://github.com/garbas/vim-snipmate.git
"" https://github.com/honza/snipmate-snippets
"" https://github.com/vim-scripts/Tagbar.git
"" https://github.com/vim-scripts/NumberToEnglish.git

" Home-grown plugins:

"" https://github.com/dahu/Insertlessly.git
"" https://github.com/dahu/Nexus.git
"" https://github.com/dahu/Firstly.git
"" https://github.com/dahu/Zzzomg.git
"" https://github.com/dahu/vim-mash.git
"" https://github.com/dahu/SearchParty.git
"" https://github.com/dahu/Vimple.git
"" https://github.com/Raimondi/vim-buffalo.git
"" https://github.com/Raimondi/vim-pathogen


" Auto Commands
"---------------
" (:help :autocmd)
if has("autocmd")
  augroup vimrc
    au!

    " Jump to last-known-position when editing files
    autocmd BufReadPost *
          \ if line("'\"") > 1 && line("'\"") <= line("$") |
          \   exe "normal! g'\"" |
          \ endif

    " Default omni completion based on syntax
    if exists("+omnifunc")
      autocmd Filetype *
            \ if &omnifunc == "" |
            \   setlocal omnifunc=syntaxcomplete#Complete |
            \ endif
    endif
  augroup END
endif


" GVim
"------
if has("gui_running")
  set t_vb=                    " t_vb gets reset when entering GUI mode
  set guifont=Terminus\ 14
endif


" User Post File
"----------------
" For overriding the common settings defined here
" Note: use <leader>gf to jump to the file
source $HOME/.vim/vimrc_${USER}_post