vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

tagsrch.txt (41445B)


      1 *tagsrch.txt*	For Vim version 9.2.  Last change: 2026 Jul 24
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 Tags and special searches				*tags-and-searches*
      8 
      9 See section |29.1| of the user manual for an introduction.
     10 
     11 1. Jump to a tag		|tag-commands|
     12 2. Tag stack			|tag-stack|
     13 3. Tag match list		|tag-matchlist|
     14 4. Tags details			|tag-details|
     15 5. Tags file format		|tags-file-format|
     16 6. Include file searches	|include-search|
     17 7. Using 'tagfunc'		|tag-function|
     18 
     19 ==============================================================================
     20 1. Jump to a tag					*tag-commands*
     21 
     22 							*tag* *tags*
     23 A tag is an identifier that appears in a "tags" file.  It is a sort of label
     24 that can be jumped to.  For example: In C programs each function name can be
     25 used as a tag.  The "tags" file has to be generated by a program like ctags,
     26 before the tag commands can be used.
     27 
     28 With the ":tag" command the cursor will be positioned on the tag.  With the
     29 CTRL-] command, the keyword on which the cursor is standing is used as the
     30 tag.  If the cursor is not on a keyword, the first keyword to the right of the
     31 cursor is used.
     32 
     33 The ":tag" command works very well for C programs.  If you see a call to a
     34 function and wonder what that function does, position the cursor inside of the
     35 function name and hit CTRL-].  This will bring you to the function definition.
     36 An easy way back is with the CTRL-T command.  Also read about the tag stack
     37 below.
     38 
     39 						*:ta* *:tag* *E426* *E429*
     40 :[count]ta[g][!] {name}
     41 			Jump to the definition of {name}, using the
     42 			information in the tags file(s).  Put {name} in the
     43 			tag stack.  See |tag-!| for [!].
     44 			{name} can be a regexp pattern, see |tag-regexp|.
     45 			When there are several matching tags for {name}, jump
     46 			to the [count] one.  When [count] is omitted the
     47 			first one is jumped to.  See |tag-matchlist| for
     48 			jumping to other matching tags.
     49 
     50 g<LeftMouse>						*g<LeftMouse>*
     51 <C-LeftMouse>					*<C-LeftMouse>* *CTRL-]*
     52 CTRL-]			Jump to the definition of the keyword under the
     53 			cursor.  Same as ":tag {name}", where {name} is the
     54 			keyword under or after cursor.
     55 			When there are several matching tags for {name}, jump
     56 			to the [count] one.  When no [count] is given the
     57 			first one is jumped to.  See |tag-matchlist| for
     58 			jumping to other matching tags.
     59 
     60 							*v_CTRL-]*
     61 {Visual}CTRL-]		Same as ":tag {name}", where {name} is the text that
     62 			is highlighted.
     63 
     64 							*telnet-CTRL-]*
     65 CTRL-] is the default telnet escape key.  When you type CTRL-] to jump to a
     66 tag, you will get the telnet prompt instead.  Most versions of telnet allow
     67 changing or disabling the default escape key.  See the telnet man page.  You
     68 can 'telnet -E {Hostname}' to disable the escape character, or 'telnet -e
     69 {EscapeCharacter} {Hostname}' to specify another escape character.  If
     70 possible, try to use "ssh" instead of "telnet" to avoid this problem.
     71 
     72 							*tag-priority*
     73 When there are multiple matches for a tag, this priority is used:
     74 1. "FSC"  A full matching static tag for the current file.
     75 2. "F C"  A full matching global tag for the current file.
     76 3. "F  "  A full matching global tag for another file.
     77 4. "FS "  A full matching static tag for another file.
     78 5. " SC"  An ignore-case matching static tag for the current file.
     79 6. "  C"  An ignore-case matching global tag for the current file.
     80 7. "   "  An ignore-case matching global tag for another file.
     81 8. " S "  An ignore-case matching static tag for another file.
     82 
     83 Note that when the current file changes, the priority list is mostly not
     84 changed, to avoid confusion when using ":tnext".  It is changed when using
     85 ":tag {name}".
     86 
     87 The ignore-case matches are not found for a ":tag" command when:
     88 - 'tagcase' is "followic" and the 'ignorecase' option is off
     89 - 'tagcase' is "followscs" and the 'ignorecase' option is off and the
     90   'smartcase' option is off or the pattern contains an upper case character.
     91 - 'tagcase' is "match"
     92 - 'tagcase' is "smart" and the pattern contains an upper case character.
     93 
     94 The ignore-case matches are found when:
     95 - a pattern is used (starting with a "/")
     96 - for ":tselect"
     97 - when 'tagcase' is "followic" and 'ignorecase' is on
     98 - when 'tagcase' is "followscs" and 'ignorecase' is on or the 'smartcase'
     99   option is on and the pattern does not contain an upper case character
    100 - when 'tagcase' is "ignore"
    101 - when 'tagcase' is "smart" and the pattern does not contain an upper case
    102   character
    103 
    104 Note that using ignore-case tag searching disables binary searching in the
    105 tags file, which causes a slowdown.  This can be avoided by fold-case sorting
    106 the tag file.  See the 'tagbsearch' option for an explanation.
    107 
    108 ==============================================================================
    109 2. Tag stack				*tag-stack* *tagstack* *E425*
    110 
    111 On the tag stack is remembered which tags you jumped to, and from where.
    112 Tags are only pushed onto the stack when the 'tagstack' option is set.
    113 
    114 g<RightMouse>						*g<RightMouse>*
    115 <C-RightMouse>					*<C-RightMouse>* *CTRL-T*
    116 CTRL-T			Jump to [count] older entry in the tag stack
    117 			(default 1).
    118 
    119 						*:po* *:pop* *E555* *E556*
    120 :[count]po[p][!]	Jump to [count] older entry in tag stack (default 1).
    121 			See |tag-!| for [!].
    122 
    123 :[count]ta[g][!]	Jump to [count] newer entry in tag stack (default 1).
    124 			See |tag-!| for [!].
    125 
    126 							*:tags*
    127 :tags			Show the contents of the tag stack.  The active
    128 			entry is marked with a '>'.
    129 
    130 The output of ":tags" looks like this:
    131 
    132    # TO tag      FROM line  in file/text
    133    1  1 main		 1  harddisk2:text/vim/test
    134  > 2  2 FuncA		58  i = FuncA(10);
    135    3  1 FuncC	       357  harddisk2:text/vim/src/amiga.c
    136 
    137 This list shows the tags that you jumped to and the cursor position before
    138 that jump.  The older tags are at the top, the newer at the bottom.
    139 
    140 The '>' points to the active entry.  This is the tag that will be used by the
    141 next ":tag" command.  The CTRL-T and ":pop" command will use the position
    142 above the active entry.
    143 
    144 Below the "TO" is the number of the current match in the match list.  Note
    145 that this doesn't change when using ":pop" or ":tag".
    146 
    147 The line number and file name are remembered to be able to get back to where
    148 you were before the tag command.  The line number will be correct, also when
    149 deleting/inserting lines, unless this was done by another program (e.g.
    150 another instance of Vim).
    151 
    152 For the current file, the "file/text" column shows the text at the position.
    153 An indent is removed and a long line is truncated to fit in the window.
    154 
    155 You can jump to previously used tags with several commands.  Some examples:
    156 
    157 	":pop" or CTRL-T	to position before previous tag
    158 	{count}CTRL-T		to position before {count} older tag
    159 	":tag"			to newer tag
    160 	":0tag"			to last used tag
    161 
    162 The most obvious way to use this is while browsing through the call graph of
    163 a program.  Consider the following call graph:
    164 
    165 	main  --->  FuncA  --->  FuncC
    166 	      --->  FuncB
    167 
    168 (Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
    169 You can get from main to FuncA by using CTRL-] on the call to FuncA.  Then
    170 you can CTRL-] to get to FuncC.  If you now want to go back to main you can
    171 use CTRL-T twice.  Then you can CTRL-] to FuncB.
    172 
    173 If you issue a ":ta {name}" or CTRL-] command, this tag is inserted at the
    174 current position in the stack.  If the stack was full (it can hold up to 20
    175 entries), the oldest entry is deleted and the older entries shift one
    176 position up (their index number is decremented by one).  If the last used
    177 entry was not at the bottom, the entries below the last used one are
    178 deleted.  This means that an old branch in the call graph is lost.  After the
    179 commands explained above the tag stack will look like this:
    180 
    181    # TO tag	FROM line  in file/text
    182    1  1 main		1  harddisk2:text/vim/test
    183    2  1 FuncB	       59  harddisk2:text/vim/src/main.c
    184 
    185 The |gettagstack()| function returns the tag stack of a specified window.  The
    186 |settagstack()| function modifies the tag stack of a window.
    187 
    188 							*tagstack-examples*
    189 Write to the tag stack just like `:tag` but with a user-defined
    190 jumper#jump_to_tag function: >
    191 	" Store where we're jumping from before we jump.
    192 	let tag = expand('<cword>')
    193 	let pos = [bufnr()] + getcurpos()[1:]
    194 	let item = {'bufnr': pos[0], 'from': pos, 'tagname': tag}
    195 	if jumper#jump_to_tag(tag)
    196 		" Jump was successful, write previous location to tag stack.
    197 		let winid = win_getid()
    198 		let stack = gettagstack(winid)
    199 		let stack['items'] = [item]
    200 		call settagstack(winid, stack, 't')
    201 	endif
    202 <
    203 Set current index of the tag stack to 4: >
    204 	call settagstack(1005, {'curidx' : 4})
    205 <
    206 Push a new item onto the tag stack: >
    207 	let pos = [bufnr('myfile.txt'), 10, 1, 0]
    208 	let newtag = [{'tagname' : 'mytag', 'from' : pos}]
    209 	call settagstack(2, {'items' : newtag}, 'a')
    210 <
    211 							*E73*
    212 When you try to use the tag stack while it doesn't contain anything you will
    213 get an error message.
    214 
    215 ==============================================================================
    216 3. Tag match list				*tag-matchlist* *E427* *E428*
    217 
    218 When there are several matching tags, these commands can be used to jump
    219 between them.  Note that these commands don't change the tag stack, they keep
    220 the same entry.
    221 
    222 							*:ts* *:tselect*
    223 :ts[elect][!] [name]	List the tags that match [name], using the
    224 			information in the tags file(s).
    225 			When [name] is not given, the last tag name from the
    226 			tag stack is used.
    227 			See |tag-!| for [!].
    228 			With a '>' in the first column is indicated which is
    229 			the current position in the list (if there is one).
    230 			[name] can be a regexp pattern, see |tag-regexp|.
    231 			See |tag-priority| for the priorities used in the
    232 			listing.
    233 			Example output:
    234 
    235 >
    236 	  # pri kind tag		file
    237 	  1 F	f    mch_delay		os_amiga.c
    238 			mch_delay(msec, ignoreinput)
    239 	> 2 F	f    mch_delay		os_msdos.c
    240 			mch_delay(msec, ignoreinput)
    241 	  3 F	f    mch_delay		os_unix.c
    242 			mch_delay(msec, ignoreinput)
    243 	Type number and <Enter> (empty cancels):
    244 <
    245 			See |tag-priority| for the "pri" column.  Note that
    246 			this depends on the current file, thus using
    247 			":tselect xxx" can produce different results.
    248 			The "kind" column gives the kind of tag, if this was
    249 			included in the tags file.
    250 			The "info" column shows information that could be
    251 			found in the tags file.  It depends on the program
    252 			that produced the tags file.
    253 			When the list is long, you may get the |more-prompt|.
    254 			If you already see the tag you want to use, you can
    255 			type 'q' and enter the number.
    256 
    257 							*:sts* *:stselect*
    258 :sts[elect][!] [name]	Does ":tselect[!] [name]" and splits the window for
    259 			the selected tag.
    260 
    261 							*g]*
    262 g]			Like CTRL-], but use ":tselect" instead of ":tag".
    263 
    264 							*v_g]*
    265 {Visual}g]		Same as "g]", but use the highlighted text as the
    266 			identifier.
    267 
    268 							*:tj* *:tjump*
    269 :tj[ump][!] [name]	Like ":tselect", but jump to the tag directly when
    270 			there is only one match.
    271 
    272 							*:stj* *:stjump*
    273 :stj[ump][!] [name]	Does ":tjump[!] [name]" and splits the window for the
    274 			selected tag.
    275 
    276 							*g_CTRL-]*
    277 g CTRL-]		Like CTRL-], but use ":tjump" instead of ":tag".
    278 
    279 							*v_g_CTRL-]*
    280 {Visual}g CTRL-]	Same as "g CTRL-]", but use the highlighted text as
    281 			the identifier.
    282 
    283 							*:tn* *:tnext*
    284 :[count]tn[ext][!]	Jump to [count] next matching tag (default 1).  See
    285 			|tag-!| for [!].
    286 
    287 							*:tp* *:tprevious*
    288 :[count]tp[revious][!]	Jump to [count] previous matching tag (default 1).
    289 			See |tag-!| for [!].
    290 
    291 							*:tN* *:tNext*
    292 :[count]tN[ext][!]	Same as ":tprevious".
    293 
    294 							*:tr* *:trewind*
    295 :[count]tr[ewind][!]	Jump to first matching tag.  If [count] is given, jump
    296 			to [count]th matching tag.  See |tag-!| for [!].
    297 
    298 							*:tf* *:tfirst*
    299 :[count]tf[irst][!]	Same as ":trewind".
    300 
    301 							*:tl* *:tlast*
    302 :tl[ast][!]		Jump to last matching tag.  See |tag-!| for [!].
    303 
    304 							*:lt* *:ltag*
    305 :lt[ag][!] [name]	Jump to tag [name] and add the matching tags to a new
    306 			location list for the current window.  [name] can be
    307 			a regexp pattern, see |tag-regexp|.  When [name] is
    308 			not given, the last tag name from the tag stack is
    309 			used.  The search pattern to locate the tag line is
    310 			prefixed with "\V" to escape all the special
    311 			characters (very nomagic).  The location list showing
    312 			the matching tags is independent of the tag stack.
    313 			See |tag-!| for [!].
    314 
    315 When there is no other message, Vim shows which matching tag has been jumped
    316 to, and the number of matching tags: >
    317 	tag 1 of 3 or more
    318 The " or more" is used to indicate that Vim didn't try all the tags files yet.
    319 When using ":tnext" a few times, or with ":tlast", more matches may be found.
    320 
    321 When you didn't see this message because of some other message, or you just
    322 want to know where you are, this command will show it again (and jump to the
    323 same tag as last time): >
    324 	:0tn
    325 <
    326 							*tag-skip-file*
    327 When a matching tag is found for which the file doesn't exist, this match is
    328 skipped and the next matching tag is used.  Vim reports this, to notify you of
    329 missing files.  When the end of the list of matches has been reached, an error
    330 message is given.
    331 
    332 							*tag-preview*
    333 The tag match list can also be used in the preview window.  The commands are
    334 the same as above, with a "p" prepended.
    335 {not available when compiled without the |+quickfix| feature}
    336 
    337 							*:pts* *:ptselect*
    338 :pts[elect][!] [name]	Does ":tselect[!] [name]" and shows the new tag in a
    339 			"Preview" window.  See |:ptag| for more info.
    340 
    341 							*:ptj* *:ptjump*
    342 :ptj[ump][!] [name]	Does ":tjump[!] [name]" and shows the new tag in a
    343 			"Preview" window.  See |:ptag| for more info.
    344 
    345 							*:ptn* *:ptnext*
    346 :[count]ptn[ext][!]	":tnext" in the preview window.  See |:ptag|.
    347 
    348 							*:ptp* *:ptprevious*
    349 :[count]ptp[revious][!]	":tprevious" in the preview window.  See |:ptag|.
    350 
    351 							*:ptN* *:ptNext*
    352 :[count]ptN[ext][!]	Same as ":ptprevious".
    353 
    354 							*:ptr* *:ptrewind*
    355 :[count]ptr[ewind][!]	":trewind" in the preview window.  See |:ptag|.
    356 
    357 							*:ptf* *:ptfirst*
    358 :[count]ptf[irst][!]	Same as ":ptrewind".
    359 
    360 							*:ptl* *:ptlast*
    361 :ptl[ast][!]		":tlast" in the preview window.  See |:ptag|.
    362 
    363 ==============================================================================
    364 4. Tags details						*tag-details*
    365 
    366 							*static-tag*
    367 A static tag is a tag that is defined for a specific file.  In a C program
    368 this could be a static function.
    369 
    370 In Vi jumping to a tag sets the current search pattern.  This means that the
    371 "n" command after jumping to a tag does not search for the same pattern that
    372 it did before jumping to the tag.  Vim does not do this as we consider it to
    373 be a bug.  If you really want the old Vi behavior, set the 't' flag in
    374 'cpoptions'.
    375 
    376 							*tag-binary-search*
    377 Vim uses binary searching in the tags file to find the desired tag quickly
    378 (when enabled at compile time |+tag_binary|).  But this only works if the
    379 tags file was sorted on ASCII byte value.  Therefore, if no match was found,
    380 another try is done with a linear search.  If you only want the linear search,
    381 reset the 'tagbsearch' option.  Or better: Sort the tags file!
    382 
    383 Note that the binary searching is disabled when not looking for a tag with a
    384 specific name.  This happens when ignoring case and when a regular expression
    385 is used that doesn't start with a fixed string.  Tag searching can be a lot
    386 slower then.  The former can be avoided by case-fold sorting the tags file.
    387 See 'tagbsearch' for details.
    388 
    389 							*tag-regexp*
    390 The ":tag" and ":tselect" commands accept a regular expression argument.  See
    391 |pattern| for the special characters that can be used.
    392 When the argument starts with '/', it is used as a pattern.  If the argument
    393 does not start with '/', it is taken literally, as a full tag name.
    394 Examples: >
    395     :tag main
    396 <	jumps to the tag "main" that has the highest priority. >
    397     :tag /^get
    398 <	jumps to the tag that starts with "get" and has the highest priority. >
    399     :tag /norm
    400 <	lists all the tags that contain "norm", including "id_norm".
    401 When the argument both exists literally, and match when used as a regexp, a
    402 literal match has a higher priority.  For example, ":tag /open" matches "open"
    403 before "open_file" and "file_open".
    404 When using a pattern case is ignored.  If you want to match case use "\C" in
    405 the pattern.
    406 
    407 							*tag-!*
    408 If the tag is in the current file this will always work.  Otherwise the
    409 performed actions depend on whether the current file was changed, whether a !
    410 is added to the command and on the 'autowrite' and 'winfixbuf' options:
    411 
    412   tag in       file	    winfixbuf	autowrite		~
    413 current file  changed	!   option	option	      action	~
    414  -----------------------------------------------------------------------------
    415     yes		x	x      off	  x	    goto tag
    416     no		no	x      off	  x	    read other file, goto tag
    417     no		yes	yes    off	  x	    abandon current file,
    418 						    read other file, goto tag
    419     no		yes	no     off	  on	    write current file,
    420 						    read other file, goto tag
    421     no		yes	no     off	  off	    fail
    422     yes		x	yes    x	  x	    goto tag
    423     no		no	no     on	  x	    fail
    424     no		yes	no     on	  x	    fail
    425     no		yes	no     on	  on	    fail
    426     no		yes	no     on	  off	    fail
    427  -----------------------------------------------------------------------------
    428 
    429 - If the tag is in the current file, the command will always work.
    430 - If the tag is in another file and the current file was not changed, the
    431   other file will be made the current file and read into the buffer.
    432 - If the tag is in another file, the current file was changed and a ! is
    433   added to the command, the changes to the current file are lost, the other
    434   file will be made the current file and read into the buffer.
    435 - If the tag is in another file, the current file was changed and the
    436   'autowrite' option is on, the current file will be written, the other
    437   file will be made the current file and read into the buffer.
    438 - If the tag is in another file, the current file was changed and the
    439   'autowrite' option is off, the command will fail.  If you want to save
    440   the changes, use the ":w" command and then use ":tag" without an argument.
    441   This works because the tag is put on the stack anyway.  If you want to lose
    442   the changes you can use the ":tag!" command.
    443 - If the tag is in another file and the window includes 'winfixbuf', the
    444   command will fail.  If the tag is in the same file then it may succeed.
    445 
    446 							*tag-security*
    447 Note that Vim forbids some commands, for security reasons.  This works like
    448 using the 'secure' option for exrc/vimrc files in the current directory.  See
    449 |trojan-horse| and |sandbox|.
    450 When the {tagaddress} changes a buffer, you will get a warning message:
    451 	"WARNING: tag command changed a buffer!!!"
    452 In a future version changing the buffer will be impossible.  All this for
    453 security reasons: Somebody might hide a nasty command in the tags file, which
    454 would otherwise go unnoticed.  Example: >
    455 	:$d|/tag-function-name/
    456 
    457 In Vi the ":tag" command sets the last search pattern when the tag is searched
    458 for.  In Vim this is not done, the previous search pattern is still
    459 remembered, unless the 't' flag is present in 'cpoptions'.
    460 
    461 					*emacs-tags* *emacs_tags* *E430*
    462 Emacs style tag files are only supported if Vim was compiled with the
    463 |+emacs_tags| feature enabled.  Sorry, there is no explanation about Emacs tag
    464 files here, it is only supported for backwards compatibility :-).
    465 
    466 Lines in Emacs tags files can be very long.  Vim only deals with lines of up
    467 to about 510 bytes.  To see whether lines are ignored set 'verbose' to 5 or
    468 higher.  Non-Emacs tags file lines can be any length.
    469 
    470 							*tags-option*
    471 The 'tags' option is a list of file names.  Each of these files is searched
    472 for the tag.  This can be used to use a different tags file than the default
    473 file "tags".  It can also be used to access a common tags file.
    474 
    475 The next file in the list is not used when:
    476 - A matching static tag for the current buffer has been found.
    477 - A matching global tag has been found.
    478 This also depends on whether case is ignored.  Case is ignored when:
    479 - 'tagcase' is "followic" and 'ignorecase' is set
    480 - 'tagcase' is "ignore"
    481 - 'tagcase' is "smart" and the pattern only contains lower case
    482   characters.
    483 - 'tagcase' is "followscs" and 'smartcase' is set and the pattern only
    484   contains lower case characters.
    485 If case is not ignored, and the tags file only has a match without matching
    486 case, the next tags file is searched for a match with matching case.  If no
    487 tag with matching case is found, the first match without matching case is
    488 used.  If case is ignored, and a matching global tag with or without matching
    489 case is found, this one is used, no further tags files are searched.
    490 
    491 When a tag file name starts with "./", the '.' is replaced with the path of
    492 the current file.  This makes it possible to use a tags file in the directory
    493 where the current file is (no matter what the current directory is).  The idea
    494 of using "./" is that you can define which tag file is searched first: In the
    495 current directory ("tags,./tags") or in the directory of the current file
    496 ("./tags,tags").
    497 
    498 For example: >
    499 	:set tags=./tags,tags,/home/user/commontags
    500 
    501 In this example the tag will first be searched for in the file "tags" in the
    502 directory where the current file is.  Next the "tags" file in the current
    503 directory.  If it is not found there, then the file "/home/user/commontags"
    504 will be searched for the tag.
    505 
    506 This can be switched off by including the 'd' flag in 'cpoptions', to make
    507 it Vi compatible.  "./tags" will then be the tags file in the current
    508 directory, instead of the tags file in the directory where the current file
    509 is.
    510 
    511 Instead of the comma a space may be used.  Then a backslash is required for
    512 the space to be included in the string option: >
    513 	:set tags=tags\ /home/user/commontags
    514 
    515 To include a space in a file name use three backslashes.  To include a comma
    516 in a file name use two backslashes.  For example, use: >
    517 	:set tags=tag\\\ file,/home/user/common\\,tags
    518 
    519 for the files "tag file" and "/home/user/common,tags".  The 'tags' option will
    520 have the value "tag\ file,/home/user/common\,tags".
    521 
    522 If the 'tagrelative' option is on (which is the default) and using a tag file
    523 in another directory, file names in that tag file are relative to the
    524 directory where the tag file is.
    525 
    526 ==============================================================================
    527 5. Tags file format				*tags-file-format* *E431*
    528 
    529 						*ctags*
    530 A tags file can be created with an external command, for example "ctags".  It
    531 will contain a tag for each function.  Some versions of "ctags" will also make
    532 a tag for each "#defined" macro, typedefs, enums, etc.
    533 
    534 Some programs that generate tags files:
    535 ctags			As found on most Unix systems.  Only supports C.  Only
    536 			does the basic work.
    537 universal ctags		A maintained version of ctags based on exuberant
    538 			ctags.  See https://ctags.io.
    539 							*Exuberant_ctags*
    540 exuberant ctags		This is a very good one.  It works for C, C++, Java,
    541 			Fortran, Eiffel and others.  It can generate tags for
    542 			many items.  See http://ctags.sourceforge.net.
    543 			No new version since 2009.
    544 etags			Connected to Emacs.  Supports many languages.
    545 |:helptags|		For Vim's |help| files
    546 ptags.py		For Python, in Python.  Found in your Python source
    547 			directory at Tools/scripts/ptags.py.
    548 ptags			For Perl, in Perl.  It can be found at
    549 			https://metacpan.org/pod/Vim::Tag
    550 gnatxref		For Ada.  See http://www.gnuada.org/.  gnatxref is
    551 			part of the gnat package.
    552 
    553 
    554 The lines in the tags file must have one of these two formats:
    555 
    556 1.  {tagname}		{TAB} {tagfile} {TAB} {tagaddress}
    557 2.  {tagname}		{TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
    558 
    559 Previously an old format was supported, see |tag-old-static|.
    560 
    561 The first format is a normal tag, which is completely compatible with Vi.  It
    562 is the only format produced by traditional ctags implementations.  This is
    563 often used for functions that are global, also referenced in other files.
    564 
    565 The lines in the tags file can end in <NL> or <CR><NL>.  On the Macintosh <CR>
    566 also works.  The <CR> and <NL> characters can never appear inside a line.
    567 
    568 The second format is new.  It includes additional information in optional
    569 fields at the end of each line.  It is backwards compatible with Vi.  It is
    570 only supported by new versions of ctags (such as Universal ctags or Exuberant
    571 ctags).
    572 
    573 {tagname}	The identifier.  Normally the name of a function, but it can
    574 		be any identifier.  It cannot contain a <Tab>.
    575 {TAB}		One <Tab> character.  Note: previous versions allowed any
    576 		white space here.  This has been abandoned to allow spaces in
    577 		{tagfile}.
    578 {tagfile}	The file that contains the definition of {tagname}.  It can
    579 		have an absolute or relative path.  It may contain environment
    580 		variables and wildcards (although the use of wildcards is
    581 		doubtful).  It cannot contain a <Tab>.
    582 								*E1576*
    583 		Using a remote file via network protocol (e.g. using
    584 		http://remote/file.txt) is not allowed unless 'tagsecure'
    585 		is unset.
    586 {tagaddress}	The Ex command that positions the cursor on the tag.  It can
    587 		be any Ex command, although restrictions apply (see
    588 		|tag-security|).  Posix only allows line numbers and search
    589 		commands, which are mostly used.
    590 {term}		;" The two characters semicolon and double quote.  This is
    591 		interpreted by Vi as the start of a comment, which makes the
    592 		following be ignored.  This is for backwards compatibility
    593 		with Vi, it ignores the following fields.  Example: >
    594 			APP	file	/^static int APP;$/;"	v
    595 <		When {tagaddress} is not a line number or search pattern, then
    596 		{term} must be |;".  Here the bar ends the command (excluding
    597 		the bar) and ;" is used to have Vi ignore the rest of the
    598 		line.  Example: >
    599 			APP	file.c	call cursor(3, 4)|;"	v
    600 
    601 {field} ..	A list of optional fields.  Each field has the form:
    602 
    603 			<Tab>{fieldname}:{value}
    604 
    605 		The {fieldname} identifies the field, and can only contain
    606 		alphabetical characters [a-zA-Z].
    607 		The {value} is any string, but cannot contain a <Tab>.
    608 		These characters are special:
    609 			"\t" stands for a <Tab>
    610 			"\r" stands for a <CR>
    611 			"\n" stands for a <NL>
    612 			"\\" stands for a single '\' character
    613 
    614 		There is one field that doesn't have a ':'.  This is the kind
    615 		of the tag.  It is handled like it was preceded with "kind:".
    616 		In the above example, this was "kind:v" (typically variable).
    617 		See the documentation of ctags for the kinds it produces, with
    618 		ctags you can use `ctags --list-kinds` .
    619 
    620 		The only other field currently recognized by Vim is "file:"
    621 		(with an empty value).  It is used for a static tag.
    622 
    623 
    624 The first lines in the tags file can contain lines that start with
    625 	!_TAG_
    626 These are sorted to the first lines, only rare tags that start with "!" can
    627 sort to before them.  Vim recognizes two items.  The first one is the line
    628 that indicates if the file was sorted.  When this line is found, Vim uses
    629 binary searching for the tags file:
    630 	!_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~
    631 
    632 A tag file may be case-fold sorted to avoid a linear search when case is
    633 ignored.  (Case is ignored when 'ignorecase' is set and 'tagcase' is
    634 "followic", or when 'tagcase' is "ignore".)  See 'tagbsearch' for details.
    635 The value '2' should be used then:
    636 	!_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~
    637 
    638 The other tag that Vim recognizes is the encoding of the tags file:
    639 	!_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} ~
    640 Here "utf-8" is the encoding used for the tags.  Vim will then convert the tag
    641 being searched for from 'encoding' to the encoding of the tags file.  And when
    642 listing tags the reverse happens.  When the conversion fails the unconverted
    643 tag is used.
    644 
    645 							*tag-search*
    646 The command can be any Ex command, but often it is a search command.
    647 Examples:
    648 	tag1	file1	/^main(argc, argv)/ ~
    649 	tag2	file2	108 ~
    650 
    651 The command is always executed with 'magic' not set.  The only special
    652 characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
    653 See |pattern|.  Note that you must put a backslash before each backslash in
    654 the search text.  This is for backwards compatibility with Vi.
    655 
    656 							*E434* *E435*
    657 If the command is a normal search command (it starts and ends with "/" or
    658 "?"), some special handling is done:
    659 - Searching starts on line 1 of the file.
    660   The direction of the search is forward for "/", backward for "?".
    661   Note that 'wrapscan' does not matter, the whole file is always searched.
    662 - If the search fails, another try is done ignoring case.  If that fails too,
    663   a search is done for: >
    664 	"^tagname[ \t]*("
    665 <  (the tag with '^' prepended and "[ \t]*(" appended).  When using function
    666   names, this will find the function name when it is in column 0.  This will
    667   help when the arguments to the function have changed since the tags file was
    668   made.  If this search also fails another search is done with: >
    669 	"^[#a-zA-Z_].*\<tagname[ \t]*("
    670 <  This means: A line starting with '#' or an identifier and containing the tag
    671   followed by white space and a '('.  This will find macro names and function
    672   names with a type prepended.
    673 
    674 
    675 							*tag-old-static*
    676 Until March 2019 (patch 8.1.1092) an outdated format was supported:
    677     {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
    678 
    679 This format is for a static tag only.  It is obsolete now, replaced by
    680 the second format.  It is only supported by Elvis 1.x, older Vim versions and
    681 a few versions of ctags.  A static tag is often used for functions that are
    682 local, only referenced in the file {tagfile}.  Note that for the static tag,
    683 the two occurrences of {tagfile} must be exactly the same.  Also see
    684 |tags-option| below, for how static tags are used.
    685 
    686 The support was removed, since when you can update to the new Vim version you
    687 should also be able to update ctags to one that supports the second format.
    688 
    689 ==============================================================================
    690 6. Include file searches		*include-search* *definition-search*
    691 							*E387* *E388* *E389*
    692 
    693 These commands look for a string in the current file and in all encountered
    694 included files (recursively).  This can be used to find the definition of a
    695 variable, function or macro.  If you only want to search in the current
    696 buffer, use the commands listed at |pattern-searches|.
    697 
    698 These commands are not available when the |+find_in_path| feature was disabled
    699 at compile time.
    700 
    701 When a line is encountered that includes another file, that file is searched
    702 before continuing in the current buffer.  Files included by included files are
    703 also searched.  When an include file could not be found it is silently
    704 ignored.  Use the |:checkpath| command to discover which files could not be
    705 found, possibly your 'path' option is not set up correctly.  Note: the
    706 included file is searched, not a buffer that may be editing that file.  Only
    707 for the current file the lines in the buffer are used.
    708 
    709 The string can be any keyword or a defined macro.  For the keyword any match
    710 will be found.  For defined macros only lines that match with the 'define'
    711 option will be found.  The default is "^#\s*define", which is for C programs.
    712 For other languages you probably want to change this.  See 'define' for an
    713 example for C++.  The string cannot contain an end-of-line, only matches
    714 within a line are found.
    715 
    716 When a match is found for a defined macro, the displaying of lines continues
    717 with the next line when a line ends in a backslash.
    718 
    719 The commands that start with "[" start searching from the start of the current
    720 file.  The commands that start with "]" start at the current cursor position.
    721 
    722 The 'include' option is used to define a line that includes another file.  The
    723 default is "\^#\s*include", which is for C programs.  Note: Vim does not
    724 recognize C syntax, if the 'include' option matches a line inside
    725 "#ifdef/#endif" or inside a comment, it is searched anyway.  The 'isfname'
    726 option is used to recognize the file name that comes after the matched
    727 pattern.
    728 
    729 The 'path' option is used to find the directory for the include files that
    730 do not have an absolute path.
    731 
    732 The 'comments' option is used for the commands that display a single line or
    733 jump to a line.  It defines patterns that may start a comment.  Those lines
    734 are ignored for the search, unless [!] is used.  One exception: When the line
    735 matches the pattern "^# *define" it is not considered to be a comment.
    736 
    737 If you want to list matches, and then select one to jump to, you could use a
    738 mapping to do that for you.  Here is an example: >
    739 
    740   :map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " .. nr .. "[\t"<CR>
    741 <
    742 							*[i*
    743 [i			Display the first line that contains the keyword
    744 			under the cursor.  The search starts at the beginning
    745 			of the file.  Lines that look like a comment are
    746 			ignored (see 'comments' option).  If a count is given,
    747 			the count'th matching line is displayed, and comment
    748 			lines are not ignored.
    749 
    750 							*]i*
    751 ]i			like "[i", but start at the current cursor position.
    752 
    753 							*:is* *:isearch*
    754 :[range]is[earch][!] [count] [/]pattern[/]
    755 			Like "[i"  and "]i", but search in [range] lines
    756 			(default: whole file).
    757 			See |:search-args| for [/] and [!].
    758 
    759 							*[I*
    760 [I			Display all lines that contain the keyword under the
    761 			cursor.  Filenames and line numbers are displayed
    762 			for the found lines.  The search starts at the
    763 			beginning of the file.
    764 
    765 							*]I*
    766 ]I			like "[I", but start at the current cursor position.
    767 
    768 							*:il* *:ilist*
    769 :[range]il[ist][!] [/]pattern[/]
    770 			Like "[I" and "]I", but search in [range] lines
    771 			(default: whole file).
    772 			See |:search-args| for [/] and [!].
    773 
    774 							*[_CTRL-I*
    775 [ CTRL-I		Jump to the first line that contains the keyword
    776 			under the cursor.  The search starts at the beginning
    777 			of the file.  Lines that look like a comment are
    778 			ignored (see 'comments' option).  If a count is given,
    779 			the count'th matching line is jumped to, and comment
    780 			lines are not ignored.
    781 
    782 							*]_CTRL-I*
    783 ] CTRL-I		like "[ CTRL-I", but start at the current cursor
    784 			position.
    785 
    786 							*:ij* *:ijump*
    787 :[range]ij[ump][!] [count] [/]pattern[/]
    788 			Like "[ CTRL-I"  and "] CTRL-I", but search in
    789 			[range] lines (default: whole file).
    790 			See |:search-args| for [/] and [!].
    791 
    792 CTRL-W CTRL-I					*CTRL-W_CTRL-I* *CTRL-W_i*
    793 CTRL-W i		Open a new window, with the cursor on the first line
    794 			that contains the keyword under the cursor.  The
    795 			search starts at the beginning of the file.  Lines
    796 			that look like a comment line are ignored (see
    797 			'comments' option).  If a count is given, the count'th
    798 			matching line is jumped to, and comment lines are not
    799 			ignored.
    800 
    801 							*:isp* *:isplit*
    802 :[range]isp[lit][!] [count] [/]pattern[/]
    803 			Like "CTRL-W i"  and "CTRL-W i", but search in
    804 			[range] lines (default: whole file).
    805 			See |:search-args| for [/] and [!].
    806 
    807 							*[d*
    808 [d			Display the first macro definition that contains the
    809 			macro under the cursor.  The search starts from the
    810 			beginning of the file.  If a count is given, the
    811 			count'th matching line is displayed.
    812 
    813 							*]d*
    814 ]d			like "[d", but start at the current cursor position.
    815 
    816 							*:ds* *:dsearch*
    817 :[range]ds[earch][!] [count] [/]string[/]
    818 			Like "[d"  and "]d", but search in [range] lines
    819 			(default: whole file).
    820 			See |:search-args| for [/] and [!].
    821 
    822 							*[D*
    823 [D			Display all macro definitions that contain the macro
    824 			under the cursor.  Filenames and line numbers are
    825 			displayed for the found lines.  The search starts
    826 			from the beginning of the file.
    827 
    828 							*]D*
    829 ]D			like "[D", but start at the current cursor position.
    830 
    831 							*:dli* *:dlist*
    832 :[range]dli[st][!] [/]string[/]
    833 			Like `[D`  and `]D`, but search in [range] lines
    834 			(default: whole file).
    835 			See |:search-args| for [/] and [!].
    836 			Note: In legacy Vim script, `:dl` works like
    837 			`:delete` with the "l" flag, not `:dlist`, whereas in
    838 			|Vim9| script `:dl` does work like `:dlist`.
    839 
    840 							*[_CTRL-D*
    841 [ CTRL-D		Jump to the first macro definition that contains the
    842 			keyword under the cursor.  The search starts from
    843 			the beginning of the file.  If a count is given, the
    844 			count'th matching line is jumped to.
    845 
    846 							*]_CTRL-D*
    847 ] CTRL-D		like "[ CTRL-D", but start at the current cursor
    848 			position.
    849 
    850 							*:dj* *:djump*
    851 :[range]dj[ump][!] [count] [/]string[/]
    852 			Like "[ CTRL-D"  and "] CTRL-D", but search  in
    853 			[range] lines (default: whole file).
    854 			See |:search-args| for [/] and [!].
    855 
    856 CTRL-W CTRL-D					*CTRL-W_CTRL-D* *CTRL-W_d*
    857 CTRL-W d		Open a new window, with the cursor on the first
    858 			macro definition line that contains the keyword
    859 			under the cursor.  The search starts from the
    860 			beginning of the file.  If a count is given, the
    861 			count'th matching line is jumped to.
    862 
    863 							*:dsp* *:dsplit*
    864 :[range]dsp[lit][!] [count] [/]string[/]
    865 			Like "CTRL-W d", but search in [range] lines
    866 			(default: whole file).
    867 			See |:search-args| for [/] and [!].
    868 
    869 					*:che* *:chec* *:check* *:checkpath*
    870 :che[ckpath]		List all the included files that could not be found.
    871 
    872 :che[ckpath]!		List all the included files.
    873 
    874 								*:search-args*
    875 Common arguments for the commands above:
    876 [!]	When included, find matches in lines that are recognized as comments.
    877 	When excluded, a match is ignored when the line is recognized as a
    878 	comment (according to 'comments'), or the match is in a C comment
    879 	(after "//" or inside /* */).  Note that a match may be missed if a
    880 	line is recognized as a comment, but the comment ends halfway the
    881 	line.  And if the line is a comment, but it is not recognized
    882 	(according to 'comments') a match may be found in it anyway.  Example: >
    883 		/* comment
    884 		   foobar */
    885 <	A match for "foobar" is found, because this line is not recognized as
    886 	a comment (even though syntax highlighting does recognize it).
    887 	Note: Since a macro definition mostly doesn't look like a comment, the
    888 	[!] makes no difference for ":dlist", ":dsearch" and ":djump".
    889 [/]	A pattern can be surrounded by '/'.  Without '/' only whole words are
    890 	matched, using the pattern "\<pattern\>".  Only after the second '/' a
    891 	next command can be appended with '|'.  Example: >
    892 	:isearch /string/ | echo "the last one"
    893 <	For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern
    894 	is used as a literal string, not as a search pattern.
    895 
    896 ==============================================================================
    897 7. Using 'tagfunc'						*tag-function*
    898 
    899 It is possible to provide Vim with a function which will generate a list of
    900 tags used for commands like |:tag|, |:tselect|, Normal mode tag commands like
    901 |CTRL-]| and for the |taglist()| function.
    902 
    903 The function used for generating the taglist is specified by setting the
    904 'tagfunc' option.  The function will be called with three arguments:
    905    pattern	The tag identifier or pattern used during the tag search.
    906    flags	String containing flags to control the function behavior.
    907    info		Dict containing the following entries:
    908 		    buf_ffname	  Full filename which can be used for priority.
    909 		    user_data	  Custom data String, if stored in the tag
    910 				  stack previously by tagfunc.
    911 
    912 Note that in a legacy function "a:" needs to be prepended to the argument name
    913 when using it.
    914 
    915 Currently up to three flags may be passed to the tag function:
    916   'c'		The function was invoked by a normal command being processed
    917 	        (mnemonic: the tag function may use the context around the
    918 		cursor to perform a better job of generating the tag list.)
    919   'i'		In Insert mode, the user was completing a tag (with
    920 		|i_CTRL-X_CTRL-]| or 'complete' contains "`t`" or "`]`").
    921   'r'		The first argument to tagfunc should be interpreted as a
    922 		|pattern| (see |tag-regexp|), such as when using: >
    923 		  :tag /pat
    924 <		It is also given when completing in insert mode.
    925 		If this flag is not present, the argument is usually taken
    926 		literally as the full tag name.
    927 
    928 Note that when 'tagfunc' is set, the priority of the tags described in
    929 |tag-priority| does not apply.  Instead, the priority is exactly as the
    930 ordering of the elements in the list returned by the function.
    931 								*E987*
    932 The function should return a List of Dict entries.  Each Dict must at least
    933 include the following entries and each value must be a string:
    934 	name		Name of the tag.
    935 	filename	Name of the file where the tag is defined.  It is
    936 			either relative to the current directory or a full
    937 			path.
    938 	cmd		Ex command used to locate the tag in the file.  This
    939 			can be a line number, a search pattern or any other
    940 			Ex command, like in a tags file (see
    941 			|tags-file-format|).  A search pattern must start and
    942 			end with "/" or "?".  An invalid value results in
    943 			|E987|.
    944 Note that the format is similar to that of |taglist()|, which makes it possible
    945 to use its output to generate the result.
    946 The following fields are optional:
    947 	kind		Type of the tag.
    948 	user_data	String of custom data stored in the tag stack which
    949 			can be used to disambiguate tags between operations.
    950 
    951 If the function returns |v:null| instead of a List, a standard tag lookup will
    952 be performed instead.
    953 
    954 It is not allowed to change the tagstack from inside 'tagfunc'.  *E986*
    955 It is not allowed to close a window or change window from inside 'tagfunc'.
    956 *E1299*
    957 
    958 The following is a hypothetical example of a function used for 'tagfunc'.  It
    959 uses the output of |taglist()| to generate the result: a list of tags in the
    960 inverse order of file names.
    961 >vim
    962 	function CompareFilenames(item1, item2)
    963 	  let f1 = a:item1['filename']
    964 	  let f2 = a:item2['filename']
    965 	  return f1 >=# f2 ? -1 : f1 <=# f2 ? 1 : 0
    966 	endfunction
    967 
    968 	function TagFunc(pattern, flags, info)
    969 	  let result = taglist(a:pattern)
    970 	  call sort(result, "CompareFilenames")
    971 
    972 	  return result
    973 	endfunc
    974 	set tagfunc=TagFunc
    975 <
    976 Note: When executing |taglist()| the 'tagfunc' function won't be called
    977 recursively.
    978 
    979  vim:tw=78:ts=8:noet:ft=help:norl: