Tag Like a Boss

tagging the way god intended


This short article aims to get you working with Vim tags quickly and effectively, using its built-in support. Your heavy plugins can wait outside.

Before we can jump in and learn the cool commands and power moves, we have to take charge of our environment.

Preparing for a Tagged Lifestyle

You will need:

• A ctags generated tags file (Exuberant Ctags is the choice for most cases)
  
  Typically this is as easy as:
  
  

  ctags -R

  
  in the root of your project.
  But if you need anything fancier than that, consult  man ctags  for guidance.
• A correctly set :help 'tags' option
  
  The Vim default of ./tags,tags is probably sufficient for most projects but you might want to include library tag files or a project-common tags file.
  
  
• A correctly set :help 'path' option
  
  My preferred default is:
  
  

  set path=.,**

  
  Which searches the directory of the current file and all directories beneath the current directory. See :help file-searching for more details.
  

These options can be set in your $MYVIMRC or, better, within filetype specific plugins in ~/.vim/ftplugin/<the-filetype>.vim or ~/.vim/after/ftplugin/<the-filetype>.vim

With the right setup, we can now enjoy a happy tagging lifestyle.

Living with Tag Love

There are many tag commands available in Vim, but I’m going to share with you only a select few — a mere dozen or so. These are the ones I most frequently reach for. You can learn the other tag commands later.

ctrl-]

Jump to the keyword under the cursor. Tag jumps are recorded on a :help tag stack.

ctrl-t

Jump to older tag in the stack.

:ta

Jump to newer tag in the stack. :help :tag

:0ta or :0tn

Jump to previously jumped-to tag. I use this one often after wandering away from the place I tag-jumped into the current file.

:ts /something

Show a list of tags matching the pattern something.

TIP: Use <ctrl-d> to show a list of tag candidates. This works with partial matches too.
Read more with :help c_CTRL-D

g]

Show a list of tags matching the keyword under the cursor.

:tj /something

Show a list of tags matching the pattern something. If there is only one tag in the list, don’t show the list but instead jump directly to it.

g ctrl-]

Show a list of tags matching the keyword under the cursor. If there is only one tag in the list, don’t show the list but instead jump directly to it.

[I

Ordinarily, this just shows all lines in the file matching the keyword under the cursor — a shortcut to :g/<c-r><c-w>

This map (taken from the Vim help) lets you jump to one of the matches:

:map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR>

Use ctrl-c to cancel the choice if you don’t want to jump to any of them. Use `` to jump back to where you were if you accidentally pressed <esc> or <enter> instead.

Courteous Cousins

While not strictly tagging commands, these little gems are semantically related:

gd and gD

Jump to the local or global declaration of the keyword under the cursor, respectively.

gf

Jump to the file under the cursor.

Honourable Mentions

While these are not in my daily tag toolbox, I do call upon them occasionally:

:tags

To see my current tag stack.

:ptj /something

To show the tag match in the :help preview-window.

ctrl-w ctrl-i and ctrl-w ctrl-d

To split the window, showing the associated first line or definition, respectively.

---

Tag! You’re It!

Using tags within Vim will speed up your editing by making it easy for you to jump around your pile of files. While there are heavy plugins that aim to make this prettier, the seasoned vimmer knows that the extra bling doesn’t add any real value to their edits.

Vanilla, when done right, is a classy choice.

Get yourself setup to use tags correctly within your projects and get on living the tag lifestyle!