Wednesday, July 27, 2011

Finding your way in vim

Vim is quite powerful programmer's editor, but has a very steep learning curve and it takes time to configure it properly. In this tutorial I'd like to share my experiences with configuring vim for efficient symbol, buffer and file navigation. In other words, I'm going to focus on finding these things easily in vim and ignore all other configuration aspects. Getting these things right seems to be the most confusing part for a lot of people who can otherwise use vim already. It's also the part that gives a big efficiency boost when programming or just browsing code, especially when it comes to finding symbol definitions quickly.


This is by no means a definitive guide on the subject. It' just a bunch of things I learned over years when using vim. Vim evolves, new plugins get developed, so the methods I list here may not neccessarily be the best solutions. But they should work and they do the job for me. These methods should work for pretty much every popular programming language, such as C, C++, Java, Python, Ruby etc.

Looking for symbols

A word of caution first: there is no perfect symbol-based navigation for programming languages such as C++ or Java in vim, as vim doesn't perform any syntax analysis of the code.  So, for example, it's not possible to go to the right definition of foo->bar() in C++ code if there are multiple definitions of bar() method, because vim has no notion of foo's type.


Jumping to tag with g CTRL-]
Vim has a built-in feature for looking for symbols based on so-called tags file. Tags file needs to be created first with ctags utility, e.g:

$ ctags -R /your/source/code

This will create tags file in your current directory. Add the following line to your .vimrc file to load tags automatically from current working directory as well as from specific path automatically:

:set tags=./tags,/home/user/your/source/code

From now on, you can jump to the first matching symbol definition by pressing CTRL-] over a symbol. CTRL-T will bring you back to where your search started. If there are several matching tags for a symbol (e.g. overloaded methods), you can use :tselect to choose the right one. Even better, if you know in advance there will be multiple matches, press "g CTRL-]" instead of CTRL-] over a keyword to bring the selection list right away. See :help tags for more information on how to use tags effectively.

Tagbar plugin window
Tags list

A very useful feature of most IDEs is the list of all classes/methods/symbols for all open files. This can easily be achieved in vim by installing a plugin such as Tagbar or Taglist. Both have similar capabilites, but I tend to like Tagbar more, as it displays tags ordered by their scope and displays method signatures (unlike Taglist, which displays only names).

Cscope-based navigation

Cscope is similiar to ctags, only a bit more powerful since it's capable of searching for functions calling given function etc. To use this capabilities in vim you have to scan you source files with cscope first (e.g. 'cscope -R -b' in your source code directory). Cscope creates a cscope.out file that needs to be loaded in vim by :cscope add /path/to/cscope.out. A common idiom for doing this automatically on vim startup (taken from vim help - see :help cscope) is:

if filereadable("cscope.out")
    cs add cscope.out
    " else add database pointed to by environment
elseif $CSCOPE_DB != ""
    cs add $CSCOPE_DB
Once loaded, cscope symbol database may be queried by issuing :cscope find with a query type and symbol name, e.g. to search for functions calling given function, type:

:cs find c foobar

This is not very convient to type, so you can define mappings for all cscope queries like this:

nmap <C-\>s :cs find s <C-R>=expand("<cword>")<CR><CR>
nmap <C-\>c :cs find c <C-R>=expand("<cword>")<CR><CR>

... and so on.

If you use tags and cscope at the same time, they are independent of each other, use different keyboard shortcuts and need to be queried separately. This can be solved by using :cstag for symbol defintion lookups: cstag searches both databases (by default cscope is searched first). And if you set cscopetag option, i.e.

:set cscopetag

then all tags queries (like CTRL-]) will use :cstag instead, so both databases will be searched. 

Grep search results
Grep-based searching

Searching for symbols with grep doesn't sound too attractive, but it's actually quite powerful once combined with a handly shortcut key and as long as the symbol you're searching for is not too common.
First off, I highly recommended installing ack-grep, which is a grep-like utility designed specifically for grepping source code files. Then configure vim to use it instead of regular grep - e.g. put this in your .vimrc:

set grepprg=ack-grep\ --cpp\ --cc\ --perl\ --python\ --make

Then define a shortcut key for grep, e.g.
:nmap _g :grep <C-R>=expand("<cword>")<CR><CR>

Pressing _g will grep source code files recursively, starting from the vim's current working directory, for the word under the cursor. Vim places grep results in so called 'quickfix' window, which you can bring up by calling :cwindow. You can navigate through quickfix entries by calling :cnext and :cprev. It's very usefull to map keys for them as well:

:map <F7> :botright cwindow<CR>
:map <F5> :cprev<CR>
:map <F6> :cnext<CR>

If grepping in the current directory is not what you want, then you may want to play with 'expand' macro to grep starting from current file's directory, or from a predefined directory and add new shortcuts for them -- here is how to create a Gvim menu entry for them:
:amenu Devel.Grep\ file\ dir :grep <C-R>=expand(expand("<cword>") . " " . expand("%:h"))<CR><CR>
:amenu Devel.Grep\ source\ dir :grep <C-R>=expand(expand("<cword>") . " " . expand("~/src"))<CR><CR>

Buffer navigation

Standard vim capabilities for navigating to opened files (buffers) are a bit limited when working with large number of files, so installing external plugin(s) is highly recommended. Just for the record, the standard commands for buffer navigation in vim are:
:ls -- shows buffer list
:buffers -- same as above
:bnext -- go to next buffer
:bprev -- go to previous buffer
:[N]b -- edit Nth buffer

There are several plugins that simplify buffer navigation, but I recommend the following: bufexplorerbuffergator and buftabs. Bufexplorer provides a sorted list of all the buffers, which can easily be navigated with cursor keys; pressing ENTER over buffer name makes it active. By default buffers are sorted in MRU (most recently used first) order, but this can easily be changed by pressing 's' in the bufexplorer window. Bufexplorer can be activated by \be, \bv and \bs keyboard shortcuts, but since I use it a lot I prefer a simpler shortcut, e.g. F3 key alone:

:imap <F3> <ESC>:BufExplorer<CR>
:map <F3> :BufExplorer<CR>

Buffergator is similiar, but makes it easy to preview buffers without leaving list of buffers. Upon invocation with \b (or :BuffergatorToggle), a new vertical window with buffers list is opened. CTRL-N, CTRL-P and SPACE keys can be used to navigate the list and preview buffers. ENTER key over buffer name opens it for editing and closes buffer list. One problem buffergator has is its slow response time on invocation: for some reason it takes 1-2 seconds to bring the list of buffers up, whereas it's instantaneous with bufexplorer.

Buftabs is a littler helper addon that is worth installing alongside bufexplorer and/or buffergator. It provides a tabs-like list of buffers displayed in the bottom of the window which is very handy for switch buffers in a circular way, in particular if you map :bprev and :bnext to keys such as CTRL-Left and CTRL-Right:

:noremap <C-left> :bprev<CR> 
:noremap <C-right> :bnext<CR> 

File navigation

The standard way for finding files is via :Explore [DIR] (or :edit [DIR] and :edit [FILE]). They both support filename completion with TAB key. Explore may be used to find files recursively, if you know only part of a file name, e.g:

:Explore **/*foo*

If you know complete file name, but not its path, you can use vim's built-in find command, e.g:
:find foobar.cpp

This will search for the file in all paths listed in vim's 'path' variable, which is current directory and /usr/include by default. You may want to set to also include subdirectories of your sources directory, for example:

:set path=.,~/src/**,/usr/include,,

Vim's path variable has one more use: it allows for opening files whose name is under or after the cursor. A typical use case is opening an included file in C/C++ source code, by moving over file name in the #include directive, and pressing 'gf' (goto file). Quite handy.

There are plugins which make finding files easier. One of the most useful is NERDTree, which implements a nice filesystem explorer in the form of a tree structure. It's very fast (uses caching), configurable (screen position, list of file patterns to be ignored etc. can be adjusted) and smart (e.g. remembers last cursor position when toggling off and on). It's so useful that its worth having a dedicated keyboard shortut for it, e.g.

:imap <F4> <ESC>:NERDTreeToggle<CR>
:map <F4> :NERDTreeToggle<CR>


The above tips should improve your day-to-day productivity a lot when programming. Go use it, learn it and improve. And let me know in the comments about your ideas and improvements!


xxx said...

great articles.thx for that

steven said...

You might want to checkout ack-grep [], there is plugin for vim.

Ari Hershowitz said...

Very helpful article. Step one to navigate in vim for me has been NERDTree []

Using NERDTree in a vsplit window, and ctrl-W-ctrl-W to move between them gets me most of the navigation I need.

tasuki said...

Cool stuff.

Just one improvement, for setting tags file, I use this one:
set tags+=tags;/

That searches for the tags file in current directory, and then subsequently parent directories until it finds a tags file in one of them. That's useful if you jump around directories.

simon said...

I can't live without Command-T for opening files

Anonymous said...

Nice article, hope it helps me move from using vim as a noob to a expert.

The Tinkerer said...

vim 7.3 now has support for completing the filename for the :find, :tabfind and :sfind commands so you don't have to worry about typing the whole name.

kang said...

should probably include something about the omnicompletion

Pawel Stolowski said...

Thanks for all hints and good words! I didn't mention omnicompletion, since I focused on navigation only. Thanks for hint on Command-T - cool thing!
ack-grep and NERDTree were mentioned in article.

Anonymous said...

I have no delay when invoking buffergator. Do you have BufExplorer and buffergator installed at the same time? If so, then the reason for the delay you experience is that after typing '\b', Vim has to time out to make sure that you are not typing '\be', '\bs', etc. which are already defined. If you map ':BuffergatorOpen' to, for example, '', you may find no delay.

Anonymous said...

Typo fix:

"If you map ':BuffergatorOpen' to, for example, 'F3' or some other key, you may find no delay."

Raymond Tay said...

Excellent post! Thanks for sharing

Nick Coleman said...

For buffer navigation, I have gone back to basics.

" show buffers
nnoremap :ls
" switch to buffer number
nnoremap \1 :b 1
nnoremap \2 :b 2
nnoremap \9 :b 9
" toggle buffers
nnoremap \\ :b #

F1 shows the buffer list; \1 switches to buffer 1, \2 switches to buffer 2, etc; \\ toggles buffers like ctrl-^.

These are instantaneous, instead of the delay that some buffer navigation plugins seem to have.

Jeet Sukumaran said...

Hi, I am the author of Buffergator. The reason for the delay that you find when opening Buffergator using the default key "b" is that Vim is waiting to see if you are going to type another letter, because BufExplorer defines "bs" and "bv" etc. as keymaps. You should remap Buffergator's default key if you wish to keep both BufExplorer and Buffergator.