To Install

(Re)move ~/.vim and ~/.vimrc if you have them already, and run:

git clone https://github.com/pivotal/vim-config.git ~/.vim
~/.vim/bin/install

Updating

Fetch the latest version of vim-config and install all the new bundles by running:

~/.vim/bin/update

Functionality

Plugins and configuration provide most of the functionality of the pivotal vim config. Below is a broad overview of the included plugins and what they do. Each plugin is linked to its documentation page. When reading the docs, keep in mind that this config has comma mapped as the leader key.

Ruby / Rails

• vim-rails lets gf and :Rextract work on partials, highlights Rails functions.
• vim-endwise automatically puts in ends for your if and do blocks.
• vim-ruby-refactoring gives some IDE-like refactoring support to vim. A favorite is :RExtractLet (aliased as ,rel) which takes a local variable in a spec and makes it into a let statement. Others are :RAddParameter, :RInlineTemp, :RConvertPostConditional, :RExtractConstant, :RExtractLocalVariable, :RRenameLocalVariable, :RRenameInstanceVariable, :RExtractMethod. They can also be accessed with the leader key followed by the capital letters in the command, so :RAlphaBeta becomes ,rab.
• vim-blockle lets you change a do..end into a {..} by pressing b with the cursor on part of the block.
• rbenv.vim adds a small amount of integration with rbenv.
• rake.vim gives you a lot of the same niceties that you get from rails.vim except for non-Rails Ruby projects.
• Convert a line with local_variable_foo to let(:local_variable_foo) { double(:local_variable_foo) } with ,ld. Just place your cursor anywhere on the variable and press ,ld.

General Editing

• vim-surround helps add/remove/change surround parentheses, quotes, and XML tags. Inside of "yolokitten", type cs"' to switch the surround double quotes to single quotes. t can generally be used to refer to XML tags, so inside of <tag>Hello</tag> you can do cit to modify the word "Hello." To add quotes around something, you can use the command ys followed by a motion and the character to surround it with. For instance, inside of "hello", typing ysiw( will change it to "( hello )".
  • vim-repeat lets plugins override . (the period) to repeat commands. Allows you to use . with the vim-surround magic above.
• nerdcommenter lets you comment and uncomment things. The most useful command is ,/ which comments or uncomments either the current line or the currently selected block. This config has ,/ mapped to the Toggle instead of ,c as listed in the docs (the rest of the commands use the c as listed).
• vim-unimpaired contains a bunch of shortcuts for longer commands that start with colons. Some of the better ones are:
  • ]q and [q to go back and forth through the quickfix list (the result of using :Ag or :Ack).
  • [f and ]f to navigate through files in the same directory as the current file.
  • ]n and [n to go through merge conflicts.
  • It's not provided by this plugin, but [h and ]h let you move through working copy changes in git in a similar manner.
• gundo lets you navigate your vim undo history as a tree. Ever do that thing where you undo a few times, make a change, and want to undo your initial undo? Type :GundoToggle and use the arrow keys to find the version you want.
• tabular makes it easy to make pretty ASCII tables and align equal signs of successive variable definitions.
• syntastic runs your compiler or interpreter and displays syntax errors in vim. A >> in the gutter means there is an error on that line, you can mouse over it for more details.
• vim-airline sets the status bar and makes it more configurable and useful by showing things like the current Git branch, etc.
• supertab lets you press Tab after Ctrl-P or Ctrl-N to cycle through completion options.
• j-split converts spaces in the current line to new lines by pressing ,j (kind of like a simple use of xargs).
• diffthese lets you use vimdiff on open windows. You can use :DiffLeft, :DiffRight, etc. :DiffThese lets you specify window numbers with number 1 in the top left, increasing clockwise.
• camelcasemotion defines motions to work on camelCase text. The usual motions w, b, and e get the friends ,w, ,b, and ,e that move within a word. If your cursor is on the first letter of lolCatAge and you press ,w, you will go the "C" in "Cat." You can also use them as text objects, for instance if you are on the lowercase "a" in "lolCatAge" you can type ci,w to change it to 'lolDogAge'.
• edit-plus lets you refer to line numbers when opening files. For instance, type :EP README.md:10 to jump to line 10 of your helpful README. Sometimes when you type :e it is automatically changed to :EP. This is useful for opening test failures from the command line into vim.
• quickfixfix maps the NERDtree key bindings to the quickfix window. If you open NERDtree (\\) and press ?, the descriptions of o, i, s, and go can be used in the quickfix window.
• vim-easymotion lets you use see where repeated motions would take you. If you've ever used vimium's link navigation, it's like that. Type the leader key twice and a motion to see a bunch of annotations in your file based on where repeated uses of that motion would take you, then press a number to go there. For instance, to jump 2 words you can do ,,wb instead of 2w.
• regreplop lets you paste text over other text without destroying your default register. Usually, if you yanked something and wanted to paste it over a word using viwp, you couldn't paste it again because the word you deleted overwrote what you originally yanked. This plugin provides Ctrl-K to paste while keeping your buffer. You can use it in visual mode or follow with a motion. Very handy for repeated replacements.
• insert_mode_background_color changes the background color when you are insert mode.
• vim-cdo runs commands on every entry in the quickfix or location windows. For instance, if you just searched for something with :L9GrepBuffer foo or :Ag foo and want to change the foos you found into bar, you could run :Cdo s/foo/bar/. If you're doing a replacement like that, make sure not to do :Cdo %s/.../... with the percent sign because the first replacement in a file will mess up the later ones. :Ldo is the same but for the location list, and suffix your commands with /c to confirm changes.
• vim-snipmate and vim-snippets provide TextMate like snippets where you can jump around the snippet with the tab key.
  • vim-addon-mw-utils is a prequisite of snipmate
  • tlib_vim is as well
• vim-textobj-user allows definition of custom vim "nouns".
  • vim-textobj-rubyblock lets you use ar and ir to select Ruby blocks just like you can do a" to select a string.
  • kana/vim-textobj-line selects entire lines.
    • il selects the entire line without leading or trailing whitespace.
    • al selects the entire line with all whitespace except for the linebreak.
    • dd continues to select the entire line including the linebreak.
  • thinca/vim-textobj-between selects between arbitrary delimiters.
    • if<delimiter> selects the region between the delimiters, excluding the delimiters themselves.
    • af<delimiter> selects the region between the delimiters plus the delimiters.
    • Particularly useful with URLs. If | represents the cursor position: /demonstration/with/riculo|usly/long/pathname/ -> cif/notso -> /demonstration/with/notso/long/pathname/
  • Julian/vim-textobj-variable-segment selects pieces of snake case or camel case identifiers. If | represents the cursor position:
    • foo_ba|r_baz -> civquux -> foo_quux_baz
    • eggsAn|dCheese -> civOr -> eggsOrCheese
• YankRing lets you view and cycle through your previous copy and paste registers on the fly
  • After pasting use <C-tab> and <C-S-tab> to cycle through previously copied text.
  • In normal mode press F6 to view previously copied text. Select one to paste it.
• terryma/vim-multiple-cursors gives you multiple cursor support, similar to Sublime Text.
  • While in normal mode, press <C-n> to add a second cursor on the next occurance of the word or symbol under your cursor.
  • Use <C-v> to make a vertical selection, then press <C-n> to convert the selection into multiple cursors.
• editorconfig/editorconfig-vim teaches vim how to follow the rules defined in .editorconfig files in your project, so that you can unify project preferences across multiple editors. See the editorconfig homepage for more information.
• projectionist.vim gives you the ability to jump between related files, such as between a code file and its spec.
  • It also supports adding a .projections.json file to your project so you can teach Vim how to find the spec for the current source file. See the README for more details.
• rainbow-parentheses highlights nested parentheses, brackets, and curly braces with differing colors so you can match them up more easily.
  • Use ,rp to toggle rainbow parenthesis mode in the current file. By default it is off.
• neoformat lets you run the code formatter of your choice on your code, bound to gg-G.

Window Management

• ZoomWin lets you close all other windows with <C-w>o. You can restore all the closed windows with the same command. Useful with :tabo to close everything but what you're working on.

Searching

• ack lets you shell out to ack within vim using :Ack pattern [directory]. By default, results show up in the quickfix window. You can use :AckAdd to append to the quickfix window or prefix 'Ack' with an 'L' to use the location list (just like :grep's siblings).
• ag is the above but for ag (a faster ack replacement)
• vim-abolish deserves a few lines:
  • It replaces teh with the. Say hello to autocorrect memes, Ruby edition. You can define your own with a regex-like syntax.
  • It helps you replace things with capitalization differences. If you had the line foo = Foo.new, you could run :S/foo/bar/g to get bar = Bar.new (note the capital 'S'). You can also use curly braces like you would on the command line, for instance :%S/facilit{y,ies}/building{,s}/g.
  • It converts between camelCase and snake_case. Use cr followed 's' for snake_case, 'm' for MixedCase, 'c' for camelCase, or 'u' for UPPER_CASE (these work within the current word and don't take a motion).
• vim-qargs (stack overflow) is kind of like Cdo.
• ctrlp is a fuzzy file finder invoked by hitting Ctrl-P in normal mode and typing some part of the file name you'd like to open. This config also has ,f mapped to the same function.

Navigation

• nerdtree puts a directory tree on the left side of the screen. Press \ to open it at your project root, or Shift-\ to open it with the current file selected. You can press m to move, delete, or create files. Press ? inside the tree to get more help.
• tagbar puts ctags for the current file in a pane on the right. Make sure ctags is installed and then do :TagbarToggle to see them in vim.

Development Tool Integration

• vim-fugitive puts git into vim. It can do almost everything git related, some of the most useful features are:
  • :Gblame to blame the current file. Press enter on a commit to see the full commit. Do :Gedit to go back to the current version (or just open it again).
  • :Gread to check out the current file from git. Very useful if you made some experimental changes that you want to get rid of.
  • :Gbrowse to open the current file on GitHub, useful for sending links to other people.
• vim-gitgutter puts + and - signs in the gutter to show you what's changed in your working tree. Use [h and ]h to navigate between modified hunks. This plugin can slow down vim, so remove it if you're having problems.
• tmux-config integrates tmux with Vim. It helps with autosave support and pasting your tmux buffer into vim.
• vim-dispatch supplies :Make and :Make! which run in the background instead of blocking like :make.
• ConqueTerm lets your run interactive commands within vim. Try :ConqueTerm bash.
• vitality.vim makes Vim play nicely with iTerm2 and tmux. It adds things like cursor change on insert mode and focus-lost detection for triggering auto-save.
• test_server lets you use F9 thru F12 to run specs and report the output in vim.
• vim-simple-bdd generates method declarations from simple_bdd steps

Colorschemes

• Vivid Chalk
• Molokai
• Solarized (github)
• ir_black
• tomorrow
• candycode
• Color-Sampler-Pack
• colorschemes
• base16
• vim-airline-themes

Languages

• vim-ruby
• vim-javascript
• vim-markdown
• vim-slim
• vim-handlebars
• vim-coffee-script
• vim-haml
• vim-cucumber
• vim-cucumber-align-pipes
• mustache.vim
• vim-go
• scala-vim-support
• vim-clojure-static
• csv.vim
• vim-elixir
• vim-json
• vim-jst
• vim-jade
• vim-pug
• vim-jsx
• elm.vim
• vim-concourse

Advanced

Updating manually

First, fetch the latest vim-config via Git. You can also rebase or merge your own project-specific customizations.

To install the necessary bundles:

vim +PluginInstall +qall # or run :PluginInstall within Vim

To upgrade bundles to their latest version, use the bang version:

vim +PluginInstall! +qall # or run :PluginInstall! within Vim

tmux support (optional)

If you will be using VIM with tmux for remote pairing or window management, see the pivotal/tmux-config README.