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.
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.
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 Universal or 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 Universal/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
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 (<CR> 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.
GUESSING TAG NAMES
Command line completion is a good way to avoid typing a long tag name.