UsingRTagsTutorial

rtags (Ruby tags)

Are you looking for a Ruby IDE? You may not need to look further once you exploit the power of a good text editor like VimEmacs with tag support. tags allow you to jump between source code files. Just click on a name and the editor will take you there... See the tutorial below for information on installation and usage.

rtags is a Ruby replacement for [WWW] ctags - allowing for name navigation in source code using vim, emacs and others.

More information:

Project maintainer: PjotrPrins

Rtags Tutorial

Introduction

Editors that support programming will have some form of tag support. I'll describe here how it works with vim - but for other editors it should amount to something similar (see also VimEmacs).

Installation

rtags comes as a gem or with an install script which can be run from the command line. Download rtags from [WWW] http://rubyforge.org/projects/rtags/. If you chose the tar ball unpack it: 

tar xvzf rtags-$ver.tgz
cd rtags-$ver
su -c 'sh install.sh'

Now rtags should have been installed in /usr/local/bin. Run it with 

rtags --help

Note: you can also download and install a [WWW] Ruby gem, the preferred Ruby package manager. You may find the command to be something like 

/var/lib/gems/1.8/bin/rtags --help

Usage

Preparing the tags file for vim

In your source directory run rtags with a command like: 

rtags --vi -R

which recurses into directories encountered in the list of supplied files looking for files ending with '.rb' extensions (or when it has a #!/usr/bin/ruby line). If the list of supplied files is empty and no file list is specified then the current directory is assumed. rtags will skip 'boring' directories like .svn, CVS and _darcs.

This creates a file with the name 'tags' which contains entries for every name found in the Ruby files. Each entry looks like: 

TC_Money      ./lib/finance/money.rb  /^  class TC_Money/
TC_MoneyType  ./lib/finance/money.rb  /^  class TC_MoneyType/
(...)

Which tells vim that TC_Money lives in the file money.rb and can be found with the regular expression /^ class TC_Money/. Simple huh!

Now we have to tell vim where to find the tags. The following line can be added to the vim configuration file ~/.vimrc: 

au BufRead,BufNewFile *.rb set tags=~/izip/darcs/opensource/tags,tags

it tells vim that with every Ruby file edited it should load the tags in those two files.

Using vim with Ruby tags

Now fire up vim and point at a name. Hit Ctrl-] (Control key plus ']' key) and it will jump automatically to the correct position. To go back hit Ctrl-T. When there are multiple tags for one name you can use :tn to move to the next tag. Finally, if a partial name is needed select it with visual mode.

For more information on using tags with vim check the help inside vim with: 

:help tags

Note you can use the Ctrl-] command to jump inside the help file too - it is also based on tags(!)

Troubleshooting

Vim does not load tags

If vim does not find your tags (file) you can check its current state by 

:echo &tags

inside the vim buffer. Note: as we defined it above the tags file only gets loaded when files have the .rb extension.

rtags warnings

rtags may give warnings when it does not understand Ruby syntax - multi-line statements in particular. You can safely ignore these - it just means these tags are missed.

Finally

Contributing

When you check the [WWW] source repository on RubyForge you'll see that rtags has a simple implementation. It is quite easy to hack - uh, improve - it. If you are so inclined I'd be happy to give you access to the repository. Just make sure you add tests (unit or regression) with every improvement. See also PjotrPrins.

Mixing rtags with ctags

rtags mixes well with ctags - so you can use both. rtags ought to give more information that is specific to Ruby - so can be more Ruby-ish. For example rtags will include tags for 'new' pointing to the class 'initialize' method. Nevertheless for large source trees, like that of Ruby on Rails, it may pay to use ctags as it is very fast, but less specific.