*07* Use of tags This chapter shows how to use tags with your files for faster navigation. |07_1| What is a tag? |07_2| Using tags |07_3| Split windows |07_4| More tag files |07_5| Multiple matches |07_6| Guessing tag names =========================================================================== *07_1* What is a tag? It is a location where an identifier is defined. An example is a function definition in a C or C++ program. A list of tags is kept in a tags file. This can be used by Vim to directly jump from any place to the tag, the place where an identifier is defined. To generate the tags file for all C files in the current directory, use the following command: > bash> ctags *.c "ctags" is a separate program. Most Unix systems already have it installed. If you do not have it yet, contact your sysadmin. =========================================================================== *07_2* Using tags Now when you are in Vim and you want to go to a function definition, you can jump to it by using the following command: > :tag startlist This command will find the function "startlist" even if it is in another file. The CTRL-] command jumps to the tag of the word that is under the cursor. This makes it easy to explore a tangle of C code. Suppose, for example, that you are in the function "write_block". You can see that it calls "write_line". But what does "write_line" do? By placing the cursor on the call to "write_line" and pressing CTRL-], you jump to the definition of this function. The "write_line" function calls "write_char". You need to figure out what it does. So you position the cursor over the call to "write_char" and press CTRL-]. Now you are at the definition of "write_char". +-------------------------------------+ |void write_block(char **s; int cnt) | |{ | | int i; | | for (i = 0; i < cnt; ++i) | | write_line(s[i); | |} | | +--------|----------------------------+ | CTRL-] | | +----------------------------+ +-->|void write_line(char *s) | |{ | | while (*s != 0) | | write_char(*s++); | |} | | +---------|------------------+ | CTRL-] | | +------------------------------------+ +-->|void write_char(char c) | |{ | | putchar((int)(unsigned char)c); | |} | +------------------------------------+ The ":tags" command shows the list of tags that you traversed through: > :tags < # TO tag FROM line in file/text ~ 1 1 write_line 8 write_block.c ~ 2 1 write_char 7 write_line.c ~ > ~ Now to go back. The CTRL-T command goes to the preceding tag. In the example above you get back to the "write_line" function, in the call to 'write_char". This command takes a count argument that indicates how many tags to jump back. You have gone forward, and now back. Let's go forward again. The following command goes to the tag on top of the list: > :tag You can prefix it with a count and jump forward that many tags. For example: ":3tag". CTRL-T also can be preceded with a count. These commands thus allow you to go down a call tree with CTRL-] and back up again with CTRL-T. Use ":tags" to find out where you are. =========================================================================== *07_3* Split windows The ":tag" command replaces the file in the current window with the one containing the new function. But suppose you want to see not only the old function but also the new one? You can split the window using the ":split" command followed by the ":tag" command. Vim has a shorthand command that does both: > :stag tagname To split the current window and jump to the tag under the cursor use this command: > CTRL-W ] If a count is specified, the new window will be that many lines high. =========================================================================== *07_4* More tags files When you have files in many directories, you can create a tags file in each of them. Vim will then only be able to jump to tags within that directory. To find more tags files, set the 'tags' option to include all the relevant tags files. Example: > :set tags=./tags,./../tags,./*/tags This finds a tags file in the same directory as the current file, one directory level higher and in all subdirectories. This is quite a number of tags files, but it may still not be enough. For example, when editing a file in "~/proj/src", you will not find the tags file "~/proj/sub/tags". For this situation Vim offers to search a whole directory tree for tags files. Example: > :set tags=~/proj/**/tags One tags file ~ When Vim has to search many places for tags files, you can hear the disk rattling. It may get a bit slow. In that case it's better to spend this time while generating one big tags file. You might do this overnight. This requires the Exuberant ctags program, mentioned above. It offers an argument to search a whole directory tree: > cd ~/proj ctags -R . The nice thing about this is that Exuberant ctags recognizes various file types. Thus this doesn't work just for C and C++ programs, also for Eiffel and even Vim scripts. See the ctags documentation to tune this. Now you only need to tell Vim where your big tags file is: > :set tags=~/proj/tags =========================================================================== *07_5* Multiple matches When a function is defined multiple times (or a method in several classes), the ":tag" command will jump to the first one. If there is a match in the current file, that one is used first. You can now jump to other matches for the same tag with: > :tnext Repeat this to find further matches. If there are many, you can select which one to jump to: > :tselect tagname Vim will present you with a list of choices: # pri kind tag file ~ 1 F f mch_init os_amiga.c ~ mch_init() ~ 2 F f mch_init os_mac.c ~ mch_init() ~ 3 F f mch_init os_msdos.c ~ mch_init(void) ~ 4 F f mch_init os_riscos.c ~ mch_init() ~ Enter nr of choice ( to abort): ~ You can now enter the number (in the first column) of the match that you would like to jump to. The information in the other columns give you a good idea of where the match is defined. To move between the matching tags, these commands can be used: :tfirst go to first match :[count]tprevious go to [count] previous match :[count]tnext go to [count] next match :tlast go to last match If [count] is omitted then one is used. =========================================================================== *07_6* Guessing tag names Command line completion is a good way to avoid typing a long tag name. Just type the first bit and press : > :tag write_ You will get the first match. If it's not the one you want, press until you find the right one. Sometimes you only know part of the name of a function. Or you have many tags that start with the same string, but end differently. Then you can tell Vim to use a pattern to find the tag. Suppose you want to jump to a tag that contains "block". First type this: > :tag /block Now use command line completion: press . Vim will find all tags that contain "block" and use the first match. The "/" before a tag name tells Vim that what follows is not a literal tag name, but a pattern. You can use all the items for search patterns here. For example, suppose you want to select a tag that starts with "write_": > :tselect /^write_ The "^" specifies that the tag starts with "write". Otherwise it would also be found halfway a tag name. Similarly "$" at the end makes sure the pattern matches until the end of a tag. A tags browser ~ Since CTRL-] takes you to the definition of the identifier under the cursor, you can use a list of identifier names as a table of contents. Here is an example. First create a list of identifiers (this requires Exuberant ctags): > ctags --c-types=f -f functions *.c Now start Vim without a file, and edit this file in Vim, in a vertically split window: > vim :vsplit functions The window contains a list of all the functions. There is some more stuff, but you can ignore that. Do ":set ts=99" to clean it up a bit. In this window, define a mapping: > :nmap 0yew:tag " Move the cursor to the line that contains the function you want to go to. Now press . Vim will go to the other window and jump to the selected function. =========================================================================== vim:ft=help:tw=76:ts=8:nomodifiable