1*tagsrch.txt* For Vim version 8.2. Last change: 2020 Dec 19 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Tags and special searches *tags-and-searches* 8 9See section |29.1| of the user manual for an introduction. 10 111. Jump to a tag |tag-commands| 122. Tag stack |tag-stack| 133. Tag match list |tag-matchlist| 144. Tags details |tag-details| 155. Tags file format |tags-file-format| 166. Include file searches |include-search| 177. Using 'tagfunc' |tag-function| 18 19============================================================================== 201. Jump to a tag *tag-commands* 21 22 *tag* *tags* 23A tag is an identifier that appears in a "tags" file. It is a sort of label 24that can be jumped to. For example: In C programs each function name can be 25used as a tag. The "tags" file has to be generated by a program like ctags, 26before the tag commands can be used. 27 28With the ":tag" command the cursor will be positioned on the tag. With the 29CTRL-] command, the keyword on which the cursor is standing is used as the 30tag. If the cursor is not on a keyword, the first keyword to the right of the 31cursor is used. 32 33The ":tag" command works very well for C programs. If you see a call to a 34function and wonder what that function does, position the cursor inside of the 35function name and hit CTRL-]. This will bring you to the function definition. 36An easy way back is with the CTRL-T command. Also read about the tag stack 37below. 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 50g<LeftMouse> *g<LeftMouse>* 51<C-LeftMouse> *<C-LeftMouse>* *CTRL-]* 52CTRL-] 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-]* 65CTRL-] is the default telnet escape key. When you type CTRL-] to jump to a 66tag, you will get the telnet prompt instead. Most versions of telnet allow 67changing or disabling the default escape key. See the telnet man page. You 68can 'telnet -E {Hostname}' to disable the escape character, or 'telnet -e 69{EscapeCharacter} {Hostname}' to specify another escape character. If 70possible, try to use "ssh" instead of "telnet" to avoid this problem. 71 72 *tag-priority* 73When there are multiple matches for a tag, this priority is used: 741. "FSC" A full matching static tag for the current file. 752. "F C" A full matching global tag for the current file. 763. "F " A full matching global tag for another file. 774. "FS " A full matching static tag for another file. 785. " SC" An ignore-case matching static tag for the current file. 796. " C" An ignore-case matching global tag for the current file. 807. " " An ignore-case matching global tag for another file. 818. " S " An ignore-case matching static tag for another file. 82 83Note that when the current file changes, the priority list is mostly not 84changed, to avoid confusion when using ":tnext". It is changed when using 85":tag {name}". 86 87The 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 94The 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 patter does not contain an upper case 102 character 103 104Note that using ignore-case tag searching disables binary searching in the 105tags file, which causes a slowdown. This can be avoided by fold-case sorting 106the tag file. See the 'tagbsearch' option for an explanation. 107 108============================================================================== 1092. Tag stack *tag-stack* *tagstack* *E425* 110 111On the tag stack is remembered which tags you jumped to, and from where. 112Tags are only pushed onto the stack when the 'tagstack' option is set. 113 114g<RightMouse> *g<RightMouse>* 115<C-RightMouse> *<C-RightMouse>* *CTRL-T* 116CTRL-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 130The 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 137This list shows the tags that you jumped to and the cursor position before 138that jump. The older tags are at the top, the newer at the bottom. 139 140The '>' points to the active entry. This is the tag that will be used by the 141next ":tag" command. The CTRL-T and ":pop" command will use the position 142above the active entry. 143 144Below the "TO" is the number of the current match in the match list. Note 145that this doesn't change when using ":pop" or ":tag". 146 147The line number and file name are remembered to be able to get back to where 148you were before the tag command. The line number will be correct, also when 149deleting/inserting lines, unless this was done by another program (e.g. 150another instance of Vim). 151 152For the current file, the "file/text" column shows the text at the position. 153An indent is removed and a long line is truncated to fit in the window. 154 155You 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 162The most obvious way to use this is while browsing through the call graph of 163a program. Consider the following call graph: 164 165 main ---> FuncA ---> FuncC 166 ---> FuncB 167 168(Explanation: main calls FuncA and FuncB; FuncA calls FuncC). 169You can get from main to FuncA by using CTRL-] on the call to FuncA. Then 170you can CTRL-] to get to FuncC. If you now want to go back to main you can 171use CTRL-T twice. Then you can CTRL-] to FuncB. 172 173If you issue a ":ta {name}" or CTRL-] command, this tag is inserted at the 174current position in the stack. If the stack was full (it can hold up to 20 175entries), the oldest entry is deleted and the older entries shift one 176position up (their index number is decremented by one). If the last used 177entry was not at the bottom, the entries below the last used one are 178deleted. This means that an old branch in the call graph is lost. After the 179commands 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 185The |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* 189Write to the tag stack just like `:tag` but with a user-defined 190jumper#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< 203Set current index of the tag stack to 4: > 204 call settagstack(1005, {'curidx' : 4}) 205< 206Push 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* 212When you try to use the tag stack while it doesn't contain anything you will 213get an error message. 214 215============================================================================== 2163. Tag match list *tag-matchlist* *E427* *E428* 217 218When there are several matching tags, these commands can be used to jump 219between them. Note that these commands don't change the tag stack, they keep 220the 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]* 262g] 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-]* 277g 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 315When there is no other message, Vim shows which matching tag has been jumped 316to, and the number of matching tags: > 317 tag 1 of 3 or more 318The " or more" is used to indicate that Vim didn't try all the tags files yet. 319When using ":tnext" a few times, or with ":tlast", more matches may be found. 320 321When you didn't see this message because of some other message, or you just 322want to know where you are, this command will show it again (and jump to the 323same tag as last time): > 324 :0tn 325< 326 *tag-skip-file* 327When a matching tag is found for which the file doesn't exist, this match is 328skipped and the next matching tag is used. Vim reports this, to notify you of 329missing files. When the end of the list of matches has been reached, an error 330message is given. 331 332 *tag-preview* 333The tag match list can also be used in the preview window. The commands are 334the 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============================================================================== 3644. Tags details *tag-details* 365 366 *static-tag* 367A static tag is a tag that is defined for a specific file. In a C program 368this could be a static function. 369 370In 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 372it did before jumping to the tag. Vim does not do this as we consider it to 373be a bug. If you really want the old Vi behavior, set the 't' flag in 374'cpoptions'. 375 376 *tag-binary-search* 377Vim 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 379tags file was sorted on ASCII byte value. Therefore, if no match was found, 380another try is done with a linear search. If you only want the linear search, 381reset the 'tagbsearch' option. Or better: Sort the tags file! 382 383Note that the binary searching is disabled when not looking for a tag with a 384specific name. This happens when ignoring case and when a regular expression 385is used that doesn't start with a fixed string. Tag searching can be a lot 386slower then. The former can be avoided by case-fold sorting the tags file. 387See 'tagbsearch' for details. 388 389 *tag-regexp* 390The ":tag" and ":tselect" commands accept a regular expression argument. See 391|pattern| for the special characters that can be used. 392When the argument starts with '/', it is used as a pattern. If the argument 393does not start with '/', it is taken literally, as a full tag name. 394Examples: > 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". 401When the argument both exists literally, and match when used as a regexp, a 402literal match has a higher priority. For example, ":tag /open" matches "open" 403before "open_file" and "file_open". 404When using a pattern case is ignored. If you want to match case use "\C" in 405the pattern. 406 407 *tag-!* 408If the tag is in the current file this will always work. Otherwise the 409performed actions depend on whether the current file was changed, whether a ! 410is added to the command and on the 'autowrite' option: 411 412 tag in file autowrite ~ 413current file changed ! option action ~ 414----------------------------------------------------------------------------- 415 yes x x x goto tag 416 no no x x read other file, goto tag 417 no yes yes x abandon current file, read other file, goto 418 tag 419 no yes no on write current file, read other file, goto 420 tag 421 no yes no off fail 422----------------------------------------------------------------------------- 423 424- If the tag is in the current file, the command will always work. 425- If the tag is in another file and the current file was not changed, the 426 other file will be made the current file and read into the buffer. 427- If the tag is in another file, the current file was changed and a ! is 428 added to the command, the changes to the current file are lost, the other 429 file will be made the current file and read into the buffer. 430- If the tag is in another file, the current file was changed and the 431 'autowrite' option is on, the current file will be written, the other 432 file will be made the current file and read into the buffer. 433- If the tag is in another file, the current file was changed and the 434 'autowrite' option is off, the command will fail. If you want to save 435 the changes, use the ":w" command and then use ":tag" without an argument. 436 This works because the tag is put on the stack anyway. If you want to lose 437 the changes you can use the ":tag!" command. 438 439 *tag-security* 440Note that Vim forbids some commands, for security reasons. This works like 441using the 'secure' option for exrc/vimrc files in the current directory. See 442|trojan-horse| and |sandbox|. 443When the {tagaddress} changes a buffer, you will get a warning message: 444 "WARNING: tag command changed a buffer!!!" 445In a future version changing the buffer will be impossible. All this for 446security reasons: Somebody might hide a nasty command in the tags file, which 447would otherwise go unnoticed. Example: > 448 :$d|/tag-function-name/ 449 450In Vi the ":tag" command sets the last search pattern when the tag is searched 451for. In Vim this is not done, the previous search pattern is still remembered, 452unless the 't' flag is present in 'cpoptions'. 453 454 *emacs-tags* *emacs_tags* *E430* 455Emacs style tag files are only supported if Vim was compiled with the 456|+emacs_tags| feature enabled. Sorry, there is no explanation about Emacs tag 457files here, it is only supported for backwards compatibility :-). 458 459Lines in Emacs tags files can be very long. Vim only deals with lines of up 460to about 510 bytes. To see whether lines are ignored set 'verbose' to 5 or 461higher. Non-Emacs tags file lines can be any length. 462 463 *tags-option* 464The 'tags' option is a list of file names. Each of these files is searched 465for the tag. This can be used to use a different tags file than the default 466file "tags". It can also be used to access a common tags file. 467 468The next file in the list is not used when: 469- A matching static tag for the current buffer has been found. 470- A matching global tag has been found. 471This also depends on whether case is ignored. Case is ignored when: 472- 'tagcase' is "followic" and 'ignorecase' is set 473- 'tagcase' is "ignore" 474- 'tagcase' is "smart" and the pattern only contains lower case 475 characters. 476- 'tagcase' is "followscs" and 'smartcase' is set and the pattern only 477 contains lower case characters. 478If case is not ignored, and the tags file only has a match without matching 479case, the next tags file is searched for a match with matching case. If no 480tag with matching case is found, the first match without matching case is 481used. If case is ignored, and a matching global tag with or without matching 482case is found, this one is used, no further tags files are searched. 483 484When a tag file name starts with "./", the '.' is replaced with the path of 485the current file. This makes it possible to use a tags file in the directory 486where the current file is (no matter what the current directory is). The idea 487of using "./" is that you can define which tag file is searched first: In the 488current directory ("tags,./tags") or in the directory of the current file 489("./tags,tags"). 490 491For example: > 492 :set tags=./tags,tags,/home/user/commontags 493 494In this example the tag will first be searched for in the file "tags" in the 495directory where the current file is. Next the "tags" file in the current 496directory. If it is not found there, then the file "/home/user/commontags" 497will be searched for the tag. 498 499This can be switched off by including the 'd' flag in 'cpoptions', to make 500it Vi compatible. "./tags" will then be the tags file in the current 501directory, instead of the tags file in the directory where the current file 502is. 503 504Instead of the comma a space may be used. Then a backslash is required for 505the space to be included in the string option: > 506 :set tags=tags\ /home/user/commontags 507 508To include a space in a file name use three backslashes. To include a comma 509in a file name use two backslashes. For example, use: > 510 :set tags=tag\\\ file,/home/user/common\\,tags 511 512for the files "tag file" and "/home/user/common,tags". The 'tags' option will 513have the value "tag\ file,/home/user/common\,tags". 514 515If the 'tagrelative' option is on (which is the default) and using a tag file 516in another directory, file names in that tag file are relative to the 517directory where the tag file is. 518 519============================================================================== 5205. Tags file format *tags-file-format* *E431* 521 522 *ctags* *jtags* 523A tags file can be created with an external command, for example "ctags". It 524will contain a tag for each function. Some versions of "ctags" will also make 525a tag for each "#defined" macro, typedefs, enums, etc. 526 527Some programs that generate tags files: 528ctags As found on most Unix systems. Only supports C. Only 529 does the basic work. 530universal ctags A maintained version of ctags based on exuberant 531 ctags. See https://ctags.io. 532 *Exuberant_ctags* 533exuberant ctags This is a very good one. It works for C, C++, Java, 534 Fortran, Eiffel and others. It can generate tags for 535 many items. See http://ctags.sourceforge.net. 536 No new version since 2009. 537etags Connected to Emacs. Supports many languages. 538JTags For Java, in Java. It can be found at 539 http://www.fleiner.com/jtags/. 540ptags.py For Python, in Python. Found in your Python source 541 directory at Tools/scripts/ptags.py. 542ptags For Perl, in Perl. It can be found at 543 http://www.eleves.ens.fr:8080/home/nthiery/Tags/. 544gnatxref For Ada. See http://www.gnuada.org/. gnatxref is 545 part of the gnat package. 546 547 548The lines in the tags file must have one of these two formats: 549 5501. {tagname} {TAB} {tagfile} {TAB} {tagaddress} 5512. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} .. 552 553Previously an old format was supported, see |tag-old-static|. 554 555The first format is a normal tag, which is completely compatible with Vi. It 556is the only format produced by traditional ctags implementations. This is 557often used for functions that are global, also referenced in other files. 558 559The lines in the tags file can end in <NL> or <CR><NL>. On the Macintosh <CR> 560also works. The <CR> and <NL> characters can never appear inside a line. 561 562The second format is new. It includes additional information in optional 563fields at the end of each line. It is backwards compatible with Vi. It is 564only supported by new versions of ctags (such as Exuberant ctags). 565 566{tagname} The identifier. Normally the name of a function, but it can 567 be any identifier. It cannot contain a <Tab>. 568{TAB} One <Tab> character. Note: previous versions allowed any 569 white space here. This has been abandoned to allow spaces in 570 {tagfile}. 571{tagfile} The file that contains the definition of {tagname}. It can 572 have an absolute or relative path. It may contain environment 573 variables and wildcards (although the use of wildcards is 574 doubtful). It cannot contain a <Tab>. 575{tagaddress} The Ex command that positions the cursor on the tag. It can 576 be any Ex command, although restrictions apply (see 577 |tag-security|). Posix only allows line numbers and search 578 commands, which are mostly used. 579{term} ;" The two characters semicolon and double quote. This is 580 interpreted by Vi as the start of a comment, which makes the 581 following be ignored. This is for backwards compatibility 582 with Vi, it ignores the following fields. Example: 583 APP file /^static int APP;$/;" v 584 When {tagaddress} is not a line number or search pattern, then 585 {term} must be |;". Here the bar ends the command (excluding 586 the bar) and ;" is used to have Vi ignore the rest of the 587 line. Example: 588 APP file.c call cursor(3, 4)|;" v 589 590{field} .. A list of optional fields. Each field has the form: 591 592 <Tab>{fieldname}:{value} 593 594 The {fieldname} identifies the field, and can only contain 595 alphabetical characters [a-zA-Z]. 596 The {value} is any string, but cannot contain a <Tab>. 597 These characters are special: 598 "\t" stands for a <Tab> 599 "\r" stands for a <CR> 600 "\n" stands for a <NL> 601 "\\" stands for a single '\' character 602 603 There is one field that doesn't have a ':'. This is the kind 604 of the tag. It is handled like it was preceded with "kind:". 605 See the documentation of ctags for the kinds it produces. 606 607 The only other field currently recognized by Vim is "file:" 608 (with an empty value). It is used for a static tag. 609 610 611The first lines in the tags file can contain lines that start with 612 !_TAG_ 613These are sorted to the first lines, only rare tags that start with "!" can 614sort to before them. Vim recognizes two items. The first one is the line 615that indicates if the file was sorted. When this line is found, Vim uses 616binary searching for the tags file: 617 !_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~ 618 619A tag file may be case-fold sorted to avoid a linear search when case is 620ignored. (Case is ignored when 'ignorecase' is set and 'tagcase' is 621"followic", or when 'tagcase' is "ignore".) See 'tagbsearch' for details. 622The value '2' should be used then: 623 !_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~ 624 625The other tag that Vim recognizes is the encoding of the tags file: 626 !_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} ~ 627Here "utf-8" is the encoding used for the tags. Vim will then convert the tag 628being searched for from 'encoding' to the encoding of the tags file. And when 629listing tags the reverse happens. When the conversion fails the unconverted 630tag is used. 631 632 *tag-search* 633The command can be any Ex command, but often it is a search command. 634Examples: 635 tag1 file1 /^main(argc, argv)/ ~ 636 tag2 file2 108 ~ 637 638The command is always executed with 'magic' not set. The only special 639characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>). 640See |pattern|. Note that you must put a backslash before each backslash in 641the search text. This is for backwards compatibility with Vi. 642 643 *E434* *E435* 644If the command is a normal search command (it starts and ends with "/" or 645"?"), some special handling is done: 646- Searching starts on line 1 of the file. 647 The direction of the search is forward for "/", backward for "?". 648 Note that 'wrapscan' does not matter, the whole file is always searched. 649- If the search fails, another try is done ignoring case. If that fails too, 650 a search is done for: 651 "^tagname[ \t]*(" 652 (the tag with '^' prepended and "[ \t]*(" appended). When using function 653 names, this will find the function name when it is in column 0. This will 654 help when the arguments to the function have changed since the tags file was 655 made. If this search also fails another search is done with: 656 "^[#a-zA-Z_].*\<tagname[ \t]*(" 657 This means: A line starting with '#' or an identifier and containing the tag 658 followed by white space and a '('. This will find macro names and function 659 names with a type prepended. 660 661 662 *tag-old-static* 663Until March 2019 (patch 8.1.1092) an outdated format was supported: 664 {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress} 665 666This format is for a static tag only. It is obsolete now, replaced by 667the second format. It is only supported by Elvis 1.x, older Vim versions and 668a few versions of ctags. A static tag is often used for functions that are 669local, only referenced in the file {tagfile}. Note that for the static tag, 670the two occurrences of {tagfile} must be exactly the same. Also see 671|tags-option| below, for how static tags are used. 672 673The support was removed, since when you can update to the new Vim version you 674should also be able to update ctags to one that supports the second format. 675 676============================================================================== 6776. Include file searches *include-search* *definition-search* 678 *E387* *E388* *E389* 679 680These commands look for a string in the current file and in all encountered 681included files (recursively). This can be used to find the definition of a 682variable, function or macro. If you only want to search in the current 683buffer, use the commands listed at |pattern-searches|. 684 685These commands are not available when the |+find_in_path| feature was disabled 686at compile time. 687 688When a line is encountered that includes another file, that file is searched 689before continuing in the current buffer. Files included by included files are 690also searched. When an include file could not be found it is silently 691ignored. Use the |:checkpath| command to discover which files could not be 692found, possibly your 'path' option is not set up correctly. Note: the 693included file is searched, not a buffer that may be editing that file. Only 694for the current file the lines in the buffer are used. 695 696The string can be any keyword or a defined macro. For the keyword any match 697will be found. For defined macros only lines that match with the 'define' 698option will be found. The default is "^#\s*define", which is for C programs. 699For other languages you probably want to change this. See 'define' for an 700example for C++. The string cannot contain an end-of-line, only matches 701within a line are found. 702 703When a match is found for a defined macro, the displaying of lines continues 704with the next line when a line ends in a backslash. 705 706The commands that start with "[" start searching from the start of the current 707file. The commands that start with "]" start at the current cursor position. 708 709The 'include' option is used to define a line that includes another file. The 710default is "\^#\s*include", which is for C programs. Note: Vim does not 711recognize C syntax, if the 'include' option matches a line inside 712"#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname' 713option is used to recognize the file name that comes after the matched 714pattern. 715 716The 'path' option is used to find the directory for the include files that 717do not have an absolute path. 718 719The 'comments' option is used for the commands that display a single line or 720jump to a line. It defines patterns that may start a comment. Those lines 721are ignored for the search, unless [!] is used. One exception: When the line 722matches the pattern "^# *define" it is not considered to be a comment. 723 724If you want to list matches, and then select one to jump to, you could use a 725mapping to do that for you. Here is an example: > 726 727 :map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR> 728< 729 *[i* 730[i Display the first line that contains the keyword 731 under the cursor. The search starts at the beginning 732 of the file. Lines that look like a comment are 733 ignored (see 'comments' option). If a count is given, 734 the count'th matching line is displayed, and comment 735 lines are not ignored. 736 737 *]i* 738]i like "[i", but start at the current cursor position. 739 740 *:is* *:isearch* 741:[range]is[earch][!] [count] [/]pattern[/] 742 Like "[i" and "]i", but search in [range] lines 743 (default: whole file). 744 See |:search-args| for [/] and [!]. 745 746 *[I* 747[I Display all lines that contain the keyword under the 748 cursor. Filenames and line numbers are displayed 749 for the found lines. The search starts at the 750 beginning of the file. 751 752 *]I* 753]I like "[I", but start at the current cursor position. 754 755 *:il* *:ilist* 756:[range]il[ist][!] [/]pattern[/] 757 Like "[I" and "]I", but search in [range] lines 758 (default: whole file). 759 See |:search-args| for [/] and [!]. 760 761 *[_CTRL-I* 762[ CTRL-I Jump to the first line that contains the keyword 763 under the cursor. The search starts at the beginning 764 of the file. Lines that look like a comment are 765 ignored (see 'comments' option). If a count is given, 766 the count'th matching line is jumped to, and comment 767 lines are not ignored. 768 769 *]_CTRL-I* 770] CTRL-I like "[ CTRL-I", but start at the current cursor 771 position. 772 773 *:ij* *:ijump* 774:[range]ij[ump][!] [count] [/]pattern[/] 775 Like "[ CTRL-I" and "] CTRL-I", but search in 776 [range] lines (default: whole file). 777 See |:search-args| for [/] and [!]. 778 779CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i* 780CTRL-W i Open a new window, with the cursor on the first line 781 that contains the keyword under the cursor. The 782 search starts at the beginning of the file. Lines 783 that look like a comment line are ignored (see 784 'comments' option). If a count is given, the count'th 785 matching line is jumped to, and comment lines are not 786 ignored. 787 788 *:isp* *:isplit* 789:[range]isp[lit][!] [count] [/]pattern[/] 790 Like "CTRL-W i" and "CTRL-W i", but search in 791 [range] lines (default: whole file). 792 See |:search-args| for [/] and [!]. 793 794 *[d* 795[d Display the first macro definition that contains the 796 macro under the cursor. The search starts from the 797 beginning of the file. If a count is given, the 798 count'th matching line is displayed. 799 800 *]d* 801]d like "[d", but start at the current cursor position. 802 803 *:ds* *:dsearch* 804:[range]ds[earch][!] [count] [/]string[/] 805 Like "[d" and "]d", but search in [range] lines 806 (default: whole file). 807 See |:search-args| for [/] and [!]. 808 809 *[D* 810[D Display all macro definitions that contain the macro 811 under the cursor. Filenames and line numbers are 812 displayed for the found lines. The search starts 813 from the beginning of the file. 814 815 *]D* 816]D like "[D", but start at the current cursor position. 817 818 *:dli* *:dlist* 819:[range]dli[st][!] [/]string[/] 820 Like `[D` and `]D`, but search in [range] lines 821 (default: whole file). 822 See |:search-args| for [/] and [!]. 823 Note that `:dl` works like `:delete` with the "l" 824 flag, not `:dlist`. 825 826 *[_CTRL-D* 827[ CTRL-D Jump to the first macro definition that contains the 828 keyword under the cursor. The search starts from 829 the beginning of the file. If a count is given, the 830 count'th matching line is jumped to. 831 832 *]_CTRL-D* 833] CTRL-D like "[ CTRL-D", but start at the current cursor 834 position. 835 836 *:dj* *:djump* 837:[range]dj[ump][!] [count] [/]string[/] 838 Like "[ CTRL-D" and "] CTRL-D", but search in 839 [range] lines (default: whole file). 840 See |:search-args| for [/] and [!]. 841 842CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d* 843CTRL-W d Open a new window, with the cursor on the first 844 macro definition line that contains the keyword 845 under the cursor. The search starts from the 846 beginning of the file. If a count is given, the 847 count'th matching line is jumped to. 848 849 *:dsp* *:dsplit* 850:[range]dsp[lit][!] [count] [/]string[/] 851 Like "CTRL-W d", but search in [range] lines 852 (default: whole file). 853 See |:search-args| for [/] and [!]. 854 855 *:che* *:chec* *:check* *:checkpath* 856:che[ckpath] List all the included files that could not be found. 857 858:che[ckpath]! List all the included files. 859 860 *:search-args* 861Common arguments for the commands above: 862[!] When included, find matches in lines that are recognized as comments. 863 When excluded, a match is ignored when the line is recognized as a 864 comment (according to 'comments'), or the match is in a C comment 865 (after "//" or inside /* */). Note that a match may be missed if a 866 line is recognized as a comment, but the comment ends halfway the line. 867 And if the line is a comment, but it is not recognized (according to 868 'comments') a match may be found in it anyway. Example: > 869 /* comment 870 foobar */ 871< A match for "foobar" is found, because this line is not recognized as 872 a comment (even though syntax highlighting does recognize it). 873 Note: Since a macro definition mostly doesn't look like a comment, the 874 [!] makes no difference for ":dlist", ":dsearch" and ":djump". 875[/] A pattern can be surrounded by '/'. Without '/' only whole words are 876 matched, using the pattern "\<pattern\>". Only after the second '/' a 877 next command can be appended with '|'. Example: > 878 :isearch /string/ | echo "the last one" 879< For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern 880 is used as a literal string, not as a search pattern. 881 882============================================================================== 8837. Using 'tagfunc' *tag-function* 884 885It is possible to provide Vim with a function which will generate a list of 886tags used for commands like |:tag|, |:tselect| and Normal mode tag commands 887like |CTRL-]|. 888 889The function used for generating the taglist is specified by setting the 890'tagfunc' option. The function will be called with three arguments: 891 a:pattern The tag identifier or pattern used during the tag search. 892 a:flags String containing flags to control the function behavior. 893 a:info Dict containing the following entries: 894 buf_ffname Full filename which can be used for priority. 895 user_data Custom data String, if stored in the tag 896 stack previously by tagfunc. 897 898Currently up to three flags may be passed to the tag function: 899 'c' The function was invoked by a normal command being processed 900 (mnemonic: the tag function may use the context around the 901 cursor to perform a better job of generating the tag list.) 902 'i' In Insert mode, the user was completing a tag (with 903 |i_CTRL-X_CTRL-]| or 'completeopt' contains `t`). 904 'r' The first argument to tagfunc should be interpreted as a 905 |pattern| (see |tag-regexp|), such as when using: > 906 :tag /pat 907< It is also given when completing in insert mode. 908 If this flag is not present, the argument is usually taken 909 literally as the full tag name. 910 911Note that when 'tagfunc' is set, the priority of the tags described in 912|tag-priority| does not apply. Instead, the priority is exactly as the 913ordering of the elements in the list returned by the function. 914 *E987* 915The function should return a List of Dict entries. Each Dict must at least 916include the following entries and each value must be a string: 917 name Name of the tag. 918 filename Name of the file where the tag is defined. It is 919 either relative to the current directory or a full path. 920 cmd Ex command used to locate the tag in the file. This 921 can be either an Ex search pattern or a line number. 922Note that the format is similar to that of |taglist()|, which makes it possible 923to use its output to generate the result. 924The following fields are optional: 925 kind Type of the tag. 926 user_data String of custom data stored in the tag stack which 927 can be used to disambiguate tags between operations. 928 929If the function returns |v:null| instead of a List, a standard tag lookup will 930be performed instead. 931 932It is not allowed to change the tagstack from inside 'tagfunc'. *E986* 933 934The following is a hypothetical example of a function used for 'tagfunc'. It 935uses the output of |taglist()| to generate the result: a list of tags in the 936inverse order of file names. 937> 938 function TagFunc(pattern, flags, info) 939 function CompareFilenames(item1, item2) 940 let f1 = a:item1['filename'] 941 let f2 = a:item2['filename'] 942 return f1 >=# f2 ? 943 \ -1 : f1 <=# f2 ? 1 : 0 944 endfunction 945 946 let result = taglist(a:pattern) 947 call sort(result, "CompareFilenames") 948 949 return result 950 endfunc 951 set tagfunc=TagFunc 952< 953 954 vim:tw=78:ts=8:noet:ft=help:norl: 955