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