| blob | 15ebbd4646b91723f8cea5d9c02a37e21a288ee6 |
1 *tagsrch.txt* For Vim version 7.2. Last change: 2009 Feb 18
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 commands 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 Lines in Emacs tags files can be very long. Vim only deals with lines of up
432 to about 510 bytes. To see whether lines are ignored set 'verbose' to 5 or
433 higher.
435 *tags-option*
436 The 'tags' option is a list of file names. Each of these files is searched
437 for the tag. This can be used to use a different tags file than the default
438 file "tags". It can also be used to access a common tags file.
440 The 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.
443 This also depends on the 'ignorecase' option. If it is off, and the tags file
444 only has a match without matching case, the next tags file is searched for a
445 match with matching case. If no tag with matching case is found, the first
446 match without matching case is used. If 'ignorecase' is on, and a matching
447 global tag with or without matching case is found, this one is used, no
448 further tags files are searched.
450 When a tag file name starts with "./", the '.' is replaced with the path of
451 the current file. This makes it possible to use a tags file in the directory
452 where the current file is (no matter what the current directory is). The idea
453 of using "./" is that you can define which tag file is searched first: In the
454 current directory ("tags,./tags") or in the directory of the current file
455 ("./tags,tags").
457 For example: >
458 :set tags=./tags,tags,/home/user/commontags
460 In this example the tag will first be searched for in the file "tags" in the
461 directory where the current file is. Next the "tags" file in the current
462 directory. If it is not found there, then the file "/home/user/commontags"
463 will be searched for the tag.
465 This can be switched off by including the 'd' flag in 'cpoptions', to make
466 it Vi compatible. "./tags" will then be the tags file in the current
467 directory, instead of the tags file in the directory where the current file
468 is.
470 Instead of the comma a space may be used. Then a backslash is required for
471 the space to be included in the string option: >
472 :set tags=tags\ /home/user/commontags
474 To include a space in a file name use three backslashes. To include a comma
475 in a file name use two backslashes. For example, use: >
476 :set tags=tag\\\ file,/home/user/common\\,tags
478 for the files "tag file" and "/home/user/common,tags". The 'tags' option will
479 have the value "tag\ file,/home/user/common\,tags".
481 If the 'tagrelative' option is on (which is the default) and using a tag file
482 in another directory, file names in that tag file are relative to the
483 directory where the tag file is.
485 ==============================================================================
486 5. Tags file format *tags-file-format* *E431*
488 *ctags* *jtags*
489 A tags file can be created with an external command, for example "ctags". It
490 will contain a tag for each function. Some versions of "ctags" will also make
491 a tag for each "#defined" macro, typedefs, enums, etc.
493 Some programs that generate tags files:
494 ctags As found on most Unix systems. Only supports C. Only
495 does the basic work.
496 *Exuberant_ctags*
497 exuberant 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.
500 etags Connected to Emacs. Supports many languages.
501 JTags For Java, in Java. It can be found at
502 http://www.fleiner.com/jtags/.
503 ptags.py For Python, in Python. Found in your Python source
504 directory at Tools/scripts/ptags.py.
505 ptags For Perl, in Perl. It can be found at
506 http://www.eleves.ens.fr:8080/home/nthiery/Tags/.
507 gnatxref For Ada. See http://www.gnuada.org/. gnatxref is
508 part of the gnat package.
511 The lines in the tags file must have one of these three formats:
513 1. {tagname} {TAB} {tagfile} {TAB} {tagaddress}
514 2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
515 3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
517 The first is a normal tag, which is completely compatible with Vi. It is the
518 only format produced by traditional ctags implementations. This is often used
519 for functions that are global, also referenced in other files.
521 The lines in the tags file can end in <LF> or <CR><LF>. On the Macintosh <CR>
522 also works. The <CR> and <NL> characters can never appear inside a line.
524 *tag-old-static*
525 The second format is for a static tag only. It is obsolete now, replaced by
526 the third format. It is only supported by Elvis 1.x and Vim and a few
527 versions of ctags. A static tag is often used for functions that are local,
528 only referenced in the file {tagfile}. Note that for the static tag, the two
529 occurrences of {tagfile} must be exactly the same. Also see |tags-option|
530 below, for how static tags are used.
532 The third format is new. It includes additional information in optional
533 fields at the end of each line. It is backwards compatible with Vi. It is
534 only supported by new versions of ctags (such as Exuberant ctags).
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:
556 <Tab>{fieldname}:{value}
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
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.
571 The only other field currently recognized by Vim is "file:"
572 (with an empty value). It is used for a static tag.
574 The first lines in the tags file can contain lines that start with
575 !_TAG_
576 These are sorted to the first lines, only rare tags that start with "!" can
577 sort to before them. Vim recognizes two items. The first one is the line
578 that indicates if the file was sorted. When this line is found, Vim uses
579 binary searching for the tags file:
580 !_TAG_FILE_SORTED<Tab>1<Tab>{anything} ~
582 A tag file may be case-fold sorted to avoid a linear search when 'ignorecase'
583 is on. See 'tagbsearch' for details. The value '2' should be used then:
584 !_TAG_FILE_SORTED<Tab>2<Tab>{anything} ~
586 The 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} ~
589 Here "utf-8" is the encoding used for the tags. Vim will then convert the tag
590 being searched for from 'encoding' to the encoding of the tags file. And when
591 listing tags the reverse happens. When the conversion fails the unconverted
592 tag is used.
594 *tag-search*
595 The command can be any Ex command, but often it is a search command.
596 Examples:
597 tag1 file1 /^main(argc, argv)/ ~
598 tag2 file2 108 ~
600 The command is always executed with 'magic' not set. The only special
601 characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
602 See |pattern|. Note that you must put a backslash before each backslash in
603 the search text. This is for backwards compatibility with Vi.
605 *E434* *E435*
606 If 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}
626 ==============================================================================
627 6. Include file searches *include-search* *definition-search*
628 *E387* *E388* *E389*
630 These commands look for a string in the current file and in all encountered
631 included files (recursively). This can be used to find the definition of a
632 variable, function or macro. If you only want to search in the current
633 buffer, use the commands listed at |pattern-searches|.
635 These commands are not available when the |+find_in_path| feature was disabled
636 at compile time.
638 When a line is encountered that includes another file, that file is searched
639 before continuing in the current buffer. Files included by included files are
640 also searched. When an include file could not be found it is silently
641 ignored. Use the |:checkpath| command to discover which files could not be
642 found, possibly your 'path' option is not set up correctly. Note: the
643 included file is searched, not a buffer that may be editing that file. Only
644 for the current file the lines in the buffer are used.
646 The string can be any keyword or a defined macro. For the keyword any match
647 will be found. For defined macros only lines that match with the 'define'
648 option will be found. The default is "^#\s*define", which is for C programs.
649 For other languages you probably want to change this. See 'define' for an
650 example for C++. The string cannot contain an end-of-line, only matches
651 within a line are found.
653 When a match is found for a defined macro, the displaying of lines continues
654 with the next line when a line ends in a backslash.
656 The commands that start with "[" start searching from the start of the current
657 file. The commands that start with "]" start at the current cursor position.
659 The 'include' option is used to define a line that includes another file. The
660 default is "\^#\s*include", which is for C programs. Note: Vim does not
661 recognize C syntax, if the 'include' option matches a line inside
662 "#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname'
663 option is used to recognize the file name that comes after the matched
664 pattern.
666 The 'path' option is used to find the directory for the include files that
667 do not have an absolute path.
669 The 'comments' option is used for the commands that display a single line or
670 jump to a line. It defines patterns that may start a comment. Those lines
671 are ignored for the search, unless [!] is used. One exception: When the line
672 matches the pattern "^# *define" it is not considered to be a comment.
674 If you want to list matches, and then select one to jump to, you could use a
675 mapping to do that for you. Here is an example: >
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}
687 *]i*
688 ]i like "[i", but start at the current cursor position.
689 {not in Vi}
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}
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}
703 *]I*
704 ]I like "[I", but start at the current cursor position.
705 {not in Vi}
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}
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}
721 *]_CTRL-I*
722 ] CTRL-I like "[ CTRL-I", but start at the current cursor
723 position. {not in Vi}
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}
731 CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i*
732 CTRL-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}
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}
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}
752 *]d*
753 ]d like "[d", but start at the current cursor position.
754 {not in Vi}
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}
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}
768 *]D*
769 ]D like "[D", but start at the current cursor position.
770 {not in Vi}
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.
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}
786 *]_CTRL-D*
787 ] CTRL-D like "[ CTRL-D", but start at the current cursor
788 position. {not in Vi}
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}
796 CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d*
797 CTRL-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}
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}
809 *:che* *:checkpath*
810 :che[ckpath] List all the included files that could not be found.
811 {not in Vi}
813 :che[ckpath]! List all the included files. {not in Vi}
815 *:search-args*
816 Common 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.
837 vim:tw=78:ts=8:ft=help:norl: