Jumping aorund using Vim's Ctags

July 25, 2012

If you haven't used Ctags for VIM in Rails development then you are really missing out.

It’s a huge time saver to be able to jump to the location in the code where the method was defined . For Rail’s methods, I find that the code is well documented along with method examples.

Installing Ctags

These instructions assume you are using: VIM, OSX, and Ruby. If you are using Windows your mileage may vary.

Step one - Install the dependences:

Home brew
Install ctags- exuberant brew install ctags-exuberant

Step two - Building the Tag database

The Ctags database can be build simply by entering the commands ctags -R * in the source of the project. This will however only include those files in your project. If you however want to include the projects gems into your tag directory then you need to specify the location of the gem directory. It also pays to exclude the log directory, and git repository.

ctags -R --exclude=.git --exclude=log --exclude=*.js * <<gem_path>>;

This works fine but it can be a pain to work out the location of the gems directory, especially if you have a number of projects on the go and are using multiple Gemsets. Plus, I wanted to automate this using my favourite editor VIM rather than running the above terminal commands.

If you copy the below code into your vimrc file it will determine the gem directory and execute the command in the terminal. To build the Ctags database type <leader>ctag (hey presto)

Step three - Adding Code to Vim

The secret source is the Ruby method ENV['GEM_PATH'] that returns the project's gem directory. The terminal command is executed using Ruby's system method.

I have made this into a VIM gem that you can grab and add to your pathogen bundle directory.

 function! LoadCtagsRails()
   " Via Vim execute the below bash command (determining the gemset path name)
   " tags -R --exclude=.git --exclude=log * ~.rvm/gems/ruby-1.9.3-p194@silentsalesman_backend
   ruby << EOF
     class LoadCtagsRails
       def initialize
       update_ctags
       end
       def update_ctags
       vimputs("this can take a while ...")
       system("ctags -R --exclude=.git --exclude=log --exclude=*.js * #{gem_path}")
       vimputs("successfully updating ctags included gem directory #{gem_path}")
       end
       def gem_path
          ENV['GEM_PATH'].split(':')[0]
       end
       def vimputs(s)
       print s
       end
     end
     LoadCtagsRails.new
   EOF
 endfunction

 map <leader>ctag :call LoadCtagsRails() <CR> :echo "completed" <CR>

Really useful commands

To use Ctags simply select the method in question and type CTRL-] to jump to the documentation. I tend to use the command to CTRL-o to jump back to my previous location.

There are a number of other commands for methods that are useful. To get more details search under VIM's help

Vim Command	What is does
ts	shows the list.
tn	goes to the next tag in that list.
tp	goes to the previous tag in that list.
tf	goes to the function which is in the first of the list.
tl	goes to the function which is in the last of the list.

Summary

I would encourage you to give Ctags a go. I find going to the source is often the best form of documentation.

Chris Zingel