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.
You will need:
A ctags generated tags file (Exuberant Ctags is the choice for most cases)
Typically this is as easy as:
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
My preferred default is:
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.
tag commands later.
- Jump to the keyword under the cursor. Tag jumps are recorded on a :help tag stack.
- Jump to older tag in the stack.
- 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
- 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.
- 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
Use `` to jump back to where you were if you accidentally
pressed <esc> or <enter> instead.
- Use ctrl-c to cancel the choice if you don’t want to jump to any of them.
- gd and gD
- Jump to the local or global declaration of the keyword under the cursor, respectively.
- Jump to the file under the cursor.
- 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.
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!