created August 3, 2001 · complexity basic · author Yegappan Lakshmanan · version 5.7
This Q&A gives an introduction to the various facilities available in Vim for using a tags file to browse through program source files. You can read the Vim online help, which explains in detail the tags support, using the ':help tagsearch.txt' command. You can also use the help keywords mentioned in this document to read more about a particular command or option. To read more about a particular command or option use, :help <helpkeyword> in Vim.
How do I create a tags file?
You can create a tags file either using the ctags utility or using a custom script or utility.
Help keyword(s): tag
Where can I download the tools to generate the tags file?
There are several utilities available to generate the tags file. Depending on the programming language, you can use any one of them.
- Exuberant ctags generates tags for the following programming language files:
- Assembler, AWK, ASP, BETA, Bourne/Korn/Zsh Shell, C, C++, COBOL, Eiffel, Fortran, Java, Lisp, Make, Pascal, Perl, PHP, Python, REXX, Ruby, S-Lang, Scheme, Tcl, and Vim.
- You can download exuberant ctags from
- On Unix, you can use the /usr/bin/ctags utility. This utility is present in most of the Unix installations.
- You can use jtags for generating tags file for java programs. You can download jtags from: http://www.fleiner.com/jtags/
- You can use ptags for generating tags file for perl programs. You can download ptags from: http://www.eleves.ens.fr:8080/home/nthiery/Tags/
- You can download scripts from the following links for generating tags file for verilog files:
- You can download Hdrtag from the following link: http://mysite.verizon.net/astronaut/vim/index.html. This utility generates tags file for the following programming languages: assembly, c/c++, header files, lex, yacc,LaTeX, vim, and Maple V.
- pltags.pl - Create tags file for perl code
- tcltags - Create tags file for TCL code
- shtags.pl - Create tags file for shell script
Help keyword(s): ctags
How do I generate a tags file using ctags?
You can generate a tags file for all the C files in the current directory using the following command:
$ ctags *.c
You can generate tags file for all the files in the current directory and all the sub-directories using (this applies only to exuberant ctags):
$ ctags -R .
You can generate tags file for all the files listed in a text file named flist using (this applies only to exuberant ctags)
$ ctags -L flist
How do I configure Vim to locate a tags file?
You can set the 'tags' option in Vim to specify a particular tags file.
set tags=/my/dir/tags
Help keyword(s): 'tags', tags-option
How do I configure Vim to use multiple tags files?
The 'tags' option can specify more than one tags file. The tag filenames are separated using either comma or spaces.
set tags=/my/dir1/tags, /my/dir2/tags
How do I configure Vim to locate a tags file in a directory tree?
You can set the 'tags' option to make Vim search for the tags file in a directory tree. For example, if the 'tags' option is set like this:
set tags=./tags;
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. Note that the above will work only in Vim 6.0 and above.
Help keyword(s): tags-option, file-searching
How do I jump to a tag?
There are several ways to jump to a tag location.
- You can use the 'tag' ex command. For example, the command ':tag <tagname>' will jump to the tag named <tagname>.
- You can position the cursor over a tag name and then press Ctrl-].
- You can visually select a text and then press Ctrl-] to jump to the tag matching the selected text.
- You can click on the tag name using the left mouse button, while pressing the <Ctrl> key.
- You can press the g key and then click on the tag name using the left mouse button.
- You can use the 'stag' ex command, to open the tag in a new window. For example, the command ':stag func1' will open the func1 definition in a new window.
- You can position the cursor over a tag name and then press Ctrl-W ]. This will open the tag location in a new window.
Help keyword(s): :tag, Ctrl-], v_CTRL_], <C-LeftMouse>, g<LeftMouse>, :stag, Ctrl-W_]
How do I come back from a tag jump?
There are several ways to come back to the old location from a tag jump.
- You can use the 'pop' ex command.
- You can press Ctrl-t.
- You can click the right mouse button, while pressing the <Ctrl> key.
- You can press the g key and then click the right mouse button.
Help keyword(s): :pop, Ctrl-T, <C-RightMouse>, g<RightMouse>
How do I jump again to a previously jumped tag location?
You can use the 'tag' ex command to jump to a previously jumped tag location, which is stored in the tag stack. Help keyword(s): tag
How do I list the contents of the tag stack?
Vim remembers the location from which you jumped to a tag in the tag stack. You can list the current tag stack using the 'tags' ex command. Help keyword(s): :tags, tagstack
How do I jump to a particular tag match, if there are multiple matching tags?
In some situations, there can be more than one match for a tag. For example, a C function or definition may be present in more than one file in a source tree. There are several ways to jump to a specific tag from a list of matching tags.
- You can use the 'tselect' ex command to list all the tag matches. For example, the command ':tselect func1' will list all the locations where func1 is defined. You can then enter the number of a tag match to jump to that location.
- You can position the cursor over the tag name and press g] to get a list of matching tags.
- You can visually select a text and press g] to get a list of matching tags.
- You can use the 'stselect' ex command. This will open the selected tag from the tag list in a new window.
- You can position the cursor over the tag name and press Ctrl-W g] to do a :stselect.
Help keyword(s): tag-matchlist, :tselect, g], v_g], :stselect, Ctrl-W_g]
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.
- You can use the 'tjump' ex command. For example, the command ':tjump func1' will jump to the definition func1, if it is defined only once. If func1 is defined multiple times, a list of matching tags will be presented.
- You can position the cursor over the tag and press g Ctrl-].
- You can visually select a text and press g Ctrl-] to jump or list the matching tags.
- You can use the 'stjump' ex command. This will open the matching or selected tag from the tag list in a new window.
- You can press Ctrl-W g Ctrl-] to do a :stjump.
Help keyword(s): :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.
- To go to the first tag in the list, use the 'tfirst' or 'trewind' ex command.
- To go to the last tag in the list, use the 'tlast' ex command.
- To go to the next matching tag in the list, use the 'tnext' ex command.
- To go to the previous matching tag in the list, use the 'tprevious' or 'tNext' ex command.
Help keyword(s): :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:
- You can use the 'ptag' ex command to open a tag in the preview window.
- You can position the cursor on a tag name and press Ctrl-W } to open the tag in the preview window.
- You can use the 'ptselect' ex command to do the equivalent of the 'tselect' ex command in the preview window.
- You can use the 'ptjump' ex command to do the equivalent of the 'tjump' ex command in the preview window.
- You can position the cursor on the tag and press Ctrl-W g} to do a :ptjump on the tag.
Help keyword(s): :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.
- To go to the first tag in the list, use the 'ptfirst' or 'ptrewind' ex command.
- To go to the last tag in the list, use the 'ptlast' ex command.
- To go to the next matching tag in the list, use the 'ptnext' ex command.
- To go to the previous matching tag in the list, use the 'ptprevious' or 'ptNext' ex command.
Help keyword(s): :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 keyword(s): -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.
- You can list all the tags matching a particular regular expression pattern by prepending the tag name with the '/' search character. For example,
:tag /<pattern> :stag /<pattern> :ptag /<pattern> :tselect /<pattern> :tjump /<pattern> :ptselect /<pattern> :ptjump /<pattern>
- If you have the 'wildmenu' option set, then you can press the <Tab> key to display a list of all the matching tags in the status bar. You can use the arrow keys to move between the tags and then use the <Enter> key to select a tag.
- If you don't have the 'wildmenu' option set, you can still use the <Tab> key to browse through the list of matching tags.
Help keyword(s): 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:
- 'tagrelative' - Controls how the file names in the tags file are treated. When on, the filenames are relative to the directory where the tags file is present.
- 'taglength' - Controls the number of significant characters used for recognizing a tag.
- 'tagbsearch' - Controls the method used to search the tags file for a tag. If this option is on, binary search is used to search the tags file. Otherwise, linear search is used.
- 'tagstack' - Controls how the tag stack is used.
Help keyword(s): '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 it possible to create a menu with all the tags in the current file?
Yes. You can use the taglist plugin to display a list of tags defined in the current file in a menu. You can download this plugin from script#273.
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:
- Map the telnet escape character to some other character using the "-e <escape character>" telnet command line option
- Disable the telnet escape character using the "-E" telnet command line option.
Help keyword(s): telnet-CTRL-]
Ctags for unsupported languages
Exuberant Ctags may not support a language such as IDL (Interactive Data Language). In some cases, you will be able to find a script to create the tags file. For IDL, a Perl script is available (so ctags is not required).
However, you can also configure ctags. IDL 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.
Comments
Heres an excellent tutorial on using cscope with Vim ; right from installing to becoming an expert. http://cscope.sourceforge.net/cscope_vim_tutorial.html
Um, for some reason - I couldn't get recursive lookup of tags to work with just the
set tags=tags;/
line - changing it to
set tags=./tags;/
works just fine - the only time I've EVER come across the need to use the ./ thing...
- According to the help files, "When a tag file name starts with "./", the '.' is replaced with the path of the current file. This makes it possible to use a tags file in the directory where the current file is (no matter what the current directory is). The idea of using "./" is that 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")." Thus, it would seem that your tags file is in the current directory of the file being edited (of course!) rather than in Vim's current working directory, which is apparently different. This is one of those times that setting your working directory to the current file might be a good idea!
TagMenu has been moved to http://members.rogers.com/jayglanville/tagsmenu/
In Brazilian keyboards, CTRL-] is CTRL-Ç (CTRL + c-cedilla). I don't know why, since 'Ç' is located just to the right of 'L' (it's ';' in US keyboards), but it works.
When -R option is not available (on Solaris), use find to generate the list of files and give them as input to ctags using -L option.
To navigate with Alt+Left and Alt+Right with tags in Vim help or in source code I added the following mappings to my .vimrc:
map <M-Left> <C-T> map <M-Right> <C-]>
As for C++, try to use ctags with "--extra=+q" to qualify member function/variable with it's class type.
Vim is nice to use with cscope and ctags, for this purpose
1. add to file .vimrc follow strings
:map [I :cs find c <C-r><C-w><CR> :set csto=1
2. before launch vim, generate:
ctags -R cscope -R -b
A modified version of exuberant ctags with support for LaTeX and BibTeX tags can be found at http://www.unb.ca/fredericton/science/chem/ajit/vim.htm
A utility similar to taglist, but for hdrtag, is available at http://mysite.verizon.net/astronaut/vim/index.html#HdrtagList