A ViM Workflow Primer

Perhaps you have thought of using VIM as an editor, but found the list of things required to get it setup too daunting. VIM can be an extremely powerful editing tool, but lots of functionality is tucked away inside plugins and can be hard to discover. This article will skip the basics of VIM, and instead focus on establishing a workflow, and introducing some popular plugins to make life easier. If you are just starting with VIM, I would recommend trying an [interactive VIM tutorial][1], or (even enjoy a VIM based game!) as a starting point before reading this guide.

VIM Configuration Options

Settings in VIM can either be applied in the editor, or can be read in from your .vimrc file. You can modify settings from inside VIM by typing :set <option> For example, we can turn on soft tabs, with two spaces by typing :set tabstop=2 . This setting is applied instantly for the current editor instance, and any tabs / buffers opened inside of it. When then editor is closed, this setting will revert, which makes it ideal for trying out new settings before making them permanent. You can also restore any settings to their default by issuing the command suffixed with an ampersand, e.g. set tabstop& . For boolean values, you can toggle the setting by suffixing the command with an exclamation point, instead of an ampersand.

If you are happy with a setting, and wish to apply it to every instance of VIM, you can place it in the VIM configuration file located at ~/.vimrc by default. If this file doesn’t exist, you can create it. The same commands you apply from inside of VIM can be listed in this file - one option per line. Note: When you place them in the .vimrc file, omit the prefixed colon.

Common Options

You may have seen people sharing their .vimrc files in version control. While this encourages the sharing of settings, I don’t find this approach too particularly helpful to newcomers unless the options are well commented. Applying a shotgun blast of options can significantly change your VIM editor without you having the understanding which options do what. I would recommend instead applying each option individually as you have a need for the option to gain maximum familiarity with your editor, and your configuration.

I do recommend backing up your vimrc (and any other rc files for that matter) in version control for your own use. This backup allows you to apply your settings to all of your computers for consistency. Even if you borrow a machine for a quick editing session, you can pull down your rc files and quickly recreate your environment.

While I don’t recommend blindly copying and pasting these commands, I would like to give a quick list of the most common VIM options:

• set noswapfile Suppresses the .swp files that would otherwise litter your working directory
• set nu Show line numbers in the left gutter
• set autoindent Automatically space the caret to the correct indentation level when creating a new line
• set softtabstop=2 Change the number of spaces in a soft tab
• syntax on Turn on syntax highlighting

For more options, check out this article from Linux Journal

File Management

When working with code, it is common to jump between multiple files, and to search for references to function definitions located in various places around the project. This can be easily managed by VIM using tabs, buffers, and a few nice plugins to extend search and file management.

Change your working directory to your project, and open VIM by issuing vim By default, netrw shows a listing of files and directories. You can open these files using by using the movement keys, then pressing enter . This opens the file in a new buffer. A buffer is analogous to an open file. You can see a list of buffers by issuing :ls , or :buffers . If you want to switch to another buffer, you may issue the command :buffer <number> replacing the buffer number with the file you wish to view.

You may also use splits to show multiple buffers on the screen simultaneously. If you open a directory, VIM lists the directory using the netrw plugin by default. To open a file from netrw in a split mode, you can press h for a horizontal screen split, or v for a vertical screen split.

VIM also offers support for tabs, with each tab mapping to a buffer. A file can be opened in a tab from netrw by pressing t , or by typing :tabe <filename> Tabs can be cycled through with the :tabprev and :tabnext commands.

Plugins to extend window functionality

Bufexplorer allows easy access of open buffers (files) inside of VIM. Open buffers can be sorted by most recently used, filename, or file extension. Note: I didn’t have any luck installing this plugin via Pathogen, but you can unzip the package into your VIM directory.

Search

Searching in VIM can be done inside of a file, or in a given directory (such as the root of your project). The easier of the search types is searching within a single file. You can search at any time by pressing the / key, followed by your search term. When you press enter, the caret will jump to the first match. You can cycle through the matches by pressing n for next, or N for previous. Note: There are additional options to do incremental search, and highlight matching results.

To search across multiple files, VIM includes a built in grep tool. You can invoke this tool by typing :vimgrep /pattern/g **/.* . This will search for the regular expression pattern recursively and globally. This takes search terms, or regular expressions, and supports many of the regex flags. To view the list of matches, you can open the quickfix window by issuing :cw . The results will be listed, and can be opened in the list window by pressing enter when focusing on the file.

Admittedly, the default searching settings in VIM can be difficult to work with, especially given how often performing a search can occur. You can make the default search behavior of VIM work more in line with other editors by setting an option to not escape special regular expression characters. Set the option :noremap / \/v to enable “very magic” mode, which allows you to use normal regular expression searching.

Plugins to extend search

CtrlP mimics the fuzzy matching provided by other editors including Textmate, SublimeText, and Rubymine. Pressing Ctrl+P allows you to type any part of a file path - directory or name, and it will locate all matching files. This is similar to the popular Command-T plugin, but without the Ruby dependency for VIM. Ack this is a fantastic search tool that is a solid replacement for grep. The difference between ack and grep is the automatic exclusion of common file locations and patterns that yield returns you don’t are to see (such as inside of the .git, or .svn directories)

Built-in Functionality

The following is a list of built in features that VIM provides that may aid you in development without the need for plugins:

Spell checking is built in, and some colorschemes like Zenburn support syntax highlighting for misspelled words. A user can move the cursor over a misspelled word and press z= to see a list of similar words to choose from. Word completion is a convenient way to auto-complete a long word. Start typing the first few characters, then press [Ctrl+n] to bring up a list of words to expand to. You can cycle through next and previous entries in the list using [Ctrl+n] and [Ctrl+p] respectively.

Plugin Management

Plugins can be installed into your ~/.vim/ directory. Download your plugin, and extract it into this directory. Often, plugins will be a collection of files, each needing to be extracted to a particular directory, such as the doc and plugin directories. In order to correctly install them, unzip the plugin archive from inside the ~/.vim directory so the files in subfolders are automatically placed in right paths.

Other plugins will come distributed in .vba (VIMball) format, and will refer to you sourcing the file from inside of VIM. This is done by opening the .vba file inside of VIM and typing :source % .

Keeping plugins in VIM up to date can be a pain, since there is no built in package management utility to inform you when updates happen. Because of this, a popular solution is to clone the plugins from their repositories, instead of downloading and unzipping. Because many of these plugins share common subfolders, you would have to keep them isolated from one another, and mix them all in together at load time. Fortunately for us, the pathogen VIM plugin does just this. It allows us to place our plugins in separate folders inside of the ~/.vim/bundle directory, which is all loaded into VIM with the entry call pathogen#infect() in your .vimrc file.

Check out pathogen as a starting point for managing all other plugins.

Popular Plugins

Several of VIM’s more popular plugins are listed below for your reference. These are broken down by categories.

Editing

• Ctags
• Tcomment
• Scratch
• Surround

File Management

NerdTree shows a hierarchical listing of all of your files. You can select any file in the list to open, or change directories, and list its contents. This plugins has lots of options for navigating files.

External Services

vim-fugitive integrates Git into your editor so that you can execute many of the commands on a file without having to shell out, or change tabs. A great example is running Gblame on an open file and seeing the results in the gutter of the file pane. Gist DBExtensions

Ruby on Rails Specific

vim-rails offers lots of nice awareness with Ruby on Rails projects. Plugin feature highlights include gf to open partials, and often times modules. Context switching between model, view and controller can also be performed with :Rmodel :Rview and :Rcontroller respectively. Additional syntax highlighting for Rails methods is provided such as validation, and association class methods. Method completion is also available with a list of abbrevions expanding to full text using the tab key. A list of abbreviations can be found on the vim-fugitive plugin page on Github

Final Thoughts

VIM can be a very powerful editor. Its axiom of modal operations makes it an incredible pairing for writing - as long as you stick with it long enough to grok its concepts. If you feel like your past editors have needed too much clicking, or keystrokes to accomplish everyday tasks, VIM may be just for you. This guide will hopefully create a starting point for users familiar with the VIM basics, but who are eager to bridge the gap between understanding of individual operations, and the application of a workflow in their editing needs.

Do you use any plugins that we missed, or have any additional helpful tips to share? We would be happy to hear them, so let us know!
-Ben Simpson