| blob | c08e63310aef1ec4587f86222c2c60e7f6a5dffd |
1 *tagsrch.txt* For Vim version 7.2c. Last change: 2006 Apr 24
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Tags and special searches *tags-and-searches*
9 See section |29.1| of the user manual for an introduction.
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|
18 ==============================================================================
19 1. Jump to a tag *tag-commands*
21 *tag* *tags*
22 A tag is an identifier that appears in a "tags" file. It is a sort of label
23 that can be jumped to. For example: In C programs each function name can be
24 used as a tag. The "tags" file has to be generated by a program like ctags,
25 before the tag commands can be used.
27 With the ":tag" command the cursor will be positioned on the tag. With the
28 CTRL-] command, the keyword on which the cursor is standing is used as the
29 tag. If the cursor is not on a keyword, the first keyword to the right of the
30 cursor is used.
32 The ":tag" command works very well for C programs. If you see a call to a
33 function and wonder what that function does, position the cursor inside of the
34 function name and hit CTRL-]. This will bring you to the function definition.
35 An easy way back is with the CTRL-T command. Also read about the tag stack
36 below.
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.
49 g<LeftMouse> *g<LeftMouse>*
50 <C-LeftMouse> *<C-LeftMouse>* *CTRL-]*
51 CTRL-] 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}
60 *v_CTRL-]*
61 {Visual}CTRL-] Same as ":tag {ident}", where {ident} is the text that
62 is highlighted. {not in Vi}
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.
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.
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 {ident}".
87 The 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
89 with a "/") and for ":tselect", also when 'ignorecase' is off. Note that
90 using ignore-case tag searching disables binary searching in the tags file,
91 which causes a slowdown. This can be avoided by fold-case sorting the tag
92 file. See the 'tagbsearch' option for an explanation.
94 ==============================================================================
95 2. Tag stack *tag-stack* *tagstack* *E425*
97 On the tag stack is remembered which tags you jumped to, and from where.
98 Tags are only pushed onto the stack when the 'tagstack' option is set.
100 g<RightMouse> *g<RightMouse>*
101 <C-RightMouse> *<C-RightMouse>* *CTRL-T*
102 CTRL-T Jump to [count] older entry in the tag stack
103 (default 1). {not in Vi}
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}
109 :[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1).
110 See |tag-!| for [!]. {not in Vi}
112 *:tags*
113 :tags Show the contents of the tag stack. The active
114 entry is marked with a '>'. {not in Vi}
116 The output of ":tags" looks like this:
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
123 This list shows the tags that you jumped to and the cursor position before
124 that jump. The older tags are at the top, the newer at the bottom.
126 The '>' points to the active entry. This is the tag that will be used by the
127 next ":tag" command. The CTRL-T and ":pop" command will use the position
128 above the active entry.
130 Below the "TO" is the number of the current match in the match list. Note
131 that this doesn't change when using ":pop" or ":tag".
133 The line number and file name are remembered to be able to get back to where
134 you were before the tag command. The line number will be correct, also when
135 deleting/inserting lines, unless this was done by another program (e.g.
136 another instance of Vim).
138 For the current file, the "file/line" column shows the text at the position.
139 An indent is removed and a long line is truncated to fit in the window.
141 You can jump to previously used tags with several commands. Some examples:
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
148 The most obvious way to use this is while browsing through the call graph of
149 a program. Consider the following call graph:
151 main ---> FuncA ---> FuncC
152 ---> FuncB
154 (Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
155 You can get from main to FuncA by using CTRL-] on the call to FuncA. Then
156 you can CTRL-] to get to FuncC. If you now want to go back to main you can
157 use CTRL-T twice. Then you can CTRL-] to FuncB.
159 If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the
160 current position in the stack. If the stack was full (it can hold up to 20
161 entries), the oldest entry is deleted and the older entries shift one
162 position up (their index number is decremented by one). If the last used
163 entry was not at the bottom, the entries below the last used one are
164 deleted. This means that an old branch in the call graph is lost. After the
165 commands explained above the tag stack will look like this:
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
171 *E73*
172 When you try to use the tag stack while it doesn't contain anything you will
173 get an error message.
175 ==============================================================================
176 3. Tag match list *tag-matchlist* *E427* *E428*
178 When there are several matching tags, these commands can be used to jump
179 between them. Note that these command don't change the tag stack, they keep
180 the same entry.
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:
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.
216 *:sts* *:stselect*
217 :sts[elect][!] [ident] Does ":tselect[!] [ident]" and splits the window for
218 the selected tag. {not in Vi}
220 *g]*
221 g] Like CTRL-], but use ":tselect" instead of ":tag".
222 {not in Vi}
224 *v_g]*
225 {Visual}g] Same as "g]", but use the highlighted text as the
226 identifier. {not in Vi}
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}
232 *:stj* *:stjump*
233 :stj[ump][!] [ident] Does ":tjump[!] [ident]" and splits the window for the
234 selected tag. {not in Vi}
236 *g_CTRL-]*
237 g CTRL-] Like CTRL-], but use ":tjump" instead of ":tag".
238 {not in Vi}
240 *v_g_CTRL-]*
241 {Visual}g CTRL-] Same as "g CTRL-]", but use the highlighted text as
242 the identifier. {not in Vi}
244 *:tn* *:tnext*
245 :[count]tn[ext][!] Jump to [count] next matching tag (default 1). See
246 |tag-!| for [!]. {not in Vi}
248 *:tp* *:tprevious*
249 :[count]tp[revious][!] Jump to [count] previous matching tag (default 1).
250 See |tag-!| for [!]. {not in Vi}
252 *:tN* *:tNext*
253 :[count]tN[ext][!] Same as ":tprevious". {not in Vi}
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}
260 *:tf* *:tfirst*
261 :[count]tf[irst][!] Same as ":trewind". {not in Vi}
263 *:tl* *:tlast*
264 :tl[ast][!] Jump to last matching tag. See |tag-!| for [!]. {not
265 in Vi}
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}
279 When there is no other message, Vim shows which matching tag has been jumped
280 to, and the number of matching tags: >
281 tag 1 of 3 or more
282 The " or more" is used to indicate that Vim didn't try all the tags files yet.
283 When using ":tnext" a few times, or with ":tlast", more matches may be found.
285 When you didn't see this message because of some other message, or you just
286 want to know where you are, this command will show it again (and jump to the
287 same tag as last time): >
288 :0tn
289 <
290 *tag-skip-file*
291 When a matching tag is found for which the file doesn't exist, this match is
292 skipped and the next matching tag is used. Vim reports this, to notify you of
293 missing files. When the end of the list of matches has been reached, an error
294 message is given.
296 *tag-preview*
297 The tag match list can also be used in the preview window. The commands are
298 the same as above, with a "p" prepended.
299 {not available when compiled without the |+quickfix| feature}
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}
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}
311 *:ptn* *:ptnext*
312 :[count]ptn[ext][!] ":tnext" in the preview window. See |:ptag|.
313 {not in Vi}
315 *:ptp* *:ptprevious*
316 :[count]ptp[revious][!] ":tprevious" in the preview window. See |:ptag|.
317 {not in Vi}
319 *:ptN* *:ptNext*
320 :[count]ptN[ext][!] Same as ":ptprevious". {not in Vi}
322 *:ptr* *:ptrewind*
323 :[count]ptr[ewind][!] ":trewind" in the preview window. See |:ptag|.
324 {not in Vi}
326 *:ptf* *:ptfirst*
327 :[count]ptf[irst][!] Same as ":ptrewind". {not in Vi}
329 *:ptl* *:ptlast*
330 :ptl[ast][!] ":tlast" in the preview window. See |:ptag|.
331 {not in Vi}
333 ==============================================================================
334 4. Tags details *tag-details*
336 *static-tag*
337 A static tag is a tag that is defined for a specific file. In a C program
338 this could be a static function.
340 In Vi jumping to a tag sets the current search pattern. This means that
341 the "n" command after jumping to a tag does not search for the same pattern
342 that it did before jumping to the tag. Vim does not do this as we consider it
343 to be a bug. You can still find the tag search pattern in the search history.
344 If you really want the old Vi behavior, set the 't' flag in 'cpoptions'.
346 *tag-binary-search*
347 Vim 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
349 tags file was sorted on ASCII byte value. Therefore, if no match was found,
350 another try is done with a linear search. If you only want the linear search,
351 reset the 'tagbsearch' option. Or better: Sort the tags file!
353 Note that the binary searching is disabled when not looking for a tag with a
354 specific name. This happens when ignoring case and when a regular expression
355 is used that doesn't start with a fixed string. Tag searching can be a lot
356 slower then. The former can be avoided by case-fold sorting the tags file.
357 See 'tagbsearch' for details.
359 *tag-regexp*
360 The ":tag" and "tselect" commands accept a regular expression argument. See
361 |pattern| for the special characters that can be used.
362 When the argument starts with '/', it is used as a pattern. If the argument
363 does not start with '/', it is taken literally, as a full tag name.
364 Examples: >
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".
371 When the argument both exists literally, and match when used as a regexp, a
372 literal match has a higher priority. For example, ":tag /open" matches "open"
373 before "open_file" and "file_open".
374 When using a pattern case is ignored. If you want to match case use "\C" in
375 the pattern.
377 *tag-!*
378 If the tag is in the current file this will always work. Otherwise the
379 performed actions depend on whether the current file was changed, whether a !
380 is added to the command and on the 'autowrite' option:
382 tag in file autowrite ~
383 current 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 -----------------------------------------------------------------------------
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.
409 *tag-security*
410 Note that Vim forbids some commands, for security reasons. This works like
411 using the 'secure' option for exrc/vimrc files in the current directory. See
412 |trojan-horse| and |sandbox|.
413 When the {tagaddress} changes a buffer, you will get a warning message:
414 "WARNING: tag command changed a buffer!!!"
415 In a future version changing the buffer will be impossible. All this for
416 security reasons: Somebody might hide a nasty command in the tags file, which
417 would otherwise go unnoticed. Example: >
418 :$d|/tag-function-name/
419 {this security prevention is not present in Vi}
421 In Vi the ":tag" command sets the last search pattern when the tag is searched
422 for. In Vim this is not done, the previous search pattern is still remembered,
423 unless the 't' flag is present in 'cpoptions'. The search pattern is always
424 put in the search history, so you can modify it if searching fails.
426 *emacs-tags* *emacs_tags* *E430*
427 Emacs 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
429 files here, it is only supported for backwards compatibility :-).
431 *tags-option*
432 The 'tags' option is a list of file names. Each of these files is searched
433 for the tag. This can be used to use a different tags file than the default
434 file "tags". It can also be used to access a common tags file.
436 The next file in the list is not used when:
437 - A matching static tag for the current buffer has been found.
438 - A matching global tag has been found.
439 This also depends on the 'ignorecase' option. If it is off, and the tags file
440 only has a match without matching case, the next tags file is searched for a
441 match with matching case. If no tag with matching case is found, the first
442 match without matching case is used. If 'ignorecase' is on, and a matching
443 global tag with or without matching case is found, this one is used, no
444 further tags files are searched.
446 When a tag file name starts with "./", the '.' is replaced with the path of
447 the current file. This makes it possible to use a tags file in the directory
448 where the current file is (no matter what the current directory is). The idea
449 of using "./" is that you can define which tag file is searched first: In the
450 current directory ("tags,./tags") or in the directory of the current file
451 ("./tags,tags").
453 For example: >
454 :set tags=./tags,tags,/home/user/commontags
456 In this example the tag will first be searched for in the file "tags" in the
457 directory where the current file is. Next the "tags" file in the current
458 directory. If it is not found there, then the file "/home/user/commontags"
459 will be searched for the tag.
461 This can be switched off by including the 'd' flag in 'cpoptions', to make
462 it Vi compatible. "./tags" will then be the tags file in the current
463 directory, instead of the tags file in the directory where the current file
464 is.
466 Instead of the comma a space may be used. Then a backslash is required for
467 the space to be included in the string option: >
468 :set tags=tags\ /home/user/commontags
470 To include a space in a file name use three backslashes. To include a comma
471 in a file name use two backslashes. For example, use: >
472 :set tags=tag\\\ file,/home/user/common\\,tags
474 for the files "tag file" and "/home/user/common,tags". The 'tags' option will
475 have the value "tag\ file,/home/user/common\,tags".
477 If the 'tagrelative' option is on (which is the default) and using a tag file
478 in another directory, file names in that tag file are relative to the
479 directory where the tag file is.
481 ==============================================================================
482 5. Tags file format *tags-file-format* *E431*
484 *ctags* *jtags*
485 A tags file can be created with an external command, for example "ctags". It
486 will contain a tag for each function. Some versions of "ctags" will also make
487 a tag for each "#defined" macro, typedefs, enums, etc.
489 Some programs that generate tags files:
490 ctags As found on most Unix systems. Only supports C. Only
491 does the basic work.
492 *Exuberant_ctags*
493 exuberant ctags This a very good one. It works for C, C++, Java,
494 Fortran, Eiffel and others. It can generate tags for
495 many items. See http://ctags.sourceforge.net.
496 etags Connected to Emacs. Supports many languages.
497 JTags For Java, in Java. It can be found at
498 http://www.fleiner.com/jtags/.
499 ptags.py For Python, in Python. Found in your Python source
500 directory at Tools/scripts/ptags.py.
501 ptags For Perl, in Perl. It can be found at
502 http://www.eleves.ens.fr:8080/home/nthiery/Tags/.
503 gnatxref For Ada. See http://www.gnuada.org/. gnatxref is
504 part of the gnat package.
507 The lines in the tags file must have one of these three formats:
509 1. {tagname} {TAB} {tagfile} {TAB} {tagaddress}
510 2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
511 3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
513 The first is a normal tag, which is completely compatible with Vi. It is the
514 only format produced by traditional ctags implementations. This is often used
515 for functions that are global, also referenced in other files.
517 The lines in the tags file can end in <LF> or <CR><LF>. On the Macintosh <CR>
518 also works. The <CR> and <NL> characters can never appear inside a line.
520 *tag-old-static*
521 The second format is for a static tag only. It is obsolete now, replaced by
522 the third format. It is only supported by Elvis 1.x and Vim and a few
523 versions of ctags. A static tag is often used for functions that are local,
524 only referenced in the file {tagfile}. Note that for the static tag, the two
525 occurrences of {tagfile} must be exactly the same. Also see |tags-option|
526 below, for how static tags are used.
528 The third format is new. It includes additional information in optional
529 fields at the end of each line. It is backwards compatible with Vi. It is
530 only supported by new versions of ctags (such as Exuberant ctags).
532 {tagname} The identifier. Normally the name of a function, but it can
533 be any identifier. It cannot contain a <Tab>.
534 {TAB} One <Tab> character. Note: previous versions allowed any
535 white space here. This has been abandoned to allow spaces in
536 {tagfile}. It can be re-enabled by including the
537 |+tag_any_white| feature at compile time. *tag-any-white*
538 {tagfile} The file that contains the definition of {tagname}. It can
539 have an absolute or relative path. It may contain environment
540 variables and wildcards (although the use of wildcards is
541 doubtful). It cannot contain a <Tab>.
542 {tagaddress} The Ex command that positions the cursor on the tag. It can
543 be any Ex command, although restrictions apply (see
544 |tag-security|). Posix only allows line numbers and search
545 commands, which are mostly used.
546 {term} ;" The two characters semicolon and double quote. This is
547 interpreted by Vi as the start of a comment, which makes the
548 following be ignored. This is for backwards compatibility
549 with Vi, it ignores the following fields.
550 {field} .. A list of optional fields. Each field has the form:
552 <Tab>{fieldname}:{value}
554 The {fieldname} identifies the field, and can only contain
555 alphabetical characters [a-zA-Z].
556 The {value} is any string, but cannot contain a <Tab>.
557 These characters are special:
558 "\t" stands for a <Tab>
559 "\r" stands for a <CR>
560 "\n" stands for a <NL>
561 "\\" stands for a single '\' character
563 There is one field that doesn't have a ':'. This is the kind
564 of the tag. It is handled like it was preceded with "kind:".
565 See the documentation of ctags for the kinds it produces.
567 The only other field currently recognized by Vim is "file:"
568 (with an empty value). It is used for a static tag.
570 The first lines in the tags file can contain lines that start with
571 !_TAG_
572 These are sorted to the first lines, only rare tags that start with "!" can
573 sort to before them. Vim recognizes two items. The first one is the line
574 that indicates if the file was sorted. When this line is found, Vim uses
575 binary searching for the tags file:
576 !_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~
578 A tag file may be case-fold sorted to avoid a linear search when 'ignorecase'
579 is on. See 'tagbsearch' for details. The value '2' should be used then:
580 !_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~
582 The other tag that Vim recognizes, but only when compiled with the
583 |+multi_byte| feature, is the encoding of the tags file:
584 !_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} ~
585 Here "utf-8" is the encoding used for the tags. Vim will then convert the tag
586 being searched for from 'encoding' to the encoding of the tags file. And when
587 listing tags the reverse happens. When the conversion fails the unconverted
588 tag is used.
590 *tag-search*
591 The command can be any Ex command, but often it is a search command.
592 Examples:
593 tag1 file1 /^main(argc, argv)/ ~
594 tag2 file2 108 ~
596 The command is always executed with 'magic' not set. The only special
597 characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
598 See |pattern|. Note that you must put a backslash before each backslash in
599 the search text. This is for backwards compatibility with Vi.
601 *E434* *E435*
602 If the command is a normal search command (it starts and ends with "/" or
603 "?"), some special handling is done:
604 - Searching starts on line 1 of the file.
605 The direction of the search is forward for "/", backward for "?".
606 Note that 'wrapscan' does not matter, the whole file is always searched. (Vi
607 does use 'wrapscan', which caused tags sometimes not be found.) {Vi starts
608 searching in line 2 of another file. It does not find a tag in line 1 of
609 another file when 'wrapscan' is not set}
610 - If the search fails, another try is done ignoring case. If that fails too,
611 a search is done for:
612 "^tagname[ \t]*("
613 (the tag with '^' prepended and "[ \t]*(" appended). When using function
614 names, this will find the function name when it is in column 0. This will
615 help when the arguments to the function have changed since the tags file was
616 made. If this search also fails another search is done with:
617 "^[#a-zA-Z_].*\<tagname[ \t]*("
618 This means: A line starting with '#' or an identifier and containing the tag
619 followed by white space and a '('. This will find macro names and function
620 names with a type prepended. {the extra searches are not in Vi}
622 ==============================================================================
623 6. Include file searches *include-search* *definition-search*
624 *E387* *E388* *E389*
626 These commands look for a string in the current file and in all encountered
627 included files (recursively). This can be used to find the definition of a
628 variable, function or macro. If you only want to search in the current
629 buffer, use the commands listed at |pattern-searches|.
631 These commands are not available when the |+find_in_path| feature was disabled
632 at compile time.
634 When a line is encountered that includes another file, that file is searched
635 before continuing in the current buffer. Files included by included files are
636 also searched. When an include file could not be found it is silently
637 ignored. Use the |:checkpath| command to discover which files could not be
638 found, possibly your 'path' option is not set up correctly. Note: the
639 included file is searched, not a buffer that may be editing that file. Only
640 for the current file the lines in the buffer are used.
642 The string can be any keyword or a defined macro. For the keyword any match
643 will be found. For defined macros only lines that match with the 'define'
644 option will be found. The default is "^#\s*define", which is for C programs.
645 For other languages you probably want to change this. See 'define' for an
646 example for C++. The string cannot contain an end-of-line, only matches
647 within a line are found.
649 When a match is found for a defined macro, the displaying of lines continues
650 with the next line when a line ends in a backslash.
652 The commands that start with "[" start searching from the start of the current
653 file. The commands that start with "]" start at the current cursor position.
655 The 'include' option is used to define a line that includes another file. The
656 default is "\^#\s*include", which is for C programs. Note: Vim does not
657 recognize C syntax, if the 'include' option matches a line inside
658 "#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname'
659 option is used to recognize the file name that comes after the matched
660 pattern.
662 The 'path' option is used to find the directory for the include files that
663 do not have an absolute path.
665 The 'comments' option is used for the commands that display a single line or
666 jump to a line. It defines patterns that may start a comment. Those lines
667 are ignored for the search, unless [!] is used. One exception: When the line
668 matches the pattern "^# *define" it is not considered to be a comment.
670 If you want to list matches, and then select one to jump to, you could use a
671 mapping to do that for you. Here is an example: >
673 :map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR>
674 <
675 *[i*
676 [i Display the first line that contains the keyword
677 under the cursor. The search starts at the beginning
678 of the file. Lines that look like a comment are
679 ignored (see 'comments' option). If a count is given,
680 the count'th matching line is displayed, and comment
681 lines are not ignored. {not in Vi}
683 *]i*
684 ]i like "[i", but start at the current cursor position.
685 {not in Vi}
687 *:is* *:isearch*
688 :[range]is[earch][!] [count] [/]pattern[/]
689 Like "[i" and "]i", but search in [range] lines
690 (default: whole file).
691 See |:search-args| for [/] and [!]. {not in Vi}
693 *[I*
694 [I Display all lines that contain the keyword under the
695 cursor. Filenames and line numbers are displayed
696 for the found lines. The search starts at the
697 beginning of the file. {not in Vi}
699 *]I*
700 ]I like "[I", but start at the current cursor position.
701 {not in Vi}
703 *:il* *:ilist*
704 :[range]il[ist][!] [/]pattern[/]
705 Like "[I" and "]I", but search in [range] lines
706 (default: whole file).
707 See |:search-args| for [/] and [!]. {not in Vi}
709 *[_CTRL-I*
710 [ CTRL-I Jump to the first line that contains the keyword
711 under the cursor. The search starts at the beginning
712 of the file. Lines that look like a comment are
713 ignored (see 'comments' option). If a count is given,
714 the count'th matching line is jumped to, and comment
715 lines are not ignored. {not in Vi}
717 *]_CTRL-I*
718 ] CTRL-I like "[ CTRL-I", but start at the current cursor
719 position. {not in Vi}
721 *:ij* *:ijump*
722 :[range]ij[ump][!] [count] [/]pattern[/]
723 Like "[ CTRL-I" and "] CTRL-I", but search in
724 [range] lines (default: whole file).
725 See |:search-args| for [/] and [!]. {not in Vi}
727 CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i*
728 CTRL-W i Open a new window, with the cursor on the first line
729 that contains the keyword under the cursor. The
730 search starts at the beginning of the file. Lines
731 that look like a comment line are ignored (see
732 'comments' option). If a count is given, the count'th
733 matching line is jumped to, and comment lines are not
734 ignored. {not in Vi}
736 *:isp* *:isplit*
737 :[range]isp[lit][!] [count] [/]pattern[/]
738 Like "CTRL-W i" and "CTRL-W i", but search in
739 [range] lines (default: whole file).
740 See |:search-args| for [/] and [!]. {not in Vi}
742 *[d*
743 [d Display the first macro definition that contains the
744 macro under the cursor. The search starts from the
745 beginning of the file. If a count is given, the
746 count'th matching line is displayed. {not in Vi}
748 *]d*
749 ]d like "[d", but start at the current cursor position.
750 {not in Vi}
752 *:ds* *:dsearch*
753 :[range]ds[earch][!] [count] [/]string[/]
754 Like "[d" and "]d", but search in [range] lines
755 (default: whole file).
756 See |:search-args| for [/] and [!]. {not in Vi}
758 *[D*
759 [D Display all macro definitions that contain the macro
760 under the cursor. Filenames and line numbers are
761 displayed for the found lines. The search starts
762 from the beginning of the file. {not in Vi}
764 *]D*
765 ]D like "[D", but start at the current cursor position.
766 {not in Vi}
768 *:dli* *:dlist*
769 :[range]dl[ist][!] [/]string[/]
770 Like "[D" and "]D", but search in [range] lines
771 (default: whole file).
772 See |:search-args| for [/] and [!]. {not in Vi}
773 Note that ":dl" works like ":delete" with the "l"
774 flag.
776 *[_CTRL-D*
777 [ CTRL-D Jump to the first macro definition that contains the
778 keyword under the cursor. The search starts from
779 the beginning of the file. If a count is given, the
780 count'th matching line is jumped to. {not in Vi}
782 *]_CTRL-D*
783 ] CTRL-D like "[ CTRL-D", but start at the current cursor
784 position. {not in Vi}
786 *:dj* *:djump*
787 :[range]dj[ump][!] [count] [/]string[/]
788 Like "[ CTRL-D" and "] CTRL-D", but search in
789 [range] lines (default: whole file).
790 See |:search-args| for [/] and [!]. {not in Vi}
792 CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d*
793 CTRL-W d Open a new window, with the cursor on the first
794 macro definition line that contains the keyword
795 under the cursor. The search starts from the
796 beginning of the file. If a count is given, the
797 count'th matching line is jumped to. {not in Vi}
799 *:dsp* *:dsplit*
800 :[range]dsp[lit][!] [count] [/]string[/]
801 Like "CTRL-W d", but search in [range] lines
802 (default: whole file).
803 See |:search-args| for [/] and [!]. {not in Vi}
805 *:che* *:checkpath*
806 :che[ckpath] List all the included files that could not be found.
807 {not in Vi}
809 :che[ckpath]! List all the included files. {not in Vi}
811 *:search-args*
812 Common arguments for the commands above:
813 [!] When included, find matches in lines that are recognized as comments.
814 When excluded, a match is ignored when the line is recognized as a
815 comment (according to 'comments'), or the match is in a C comment (after
816 "//" or inside /* */). Note that a match may be missed if a line is
817 recognized as a comment, but the comment ends halfway the line.
818 And if the line is a comment, but it is not recognized (according to
819 'comments') a match may be found in it anyway. Example: >
820 /* comment
821 foobar */
822 < A match for "foobar" is found, because this line is not recognized as a
823 comment (even though syntax highlighting does recognize it).
824 Note: Since a macro definition mostly doesn't look like a comment, the
825 [!] makes no difference for ":dlist", ":dsearch" and ":djump".
826 [/] A pattern can be surrounded by '/'. Without '/' only whole words are
827 matched, using the pattern "\<pattern\>". Only after the second '/' a
828 next command can be appended with '|'. Example: >
829 :isearch /string/ | echo "the last one"
830 < For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern
831 is used as a literal string, not as a search pattern.
833 vim:tw=78:ts=8:ft=help:norl: