1 *tagsearch.txt* For Vim version 5.8. Last change: 2001 May 10
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Tags and special searches *tags-and-searches*
9 1. Jump to a tag |tag-commands|
10 2. Tag stack |tag-stack|
11 3. Tag match list |tag-matchlist|
12 4. Tags details |tag-details|
13 5. Tags file format |tags-file-format|
14 6. Include file searches |include-search|
15 7. 'Grep' and 'Lid' |grep|
17 ==============================================================================
18 1. Jump to a tag *tag-commands* *tag*
21 A tag is an identifier that appears in a "tags" file. It is a sort of label
22 that can be jumped to. For example: In C programs each function name can be
23 used as a tag. The "tags" file has to be generated by a program like ctags,
24 before the tag commands can be used.
26 With the ":tag" command the cursor will be positioned on the tag. With the
27 CTRL-] command, the keyword on which the cursor is standing is used as the
28 tag. If the cursor is not on a keyword, the first keyword to the right of the
31 The ":tag" command works very well for C programs. If you see a call to a
32 function and wonder what that function does, position the cursor inside of the
33 function name and hit CTRL-]. This will bring you to the function definition.
34 An easy way back is with the CTRL-T command. Also read about the tag stack
38 :ta[g][!] {ident} Jump to the definition of {ident}, using the
39 information in the tags file(s). Put {ident} in the
40 tag stack. See |tag-!| for [!].
41 {ident} can be a regexp pattern, see |tag-regexp|.
42 When there are several matching tags for {ident}, the
43 first one is jumped to. |:tnext|.
45 g<LeftMouse> *g<LeftMouse>*
46 <C-LeftMouse> *<C-LeftMouse>* *CTRL-]*
47 CTRL-] Same as ":tag {ident}", where {ident} is the keyword
48 under or after cursor. {Vi: identifier after the
52 {Visual}CTRL-] Same as ":tag {ident}", where {ident} is the text that
53 is highlighted. {not in Vi}
56 CTRL-] is the default telnet escape key. When you type CTRL-] to jump to a
57 tag, you will get the telnet prompt instead. Most versions of telnet allow
58 changing or disabling the default escape key. See the telnet man page. You
59 can 'telnet -E {Hostname}' to disable the escape character, or 'telnet -e
60 {EscapeCharacter} {Hostname}' to specify another escape character. If
61 possible, try to use "rsh" instead of "telnet" to avoid this problem.
64 When there are multiple matches for a tag, this priority is used:
65 1. "FSC" A full matching static tag for the current file.
66 2. "F C" A full matching global tag for the current file.
67 3. "F " A full matching global tag for another file.
68 4. "FS " A full matching static tag for another file.
69 5. " SC" An ignore-case matching static tag for the current file.
70 6. " C" An ignore-case matching global tag for the current file.
71 7. " " An ignore-case matching global tag for another file.
72 8. " S " An ignore-case matching static tag for another file.
74 Note that when the current file changes, the priority list is mostly not
75 changed, to avoid confusion when using ":tnext". It is changed when using
78 The ignore-case matches are not found for a ":tag" command when the
79 'ignorecase' option is off. They are found when a pattern is used (starting
80 with a "/") and for ":tselect", also when 'ignorecase' is off. Note that
81 using ignore-case tag searching disables binary searching in the tags file,
82 which causes a slowdown.
84 ==============================================================================
85 2. Tag stack *tag-stack* *tagstack*
87 On the tag stack is remembered which tags you jumped to, and from where.
88 Tags are only pushed onto the stack when the 'tagstack' option is set.
90 g<RightMouse> *g<RightMouse>*
91 <C-RightMouse> *<C-RightMouse>* *CTRL-T*
92 CTRL-T Jump to [count] older entry in the tag stack
93 (default 1). {not in Vi}
96 :[count]po[p][!] Jump to [count] older entry in tag stack (default 1).
97 See |tag-!| for [!]. {not in Vi}
99 :[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1).
100 See |tag-!| for [!]. {not in Vi}
103 :tags Show the contents of the tag stack. The active
104 entry is marked with a '>'. {not in Vi}
106 The output of ":tags" looks like this:
108 # TO tag FROM line in file/line
109 1 1 main 1 harddisk2:text/vim/test
110 > 2 2 FuncA 58 i = FuncA(10);
111 3 1 FuncC 357 harddisk2:text/vim/src/amiga.c
113 This list shows the tags that you jumped to and the cursor position before
114 that jump. The older tags are at the top, the newer at the bottom.
116 The '>' points to the active entry. This is the tag that will be used by the
117 next ":tag" command. The CTRL-T and ":pop" command will use the position
118 above the active entry.
120 Below the "TO" is the number of the current match in the match list. Note
121 that this doesn't change when using ":pop" or ":tag".
123 The line number and file name are remembered to be able to get back to where
124 you were before the tag command. The line number will be correct, also when
125 deleting/inserting lines, unless this was done by another program (e.g.
126 another instance of Vim).
128 For the current file, the "file/line" column shows the text at the position.
129 An indent is removed and a long line is truncated to fit in the window.
131 You can jump to previously used tags with several commands. Some examples:
133 ":pop" or CTRL-T to position before previous tag
134 {count}CTRL-T to position before {count} older tag
136 ":0tag" to last used tag
138 The most obvious way to use this is while browsing through the call graph of
139 a program. Consider the following call graph:
141 main ---> FuncA ---> FuncC
144 (Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
145 You can get from main to FuncA by using CTRL-] on the call to FuncA. Then
146 you can CTRL-] to get to FuncC. If you now want to go back to main you can
147 use CTRL-T twice. Then you can CTRL-] to FuncB.
149 If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the
150 current position in the stack. If the stack was full (it can hold up to 20
151 entries), the oldest entry is deleted and the older entries shift one
152 position up (their index number is decremented by one). If the last used
153 entry was not at the bottom, the entries below the last used one are
154 deleted. This means that an old branch in the call graph is lost. After the
155 commands explained above the tag stack will look like this:
157 # TO tag FROM line in file
158 1 main 1 harddisk2:text/vim/test
159 2 FuncB 59 harddisk2:text/vim/src/main.c
162 ==============================================================================
163 3. Tag match list *tag-matchlist*
165 When there are several matching tags, these commands can be used to jump
166 between them. Note that these command don't change the tag stack, they keep
170 :ts[elect][!] [ident] List the tags that match [ident], using the
171 information in the tags file(s).
172 When [ident] is not given, the last tag name from the
174 With a '>' in the first column is indicated which is
175 the current position in the list (if there is one).
176 [ident] can be a regexp pattern, see |tag-regexp|.
177 See |tag-priority| for the priorities used in the
181 nr pri kind tag file ~
182 > 1 F f mch_delay os_amiga.c
183 > mch_delay(msec, ignoreinput)
184 > > 2 F f mch_delay os_msdos.c
185 > mch_delay(msec, ignoreinput)
186 > 3 F f mch_delay os_unix.c
187 > mch_delay(msec, ignoreinput)
188 > Enter nr of choice (<CR> to abort):
190 See |tag-priority| for the "pri" column. Note that
191 this depends on the current file, thus using
192 ":tselect xxx" can produce different results.
193 The "kind" column gives the kind of tag, if this was
194 included in the tags file.
195 The "info" column shows information that could be
196 found in the tags file. It depends on the program
197 that produced the tags file.
198 When the list is long, you may get the |more-prompt|.
199 If you already see the tag you want to use, you can
200 type 'q' and enter the number.
203 :sts[elect][!] [ident] Does ":tselect[!] [ident]" and splits the window for
204 the selected tag. {not in Vi}
207 g] Like CTRL-], but use ":tselect" instead of ":tag".
211 :tj[ump][!] [ident] Like ":tselect", but jump to the tag directly when
212 there is only one match. {not in Vi}
215 :stj[ump][!] [ident] Does ":tjump[!] [ident]" and splits the window for the
216 selected tag. {not in Vi}
219 g CTRL-] Like CTRL-], but use ":tjump" instead of ":tag".
223 :[count]tn[ext][!] Jump to [count] next matching tag (default 1). See
224 |tag-!| for [!]. {not in Vi}
227 :[count]tp[revious][!] Jump to [count] previous matching tag (default 1).
228 See |tag-!| for [!]. {not in Vi}
231 :[count]tN[ext][!] Same as ":tprevious". {not in Vi}
234 :[count]tr[ewind][!] Jump to first matching tag. If [count] is given, jump
235 to [count]th matching tag. See |tag-!| for [!]. {not
239 :tl[ast][!] Jump to last matching tag. See |tag-!| for [!]. {not
243 When there is no other message, Vim shows which matching tag has been jumped
244 to, and the number of matching tags:
246 The " or more" is used to indicate that Vim didn't try all the tags files yet.
247 When using ":tnext" a few times, or with ":tlast", more matches may be found.
249 When you didn't see this message because of some other message, or you just
250 want to know where you are, this command will show it again (and jump to the
251 same tag as last time):
255 When a matching tag is found for which the file doesn't exist, this match is
256 skipped and the next matching tag is used. Vim reports this, to notify you of
257 missing files. When the end of the list of matches has been reached, an error
260 The tag match list can also be used in the preview window. The commands are
261 the same as above, with a "p" prepended.
264 :pts[elect][!] [ident] Does ":tselect[!] [ident]" and shows the new tag in a
265 "Preview" window. See |:ptag| for more info.
269 :ptj[ump][!] [ident] Does ":tjump[!] [ident]" and shows the new tag in a
270 "Preview" window. See |:ptag| for more info.
274 :[count]ptn[ext][!] ":tnext" in the preview window. See |:ptag|.
278 :[count]ptp[revious][!] ":tprevious" in the preview window. See |:ptag|.
282 :[count]ptN[ext][!] Same as ":ptprevious". {not in Vi}
285 :[count]ptr[ewind][!] ":trewind" in the preview window. See |:ptag|.
289 :ptl[ast][!] ":tlast" in the preview window. See |:ptag|.
292 ==============================================================================
293 4. Tags details *tag-details*
296 A static tag is a tag that is defined for a specific file. In a C program
297 this could be a static function.
299 In Vi jumping to a tag sets the current search pattern. This means that
300 the "n" command after jumping to a tag does not search for the same pattern
301 that it did before jumping to the tag. Vim does not do this as we consider it
302 to be a bug. You can still find the tag search pattern in the search history.
303 If you really want the old Vi behaviour, set the 't' flag in 'cpoptions'.
306 Vim uses binary searching in the tags file to find the desired tag quickly
307 (when enabled at compile time |+tag_binary|). But this only works if the
308 tags file was sorted on ASCII byte value. Therefore, if no match was found,
309 another try is done with a linear search. If you only want the linear search,
310 reset the 'tagbsearch' option. Or better: Sort the tags file!
312 Note that the binary searching is disabled when not looking for a tag with a
313 specific name. This happens when ignoring case and when a regular expression
314 is used that doesn't start with a fixed string. Tag searching can be a lot
318 The ":tag" and "tselect" commands accept a regular expression argument. See
319 |pattern| for the special characters that can be used.
320 When the argument starts with '/', it is used as a pattern. If the argument
321 does not start with '/', it is taken literally, as a full tag name.
324 jumps to the tag "main" that has the highest priority.
326 jumps to the tag that starts with "get" and has the highest priority.
328 lists all the tags that contain "norm", including "id_norm".
329 When the argument both exists literally, and match when used as a regexp, a
330 literal match has a higher priority. For example, ":tag /open" matches "open"
331 before "open_file" and "file_open".
334 If the tag is in the current file this will always work. Otherwise the
335 performed actions depend on whether the current file was changed, whether a !
336 is added to the command and on the 'autowrite' option:
338 tag in file autowrite ~
339 current file changed ! option action ~
340 -----------------------------------------------------------------------------
342 no no x x read other file, goto tag
343 no yes yes x abandon current file, read other file, goto
345 no yes no on write current file, read other file, goto
348 -----------------------------------------------------------------------------
350 - If the tag is in the current file, the command will always work.
351 - If the tag is in another file and the current file was not changed, the
352 other file will be made the current file and read into the buffer.
353 - If the tag is in another file, the current file was changed and a ! is
354 added to the command, the changes to the current file are lost, the other
355 file will be made the current file and read into the buffer.
356 - If the tag is in another file, the current file was changed and the
357 'autowrite' option is on, the current file will be written, the other
358 file will be made the current file and read into the buffer.
359 - If the tag is in another file, the current file was changed and the
360 'autowrite' option is off, the command will fail. If you want to save
361 the changes, use the ":w" command and then use ":tag" without an argument.
362 This works because the tag is put on the stack anyway. If you want to lose
363 the changes you can use the ":tag!" command.
366 Note that Vim forbids some commands, for security reasons. This works like
367 using the 'secure' option for exrc/vimrc files in the current directory. See
369 When the {tagaddress} changes a buffer, you will get a warning message:
370 "WARNING: tag command changed a buffer!!!"
371 In a future version changing the buffer will be impossible. All this for
372 security reasons: Somebody might hide a nasty command in the tags file, which
373 would otherwise go unnoticed. Example:
374 > :$d|/tag-function-name/
375 {this security prevention is not present in Vi}.
377 In Vi the ":tag" command sets the last search pattern when the tag is searched
378 for. In Vim this is not done, the previous search pattern is still remembered,
379 unless the 't' flag is present in 'cpoptions'. The search pattern is always
380 put in the search history, so you can modify it if searching fails.
382 *emacs-tags* *emacs_tags*
383 Emacs style tag files are only supported if Vim was compiled with the
384 |+emacs_tags| feature enabled. Sorry, there is no explanation about Emacs tag
385 files here, it is only supported for backwards compatibility :-).
388 The 'tags' option is a list of file names. Each of these files is searched
389 for the tag. This can be used to use a different tags file than the default
390 file "tags". It can also be used to access a common tags file.
392 The next file in the list is not used when:
393 - A matching static tag for the current buffer has been found.
394 - A matching global tag has been found.
395 This also depends on the 'ignorecase' option. If it is off, and the tags file
396 only has a match without matching case, the next tags file is searched for a
397 match with matching case. If no tag with matching case is found, the first
398 match without matching case is used. If 'ignorecase' is on, and a matching
399 global tag with or without matching case is found, this one is used, no
400 further tags files are searched.
402 When a tag file name starts with "./", the '.' is replaced with the path of
403 the current file. This makes it possible to use a tags file in the directory
404 where the current file is (no matter what the current directory is). The idea
405 of using "./" is that you can define which tag file is searched first: In the
406 current directory ("tags,./tags") or in the directory of the current file
410 > :set tags=./tags,tags,/home/user/commontags
412 In this example the tag will first be searched for in the file "tags" in the
413 directory where the current file is. Next the "tags" file in the current
414 directory. If it is not found there, then the file "/home/user/commontags"
415 will be searched for the tag.
417 This can be switched off by including the 'd' flag in 'cpoptions', to make
418 it Vi compatible. "./tags" will than be the tags file in the current
419 directory, instead of the tags file in the directory where the current file
422 Instead of the comma a space may be used. Then a backslash is required for
423 the space to be included in the string option:
424 > :set tags=tags\ /home/user/commontags
426 To include a space in a file name use three backslashes. To include a comma
427 in a file name use two backslashes. For example, use:
428 > :set tags=tag\\\ file,/home/user/common\\,tags
430 for the files "tag file" and "/home/user/common,tags". The 'tags' option will
431 have the value "tag\ file,/home/user/common\,tags".
433 If the 'tagrelative' option is on (which is the default) and using a tag file
434 in another directory, file names in that tag file are relative to the
435 directory where the tag file is.
437 ==============================================================================
438 5. Tags file format *tags-file-format*
441 A tags file can be created with an external command, for example "ctags". It
442 will contain a tag for each function. Some versions of "ctags" will also make
443 a tag for each "#defined" macro, typedefs, enums, etc.
445 Some programs that generate tags files:
446 ctags As found on most Unix systems. Only supports C. Only
448 exuberant ctags Found at http://ctags.sf.net. This a very good one.
449 It works for C, C++, Java, Fortran and other
450 languages. It can generate tags for many items.
451 etags Connected to Emacs. Supports many languages.
452 JTags For Java, in Java. It can be found at
453 http://www.fleiner.com/jtags/.
454 ptags.py For Python, in Python. Found in your Python source
455 directory at Tools/scripts/ptags.py.
457 The lines in the tags file must have one of these three formats:
459 1. {tagname} {TAB} {tagfile} {TAB} {tagaddress}
460 2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
461 3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
463 The first is a normal tag, which is completely compatible with Vi. It is the
464 only format produced by traditional ctags implementations. This is often used
465 for functions that are global, also referenced in other files.
467 The lines in the tags file can end in <LF> or <CR><LF>. On the Macintosh <CR>
468 probably also works (this depends on the fgets() function). The <CR> and <NL>
469 characters can never appear inside a line.
472 The second format is for a static tag only. It is obsolete now, replaced by
473 the third format. It is only supported by Elvis 1.x and Vim and a few
474 versions of ctags. A static tag is often used for functions that are local,
475 only referenced in the file {tagfile}. Note that for the static tag, the two
476 occurrences of {tagfile} must be exactly the same. Also see |tags-option|
477 below, for how static tags are used.
479 The third format is new. It includes additional information in optional
480 fields at the end of each line. It is backwards compatible with Vi. It is
481 only supported by new versions of ctags (like Exuberant ctags).
483 {tagname} The identifier. Normally the name of a function, but it can
484 be any identifier. It cannot contain a <Tab>.
485 {TAB} One <Tab> character. Note: previous versions allowed any
486 white space here. This has been abandoned to allow spaces in
487 {tagfile}. It can be re-enabled by including the
488 |+tag_any_white| feature at compile time. *tag-any-white*
489 {tagfile} The file that contains the definition of {tagname}. It can
490 have an absolute or relative path. It may contain environment
491 variables and wildcards (although the use of wildcards is
492 doubtful). It cannot contain a <Tab>.
493 {tagaddress} The Ex command that positions the cursor on the tag. It can
494 be any Ex command, although restrictions apply (see
495 |tag-security|). Posix only allows line numbers and search
496 commands, which are mostly used.
497 {term} ;" The two characters semicolon and double quote. This is
498 interpreted by Vi as the start of a comment, which makes the
499 following be ignored. This is only for backwards
500 compatibility with Vi.
501 {field} .. A list of optional fields. Each field has the form:
503 <Tab>{fieldname}:{value}
505 The {fieldname} identifies the field, and can only contain
506 alphabetical characters [a-zA-Z].
507 The {value} is any string, but cannot contain a <Tab>.
508 These characters are special:
509 "\t" stands for a <Tab>
510 "\r" stands for a <CR>
511 "\n" stands for a <NL>
512 "\\" stands for a single '\' character
514 There is one field that doesn't have a ':'. This is the kind
515 of the tag. It is handled like it was preceded with "kind:".
516 See the documentation of ctags for the kinds it produces.
518 The only other field currently recognized by Vim is "file:"
519 (with an empty value). It is used for a static tag.
521 The first lines in the tags file can contain lines that start with
523 These are sorted to the first lines, only rare tags that start with "!" can
524 sort to before them. Vim only recognizes the line that indicates if the file
525 was sorted. When this line is found, Vim uses binary searching for the tags
527 > !_TAG_FILE_SORTED<Tab>1
530 The command can be any Ex command, but often it is a search command.
532 > tag1 file1 /^main(argc, argv)/
535 The command is always executed with 'magic' not set. The only special
536 characters in a search pattern are "^" (begin-of-line) and "$" (<EOL>).
537 See |pattern|. Note that you must put a backslash before each backslash in
538 the search text. This is for backwards compatibility with Vi.
540 If the command is a normal search command (it starts and ends with "/" or
541 "?"), some special handling is done:
542 - Searching starts on line 1 of the file.
543 The direction of the search is forward for "/", backward for "?".
544 Note that 'wrapscan' does not matter, the whole file is always searched. {Vi
545 does use 'wrapscan', which caused tags sometimes not be found). {Vi starts
546 searching in line 2 of another file. It does not find a tag in line 1 of
547 another file when 'wrapscan' is not set}
548 - If the search fails, another try is done ignoring case. If that fails too,
549 a search is done for:
551 (the tag with '^' prepended and "[ \t]*(" appended). When using function
552 names, this will find the function name when it is in column 0. This will
553 help when the arguments to the function have changed since the tags file was
554 made. If this search also fails another search is done with:
555 "^[#a-zA-Z_].*\<tagname[ \t]*("
556 This means: A line starting with '#' or an identifier and containing the tag
557 followed by white space and a '('. This will find macro names and function
558 names with a type prepended. {the extra searches are not in Vi}.
560 ==============================================================================
561 6. Include file searches *include-search* *definition-search*
563 These commands look for a string in the current file and in all encountered
564 included files (recursively). This can be used to find the definition of a
565 variable, function or macro. If you only want to search in the current
566 buffer, use the commands listed at |pattern-searches|.
568 These commands are not available when the |+find_in_path| feature was disabled
571 When a line is encountered that includes another file, that file is searched
572 before continuing in the current buffer. Files included by included files are
573 also searched. When an include file could not be found it is silently
574 ignored. Use the ":checkpath" command to discover which files could not be
575 found, possibly your 'path' option is not set up correctly. Note: the
576 included file is searched, not a buffer that may be editing that file. Only
577 for the current file the lines in the buffer are used.
579 The string can be any keyword or a defined macro. For the keyword any match
580 will be found. For defined macros only lines that match with the 'define'
581 option will be found. The default is "^#\s*define", which is for C programs.
582 For other languages you probably want to change this. See 'define' for an
585 When a match is found for a defined macro, the displaying of lines continues
586 with the next line when a line ends in a backslash.
588 The commands that start with "[" start searching from the start of the current
589 file. The commands that start with "]" start at the current cursor position.
591 The 'include' option is used to define a line that includes another file. The
592 default is "\^#\s*include", which is for C programs. Note: Vim does not
593 recognize C syntax, if the 'include' option matches a line inside
594 "#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname'
595 option is used to recognize the file name that comes after the matched
598 The 'path' option is used to find the directory for the include files that
599 do not have an absolute path.
601 The 'comments' option is used for the commands that display a single line or
602 jump to a line. It defines patterns that may start a comment. Those lines
603 are ignored for the search, unless [!] is used. One exception: When the line
604 matches the pattern "^# *define" it is not considered to be a comment.
606 If you want to list matches, and then select one to jump to, you could use a
607 mapping to do that for you. Here is an example:
609 > :map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR>
612 [i Display the first line that contains the keyword
613 under the cursor. The search starts at the beginning
614 of the file. Lines that look like a comment are
615 ignored (see 'comments' option). If a count is given,
616 the count'th matching line is displayed, and comment
617 lines are not ignored. {not in Vi}
620 ]i like "[i", but start at the current cursor position.
624 :[range]is[earch][!] [count] [/]pattern[/]
625 Like "[i" and "]i", but search in [range] lines
626 (default: whole file).
627 See |:search-args| for [/] and [!]. {not in Vi}
630 [I Display all lines that contain the keyword under the
631 cursor. Filenames and line numbers are displayed
632 for the found lines. The search starts at the
633 beginning of the file. {not in Vi}
636 ]I like "[I", but start at the current cursor position.
640 :[range]il[ist][!] [/]pattern[/]
641 Like "[I" and "]I", but search in [range] lines
642 (default: whole file).
643 See |:search-args| for [/] and [!]. {not in Vi}
646 [ CTRL-I Jump to the first line that contains the keyword
647 under the cursor. The search starts at the beginning
648 of the file. Lines that look like a comment are
649 ignored (see 'comments' option). If a count is given,
650 the count'th matching line is jumped to, and comment
651 lines are not ignored. {not in Vi}
654 ] CTRL-I like "[ CTRL-I", but start at the current cursor
655 position. {not in Vi}
658 :[range]ij[ump][!] [count] [/]pattern[/]
659 Like "[ CTRL-I" and "] CTRL-I", but search in
660 [range] lines (default: whole file).
661 See |:search-args| for [/] and [!]. {not in Vi}
663 CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i*
664 CTRL-W i Open a new window, with the cursor on the first line
665 that contains the keyword under the cursor. The
666 search starts at the beginning of the file. Lines
667 that look like a comment line are ignored (see
668 'comments' option). If a count is given, the count'th
669 matching line is jumped to, and comment lines are not
673 :[range]isp[lit][!] [count] [/]pattern[/]
674 Like "CTRL-W i" and "CTRL-W i", but search in
675 [range] lines (default: whole file).
676 See |:search-args| for [/] and [!]. {not in Vi}
679 [d Display the first macro definition that contains the
680 macro under the cursor. The search starts from the
681 beginning of the file. If a count is given, the
682 count'th matching line is displayed. {not in Vi}
685 ]d like "[d", but start at the current cursor position.
689 :[range]ds[earch][!] [count] [/]pattern[/]
690 Like "[d" and "]d", but search in [range] lines
691 (default: whole file).
692 See |:search-args| for [/] and [!]. {not in Vi}
695 [D Display all macro definitions that contain the macro
696 under the cursor. Filenames and line numbers are
697 displayed for the found lines. The search starts
698 from the beginning of the file. {not in Vi}
701 ]D like "[D", but start at the current cursor position.
705 :[range]dl[ist][!] [/]pattern[/]
706 Like "[D" and "]D", but search in [range] lines
707 (default: whole file).
708 See |:search-args| for [/] and [!]. {not in Vi}
711 [ CTRL-D Jump to the first macro definition that contains the
712 keyword under the cursor. The search starts from
713 the beginning of the file. If a count is given, the
714 count'th matching line is jumped to. {not in Vi}
717 ] CTRL-D like "[ CTRL-D", but start at the current cursor
718 position. {not in Vi}
721 :[range]dj[ump][!] [count] [/]pattern[/]
722 Like "[ CTRL-D" and "] CTRL-D", but search in
723 [range] lines (default: whole file).
724 See |:search-args| for [/] and [!]. {not in Vi}
726 CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d*
727 CTRL-W d Open a new window, with the cursor on the first
728 macro definition line that contains the keyword
729 under the cursor. The search starts from the
730 beginning of the file. If a count is given, the
731 count'th matching line is jumped to. {not in Vi}
734 :[range]dsp[lit][!] [count] [/]pattern[/]
735 Like "CTRL-W d", but search in [range] lines
736 (default: whole file).
737 See |:search-args| for [/] and [!]. {not in Vi}
740 :che[ckpath] List all the included files that could not be found.
743 :che[ckpath]! List all the included files. {not in Vi}
746 Common arguments for the commands above:
747 [!] When included, find matches in lines that are recognized as comments.
748 When excluded, a match is ignored when the line is recognized as a
749 comment (according to 'comments'), or the match is in a C comment (after
750 "//" or inside /* */). Note that a match may be missed if a line is
751 recognized as a comment, but the comment ends halfway the line.
752 And if the line is a comment, but it is not recognized (according to
753 'comments') a match may be found in it anyway. Example:
756 A match for "foobar" is found, because this line is not recognized as a
757 comment (even though syntax highlighting does recognize it).
758 Note: Since a macro definition mostly doesn't look like a comment, the
759 [!] makes no difference for ":dlist", ":dsearch" and ":djump".
760 [/] A pattern can be surrounded by '/'. Without '/' only whole words are
761 matched, using the pattern "\<pattern\>". Only after the second '/' a
762 next command can be appended with '|'. Examples:
763 > :isearch /string/ | echo "the last one"
765 ==============================================================================
766 7. 'Grep' and 'Lid' *grep* *lid*
768 Vim can interface with "grep" and grep-like programs (such as the GNU
769 id-utils) in a similar way to its compiler integration. (see |:make| for more
770 information on that.)
773 If you have a standard "grep" program installed, the :grep command may well
774 work first time with the defaults. The syntax is very similar to the standard
779 Will search all files with the .c extension for the substring "foo". The
780 arguments to :grep are passed straight to the "grep" program, so you can use
781 whatever options your "grep" supports.
783 By default, :grep invokes grep with the -n option (show file and line
784 numbers). You can change this with the 'grepprg' option. You will need to set
787 a) You are using a program that isn't called "grep"
788 b) You have to call grep with a full path
789 c) You want to pass other options automatically (e.g. case insensitive
792 Once "grep" has executed, Vim parses the results using the 'grepformat'
793 option. This option works in the same way as the 'errorformat' option - see
794 that for details. You may need to change 'grepformat' from the default if your
795 grep outputs in a non-standard format, or you are using some other program
796 with a special format.
798 Once the results are parsed, Vim loads the first file containing a match and
799 jumps to the appropriate line, in the same way that it jumps to a compiler
800 error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc.
801 commands to see the other matches.
803 7.2 Using :grep with id-utils
804 You can set up :grep to work with the GNU id-utils like this:
806 > set grepprg=lid\ -Rgrep\ -s
807 > set grepformat=%f:%l:%m
812 works just as you'd expect.
813 (provided you remembered to mkid first :)