When editing programs, there is often a need to jump to another location, for example, to see how a function is defined. To help, Vim uses a tags file that lists each word you are likely to want, and their locations (file path and line number). Each wanted word is known as a "tag", for example, each function name or global variable may be a tag.
The tags file has to be created by a utility, and has to be updated after significant editing has occurred. This tip provides an overview of creating and using tags files (for the details, see :help tagsrch.txt).
Contents[show]
|
Jumping to a tag
Help: :tag, Ctrl-], v_CTRL_], <C-LeftMouse>, g<LeftMouse>, :stag, Ctrl-W_]
How do I jump to a particular tag match, if there are multiple matching tags?
Help: tag-matchlist, :tselect, g], v_g], :stselect, Ctrl-W_g]
Returning after a tag jump
Help: :pop, Ctrl-T, <C-RightMouse>, g<RightMouse>
How do I jump again to a previously jumped tag location?
Help: tag
How do I list the contents of the tag stack?
Help: :tags, tagstack
I want to jump to a tag, if there is only one matching tag, otherwise a list of matching tags should be displayed. How do I do this?
There are several ways to make Vim to jump to a tag directly, if there is only one tag match, otherwise present a list of tag matches.
Help: :tjump, g_Ctrl-], v_g_CTRL-], :stjump, Ctrl-W_g_Ctrl-]
How do browse through a list of multiple tag matches?
If there are multiple tag matches, you can browse through all of them using several of the Vim ex commands.
Help: :tfirst, :trewind, :tlast, :tnext, :tprevious, :tNext
How do I preview a tag?
You can use the preview window to preview a tag, without leaving the original window. There are several ways to preview a tag:
Help: :preview-window, :ptag, Ctrl-W_}, :ptselect, :ptjump, Ctrl-W_g}
How do I browse through the tag list in a preview window?
If there are multiple tag matches, you can browse through all of them in the preview window using several of the Vim ex commands.
Help: :ptfirst, :ptrewind, :ptlast, :ptnext, :ptprevious, :ptNext
How do I start Vim to start editing a file at a given tag match?
While starting Vim, you can use the command line option '-t' to supply a tag name. Vim will directly jump to the supplied tag location.
Help: -t
How do I list all the tags matching a search pattern?
There are several ways to go through a list of all tags matching a pattern.
:tag /<pattern> :stag /<pattern> :ptag /<pattern> :tselect /<pattern> :tjump /<pattern> :ptselect /<pattern> :ptjump /<pattern>
Help: tag-regexp, wildmenu
What options are available to control how Vim handles the tags file?
You can use the following options to control the handling of tags file by Vim:
Help: 'tagrelative', 'taglength', 'tagbsearch', 'tagstack'
Is it possible to highlight all the tags in the current file?
Yes. Read the Vim online help on "tag-highlight".
Is there a workaround to make the Ctrl-] key not to be treated as the telnet escape character?
The default escape characters for telnet in Unix systems is Ctrl-]. While using Vim in a telnet session, if you use Ctrl-] to jump to a tag, you will get the telnet prompt. There are two ways to avoid this problem:
Help: telnet-CTRL-]
Often Exuberant Ctags (or other ctags program) is used to create the required tags file. However, many other custom scripts or tools are used for the occasions when ctags is not suitable.
Exuberant Ctags may already be present on your system (in a directory of your PATH). The current version should be used (version 5.8, dated 9 July 2009, as at July 2009; version 5.7 also works well).
Exuberant Ctags has built-in support for 34 different programming languages, and can be extended to support others. Some alternatives are listed below, but it is better to use Exuberant Ctags unless you know that your circumstances require something else. :help ctags
Following is an example of defining a language for Exuberant Ctags. IDL (Interactive Data Language) procedures and functions are supported by putting the following in your .ctags file:
--langdef=IDL --langmap=IDL:.pro --regex-IDL=/^pro[ \t]+([a-zA-Z0-9_:]+)/\1/p,procedure/i --regex-IDL=/^function[ \t]+([a-zA-Z0-9_:]+)/\1/f,function/i
See Use Taglist with LaTeX files for another example that adds support for LaTeX.
You may need the current version of Exuberant Ctags for these commands.
Generate a tags file for all C files in the current directory:
$ ctags *.c
Same, processing the current directory and all subdirectories:
$ ctags -R .
Generate a tags file for all files listed in file flist:
$ ctags -L flist
Vim needs to be told where to look for your tags files, using the 'tags' option. :help 'tags' :help tags-option
:set tags=/my/dir/tags
The 'tags' option can specify more than one tags file:
:set tags=/my/dir1/tags,/my/dir2/tags
In a large project, it is common to have a tags file in each directory (with each tags file handling the files in its directory). To assist, there is a special case: If a file specified in 'tags' starts with "./", the '.' is replaced with the path of the current file.
With this setting, the tags file is in the directory of the current file (no matter what the current directory is). You can define which tag file is searched first: In the current directory ("tags,./tags"), or in the directory of the current file ("./tags,tags"). You might also consider setting your working directory to the current file.
With the following setting, Vim will search for the file named 'tags', starting with the directory of the current file and then going to the parent directory and then recursively to the directory one level above, till it either locates the 'tags' file or reaches the root directory. :help tags-option :help file-searching
:set tags=./tags;