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: