*tagsrch.txt*   For Vim version 7.0aa.  Last change: 2005 Apr 01


		  VIM REFERENCE MANUAL    by Bram Moolenaar


Tags and special searches				*tags-and-searches*

See section |29.1| of the user manual for an introduction.

1. Jump to a tag		|tag-commands|
2. Tag stack			|tag-stack|
3. Tag match list		|tag-matchlist|
4. Tags details			|tag-details|
5. Tags file format		|tags-file-format|
6. Include file searches	|include-search|

==============================================================================
1. Jump to a tag					*tag-commands*

							*tag* *tags*
A tag is an identifier that appears in a "tags" file.  It is a sort of label
that can be jumped to.  For example: In C programs each function name can be
used as a tag.  The "tags" file has to be generated by a program like ctags,
before the tag commands can be used.

With the ":tag" command the cursor will be positioned on the tag.  With the
CTRL-] command, the keyword on which the cursor is standing is used as the
tag.  If the cursor is not on a keyword, the first keyword to the right of the
cursor is used.

The ":tag" command works very well for C programs.  If you see a call to a
function and wonder what that function does, position the cursor inside of the
function name and hit CTRL-].  This will bring you to the function definition.
An easy way back is with the CTRL-T command.  Also read about the tag stack
below.

						*:ta* *:tag* *E426* *E429*
:ta[g][!] {ident}	Jump to the definition of {ident}, using the
			information in the tags file(s).  Put {ident} in the
			tag stack.  See |tag-!| for [!].
			{ident} can be a regexp pattern, see |tag-regexp|.
			When there are several matching tags for {ident}, the
			first one is jumped to. |:tnext|.

g<LeftMouse>						*g<LeftMouse>*
<C-LeftMouse>					*<C-LeftMouse>* *CTRL-]*
CTRL-]			Jump to the definition of the keyword under the
			cursor.  Same as ":tag {ident}", where {ident} is the
			keyword under or after cursor.  {Vi: identifier after
			the cursor}

							*v_CTRL-]*
{Visual}CTRL-]		Same as ":tag {ident}", where {ident} is the text that
			is highlighted.  {not in Vi}

							*telnet-CTRL-]*
CTRL-] is the default telnet escape key.  When you type CTRL-] to jump to a
tag, you will get the telnet prompt instead.  Most versions of telnet allow
changing or disabling the default escape key.  See the telnet man page.  You
can 'telnet -E {Hostname}' to disable the escape character, or 'telnet -e
{EscapeCharacter} {Hostname}' to specify another escape character.  If
possible, try to use "ssh" instead of "telnet" to avoid this problem.

							*tag-priority*
When there are multiple matches for a tag, this priority is used:
1. "FSC"  A full matching static tag for the current file.
2. "F C"  A full matching global tag for the current file.
3. "F  "  A full matching global tag for another file.
4. "FS "  A full matching static tag for another file.
5. " SC"  An ignore-case matching static tag for the current file.
6. "  C"  An ignore-case matching global tag for the current file.
7. "   "  An ignore-case matching global tag for another file.
8. " S "  An ignore-case matching static tag for another file.

Note that when the current file changes, the priority list is mostly not
changed, to avoid confusion when using ":tnext".  It is changed when using
":tag {ident}".

The ignore-case matches are not found for a ":tag" command when the
'ignorecase' option is off.  They are found when a pattern is used (starting
with a "/") and for ":tselect", also when 'ignorecase' is off.  Note that
using ignore-case tag searching disables binary searching in the tags file,
which causes a slowdown.  This can be avoided by fold-case sorting the tag
file.  See the 'tagbsearch' option for an explanation.

==============================================================================
2. Tag stack				*tag-stack* *tagstack* *E425*

On the tag stack is remembered which tags you jumped to, and from where.
Tags are only pushed onto the stack when the 'tagstack' option is set.

g<RightMouse>						*g<RightMouse>*
<C-RightMouse>					*<C-RightMouse>* *CTRL-T*
CTRL-T			Jump to [count] older entry in the tag stack
			(default 1).  {not in Vi}

						*:po* *:pop* *E555* *E556*
:[count]po[p][!]	Jump to [count] older entry in tag stack (default 1).
			See |tag-!| for [!].  {not in Vi}

:[count]ta[g][!]	Jump to [count] newer entry in tag stack (default 1).
			See |tag-!| for [!].  {not in Vi}

							*:tags*
:tags			Show the contents of the tag stack.  The active
			entry is marked with a '>'.  {not in Vi}

The output of ":tags" looks like this:

   # TO tag      FROM line in file/line
   1  1 main		 1  harddisk2:text/vim/test
 > 2  2 FuncA		58  i = FuncA(10);
   3  1 FuncC	       357  harddisk2:text/vim/src/amiga.c

This list shows the tags that you jumped to and the cursor position before
that jump.  The older tags are at the top, the newer at the bottom.

The '>' points to the active entry.  This is the tag that will be used by the
next ":tag" command.  The CTRL-T and ":pop" command will use the position
above the active entry.

Below the "TO" is the number of the current match in the match list.  Note
that this doesn't change when using ":pop" or ":tag".

The line number and file name are remembered to be able to get back to where
you were before the tag command.  The line number will be correct, also when
deleting/inserting lines, unless this was done by another program (e.g.
another instance of Vim).

For the current file, the "file/line" column shows the text at the position.
An indent is removed and a long line is truncated to fit in the window.

You can jump to previously used tags with several commands.  Some examples:

	":pop" or CTRL-T	to position before previous tag
	{count}CTRL-T		to position before {count} older tag
	":tag"			to newer tag
	":0tag"			to last used tag

The most obvious way to use this is while browsing through the call graph of
a program.  Consider the following call graph:

	main  --->  FuncA  --->  FuncC
	      --->  FuncB

(Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
You can get from main to FuncA by using CTRL-] on the call to FuncA.  Then
you can CTRL-] to get to FuncC.  If you now want to go back to main you can
use CTRL-T twice.  Then you can CTRL-] to FuncB.

If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the
current position in the stack.  If the stack was full (it can hold up to 20
entries), the oldest entry is deleted and the older entries shift one
position up (their index number is decremented by one).  If the last used
entry was not at the bottom, the entries below the last used one are
deleted.  This means that an old branch in the call graph is lost.  After the
commands explained above the tag stack will look like this:

   # TO tag	FROM line in file
   1 main	       1  harddisk2:text/vim/test
   2 FuncB	      59  harddisk2:text/vim/src/main.c

							*E73*
When you try to use the tag stack while it doesn't contain anything you will
get an error message.

==============================================================================
3. Tag match list				*tag-matchlist* *E427* *E428*

When there are several matching tags, these commands can be used to jump
between them.  Note that these command don't change the tag stack, they keep
the same entry.

							*:ts* *:tselect*
:ts[elect][!] [ident]	List the tags that match [ident], using the
			information in the tags file(s).
			When [ident] is not given, the last tag name from the
			tag stack is used.
			With a '>' in the first column is indicated which is
			the current position in the list (if there is one).
			[ident] can be a regexp pattern, see |tag-regexp|.
			See |tag-priority| for the priorities used in the
			listing.  {not in Vi}
			Example output:

>
	 nr pri kind tag		file
	  1 F	f    mch_delay		os_amiga.c
			mch_delay(msec, ignoreinput)
	> 2 F	f    mch_delay		os_msdos.c
			mch_delay(msec, ignoreinput)
	  3 F	f    mch_delay		os_unix.c
			mch_delay(msec, ignoreinput)
	Enter nr of choice (<CR> to abort):
<
			See |tag-priority| for the "pri" column.  Note that
			this depends on the current file, thus using
			":tselect xxx" can produce different results.
			The "kind" column gives the kind of tag, if this was
			included in the tags file.
			The "info" column shows information that could be
			found in the tags file.  It depends on the program
			that produced the tags file.
			When the list is long, you may get the |more-prompt|.
			If you already see the tag you want to use, you can
			type 'q' and enter the number.

							*:sts* *:stselect*
:sts[elect][!] [ident]	Does ":tselect[!] [ident]" and splits the window for
			the selected tag.  {not in Vi}

							*g]*
g]			Like CTRL-], but use ":tselect" instead of ":tag".
			{not in Vi}

							*v_g]*
{Visual}g]		Same as "g]", but use the highlighted text as the
			identifier.  {not in Vi}

							*:tj* *:tjump*
:tj[ump][!] [ident]	Like ":tselect", but jump to the tag directly when
			there is only one match.  {not in Vi}

							*:stj* *:stjump*
:stj[ump][!] [ident]	Does ":tjump[!] [ident]" and splits the window for the
			selected tag.  {not in Vi}

							*g_CTRL-]*
g CTRL-]		Like CTRL-], but use ":tjump" instead of ":tag".
			{not in Vi}

							*v_g_CTRL-]*
{Visual}g CTRL-]	Same as "g CTRL-]", but use the highlighted text as
			the identifier.  {not in Vi}

							*:tn* *:tnext*
:[count]tn[ext][!]	Jump to [count] next matching tag (default 1).  See
			|tag-!| for [!].  {not in Vi}

							*:tp* *:tprevious*
:[count]tp[revious][!]	Jump to [count] previous matching tag (default 1).
			See |tag-!| for [!].  {not in Vi}

							*:tN* *:tNext*
:[count]tN[ext][!]	Same as ":tprevious".  {not in Vi}

							*:tr* *:trewind*
:[count]tr[ewind][!]	Jump to first matching tag.  If [count] is given, jump
			to [count]th matching tag.  See |tag-!| for [!].  {not
			in Vi}

							*:tf* *:tfirst*
:[count]tf[irst][!]	Same as ":trewind".  {not in Vi}

							*:tl* *:tlast*
:tl[ast][!]		Jump to last matching tag.  See |tag-!| for [!].  {not
			in Vi}


When there is no other message, Vim shows which matching tag has                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            