Tagsrch
Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.
Tags and special searches
See section
29.1 of the user manual for an introduction.
tagtagsA tag is an identifier that appears in a "tags" file. It is a sort of labelthat can be jumped to. For example: In C programs each function name can beused as a tag. The "tags" file has to be generated by a program like ctags,before the tag commands can be used.
With the ":tag" command the cursor will be positioned on the tag. With theCTRL-] command, the keyword on which the cursor is standing is used as thetag. If the cursor is not on a keyword, the first keyword to the right of thecursor is used.
The ":tag" command works very well for C programs. If you see a call to afunction and wonder what that function does, position the cursor inside of thefunction name and hitCTRL-]. This will bring you to the function definition.An easy way back is with theCTRL-T command. Also read about the tag stackbelow.
:ta:tagE426E429:[count]ta[g][!]
{name}Jump to the definition of
{name}, using theinformation in the tags file(s). Put
{name} in thetag stack. See
tag-! for [!].
{name} can be a regexp pattern, see
tag-regexp.When there are several matching tags for
{name}, jumpto the [count] one. When [count] is omitted thefirst one is jumped to. See
tag-matchlist forjumping to other matching tags.
g<LeftMouse>
g<LeftMouse><C-LeftMouse><C-LeftMouse>CTRL-]CTRL-]Jump to the definition of the keyword under thecursor. Same as ":tag
{name}", where
{name} is thekeyword under or after cursor.When there are several matching tags for
{name}, jumpto the [count] one. When no [count] is given thefirst one is jumped to. See
tag-matchlist forjumping to other matching tags.
v_CTRL-]{Visual}CTRL-]Same as ":tag
{name}", where
{name} is the text thatis highlighted.
telnet-CTRL-]CTRL-] is the default telnet escape key. When you type
CTRL-] to jump to atag, you will get the telnet prompt instead. Most versions of telnet allowchanging or disabling the default escape key. See the telnet man page. Youcan
telnet -E {Hostname} to disable the escape character, or
telnet -e {EscapeCharacter} {Hostname} to specify another escape character.If possible, try to use "ssh" instead of "telnet" to avoid this problem.
tag-priorityWhen there are multiple matches for a tag, this priority is used:1. "FSC" A full matching static tag for the current file.2. "F C" A full matching global tag for the current file.3. "F " A full matching global tag for another file.4. "FS " A full matching static tag for another file.5. " SC" An ignore-case matching static tag for the current file.6. " C" An ignore-case matching global tag for the current file.7. " " An ignore-case matching global tag for another file.8. " S " An ignore-case matching static tag for another file.
Note that when the current file changes, the priority list is mostly notchanged, to avoid confusion when using ":tnext". It is changed when using":tag{name}".
The ignore-case matches are not found for a ":tag" command when:
'tagcase' is "smart" and the pattern contains an upper case character.
The ignore-case matches are found when:
a pattern is used (starting with a "/")
for ":tselect"
when
'tagcase' is "smart" and the pattern does not contain an upper case character
Note that using ignore-case tag searching disables binary searching in thetags file, which causes a slowdown. This can be avoided by fold-case sortingthe tag file. See the
'tagbsearch' option for an explanation.
On the tag stack is remembered which tags you jumped to, and from where.Tags are only pushed onto the stack when the
'tagstack' option is set.
:po:popE555E556:[count]po[p][!]Jump to [count] older entry in tag stack (default 1).See
tag-! for [!].
:[count]ta[g][!]Jump to [count] newer entry in tag stack (default 1).See
tag-! for [!].
:tags:tagsShow the contents of the tag stack. The activeentry is marked with a '>'.
The output of ":tags" looks like this:
# TO tag FROM line in file/text 1 1 main 1 harddisk2:text/vim/test > 2 2 FuncA58 i = FuncA(10); 3 1 FuncC 357 harddisk2:text/vim/src/amiga.c
This list shows the tags that you jumped to and the cursor position beforethat jump. The older tags are at the top, the newer at the bottom.
The '>' points to the active entry. This is the tag that will be used by thenext ":tag" command. TheCTRL-T and ":pop" command will use the positionabove the active entry.
Below the "TO" is the number of the current match in the match list. Notethat this doesn't change when using ":pop" or ":tag".
The line number and file name are remembered to be able to get back to whereyou were before the tag command. The line number will be correct, also whendeleting/inserting lines, unless this was done by another program (e.g.another instance of Vim).
For the current file, the "file/text" column shows the text at the position.An indent is removed and a long line is truncated to fit in the window.
You can jump to previously used tags with several commands. Some examples:
":pop" orCTRL-Tto position before previous tag{count}CTRL-Tto position before{count} older tag":tag"to newer tag":0tag"to last used tag
The most obvious way to use this is while browsing through the call graph ofa program. Consider the following call graph:
main ---> FuncA ---> FuncC ---> FuncB
(Explanation: main calls FuncA and FuncB; FuncA calls FuncC).You can get from main to FuncA by usingCTRL-] on the call to FuncA. Thenyou canCTRL-] to get to FuncC. If you now want to go back to main you canuseCTRL-T twice. Then you canCTRL-] to FuncB.
If you issue a ":ta{name}" orCTRL-] command, this tag is inserted at thecurrent position in the stack. If the stack was full (it can hold up to 20entries), the oldest entry is deleted and the older entries shift oneposition up (their index number is decremented by one). If the last usedentry was not at the bottom, the entries below the last used one aredeleted. This means that an old branch in the call graph is lost. After thecommands explained above the tag stack will look like this:
# TO tagFROM line in file/text 1 1 main1 harddisk2:text/vim/test 2 1 FuncB 59 harddisk2:text/vim/src/main.c
The
gettagstack() function returns the tag stack of a specified window. The
settagstack() function modifies the tag stack of a window.
tagstack-examplesWrite to the tag stack just like
:tag but with a user-definedjumper#jump_to_tag function:
" Store where we're jumping from before we jump.let tag = expand('<cword>')let pos = [bufnr()] + getcurpos()[1:]let item = {'bufnr': pos[0], 'from': pos, 'tagname': tag}if jumper#jump_to_tag(tag) " Jump was successful, write previous location to tag stack. let winid = win_getid() let stack = gettagstack(winid) let stack['items'] = [item] call settagstack(winid, stack, 't')endif Set current index of the tag stack to 4:
call settagstack(1005, {'curidx' : 4})Push a new item onto the tag stack:
let pos = [bufnr('myfile.txt'), 10, 1, 0]let newtag = [{'tagname' : 'mytag', 'from' : pos}]call settagstack(2, {'items' : newtag}, 'a')E73When you try to use the tag stack while it doesn't contain anything you willget an error message.
When there are several matching tags, these commands can be used to jumpbetween them. Note that these commands don't change the tag stack, they keepthe same entry.
:ts:tselect:ts[elect][!] [name]List the tags that match [name], using theinformation in the tags file(s).When [name] is not given, the last tag name from thetag stack is used.See
tag-! for [!].With a '>' in the first column is indicated which isthe current position in the list (if there is one).[name] can be a regexp pattern, see
tag-regexp.See
tag-priority for the priorities used in thelisting.Example output:
# pri kind tagfile 1 Ff mch_delayos_amiga.c mch_delay(msec, ignoreinput)> 2 Ff mch_delayos_msdos.c mch_delay(msec, ignoreinput) 3 Ff mch_delayos_unix.c mch_delay(msec, ignoreinput)Type number and <Enter> (empty cancels):
See
tag-priority for the "pri" column. Note thatthis depends on the current file, thus using":tselect xxx" can produce different results.The "kind" column gives the kind of tag, if this wasincluded in the tags file.The "info" column shows information that could befound in the tags file. It depends on the programthat produced the tags file.When the list is long, you may get the
more-prompt.If you already see the tag you want to use, you cantype 'q' and enter the number.
:sts:stselect:sts[elect][!] [name]Does ":tselect[!] [name]" and splits the window forthe selected tag.
g]g]Like
CTRL-], but use ":tselect" instead of ":tag".
v_g]{Visual}g]Same as "g]", but use the highlighted text as theidentifier.
:tj:tjump:tj[ump][!] [name]Like ":tselect", but jump to the tag directly whenthere is only one match.
:stj:stjump:stj[ump][!] [name]Does ":tjump[!] [name]" and splits the window for theselected tag.
g_CTRL-]g
CTRL-]Like
CTRL-], but use ":tjump" instead of ":tag".
v_g_CTRL-]{Visual}g
CTRL-]Same as "g
CTRL-]", but use the highlighted text asthe identifier.
:tn:tnext:[count]tn[ext][!]Jump to [count] next matching tag (default 1). See
tag-! for [!].
:tp:tprevious:[count]tp[revious][!]Jump to [count] previous matching tag (default 1).See
tag-! for [!].
:tN:tNext:[count]tN[ext][!]Same as ":tprevious".
:tr:trewind:[count]tr[ewind][!]Jump to first matching tag. If [count] is given, jumpto [count]th matching tag. See
tag-! for [!].
:lt:ltag:lt[ag][!] [name]Jump to tag [name] and add the matching tags to a newlocation list for the current window. [name] can bea regexp pattern, see
tag-regexp. When [name] isnot given, the last tag name from the tag stack isused. The search pattern to locate the tag line isprefixed with "\V" to escape all the specialcharacters (very nomagic). The location list showingthe matching tags is independent of the tag stack.See
tag-! for [!].
When there is no other message, Vim shows which matching tag has been jumpedto, and the number of matching tags:
tag 1 of 3 or more
The " or more" is used to indicate that Vim didn't try all the tags files yet.When using ":tnext" a few times, or with ":tlast", more matches may be found.
When you didn't see this message because of some other message, or you justwant to know where you are, this command will show it again (and jump to thesame tag as last time):
:0tn
tag-skip-fileWhen a matching tag is found for which the file doesn't exist, this match isskipped and the next matching tag is used. Vim reports this, to notify you ofmissing files. When the end of the list of matches has been reached, an errormessage is given.
tag-previewThe tag match list can also be used in the preview window. The commands arethe same as above, with a "p" prepended.
:pts:ptselect:pts[elect][!] [name]Does ":tselect[!] [name]" and shows the new tag in a"Preview" window. See
:ptag for more info.
:ptj:ptjump:ptj[ump][!] [name]Does ":tjump[!] [name]" and shows the new tag in a"Preview" window. See
:ptag for more info.
static-tagA static tag is a tag that is defined for a specific file. In a C programthis could be a static function.
In Vi jumping to a tag sets the current search pattern. This means that the"n" command after jumping to a tag does not search for the same pattern thatit did before jumping to the tag. Vim does not do this as we consider it tobe a bug. If you really want the old Vi behavior, set the 't' flag in
'cpoptions'.
tag-binary-searchVim uses binary searching in the tags file to find the desired tag quickly.But this only works if the tags file was sorted on ASCII byte value.Therefore, if no match was found, another try is done with a linear search.If you only want the linear search, reset the
'tagbsearch' option. Or better:Sort the tags file!
Note that the binary searching is disabled when not looking for a tag with aspecific name. This happens when ignoring case and when a regular expressionis used that doesn't start with a fixed string. Tag searching can be a lotslower then. The former can be avoided by case-fold sorting the tags file.See
'tagbsearch' for details.
tag-regexpThe ":tag" and ":tselect" commands accept a regular expression argument. See
pattern for the special characters that can be used.When the argument starts with '/', it is used as a pattern. If the argumentdoes not start with '/', it is taken literally, as a full tag name.Examples:
:tag main
jumps to the tag "main" that has the highest priority.
:tag /^get
jumps to the tag that starts with "get" and has the highest priority.
:tag /norm
lists all the tags that contain "norm", including "id_norm".When the argument both exists literally, and match when used as a regexp, aliteral match has a higher priority. For example, ":tag /open" matches "open"before "open_file" and "file_open".When using a pattern case is ignored. If you want to match case use "\C" inthe pattern.
tag-!If the tag is in the current file this will always work. Otherwise theperformed actions depend on whether the current file was changed, whether a !is added to the command and on the
'autowrite' and
'winfixbuf' options:
tag in file winfixbufautowrite
current file changed! optionoption action
----------------------------------------------------------------------------- yesxx off x goto tag nonox off x read other file, goto tag noyesyes off x abandon current file, read other file, goto tag noyesno off on write current file, read other file, goto tag noyesno off off fail yesxyes x x goto tag nonono on x fail noyesno on x fail noyesno on on fail noyesno on off fail -----------------------------------------------------------------------------
If the tag is in the current file, the command will always work.
If the tag is in another file and the current file was not changed, the other file will be made the current file and read into the buffer.
If the tag is in another file, the current file was changed and a ! is added to the command, the changes to the current file are lost, the other file will be made the current file and read into the buffer.
If the tag is in another file, the current file was changed and the
'autowrite' option is on, the current file will be written, the other file will be made the current file and read into the buffer.
If the tag is in another file, the current file was changed and the
'autowrite' option is off, the command will fail. If you want to save the changes, use the ":w" command and then use ":tag" without an argument. This works because the tag is put on the stack anyway. If you want to lose the changes you can use the ":tag!" command.
If the tag is in another file and the window includes
'winfixbuf', the command will fail. If the tag is in the same file then it may succeed.
tag-securityNote that Vim forbids some commands, for security reasons. This works likeusing the
'secure' option for exrc/vimrc files in the current directory. See
trojan-horse and
sandbox.When the
{tagaddress} changes a buffer, you will get a warning message:"WARNING: tag command changed a buffer!!!"In a future version changing the buffer will be impossible. All this forsecurity reasons: Somebody might hide a nasty command in the tags file, whichwould otherwise go unnoticed. Example:
:$d|/tag-function-name/
In Vi the ":tag" command sets the last search pattern when the tag is searchedfor. In Vim this is not done, the previous search pattern is stillremembered, unless the 't' flag is present in
'cpoptions'.
tags-optionThe
'tags' option is a list of file names. Each of these files is searchedfor the tag. This can be used to use a different tags file than the defaultfile "tags". It can also be used to access a common tags file.
The next file in the list is not used when:
A matching static tag for the current buffer has been found.
A matching global tag has been found.This also depends on whether case is ignored. Case is ignored when:
'tagcase' is "smart" and the pattern only contains lower case characters.
'tagcase' is "followscs" and
'smartcase' is set and the pattern only contains lower case characters.If case is not ignored, and the tags file only has a match without matchingcase, the next tags file is searched for a match with matching case. If notag with matching case is found, the first match without matching case isused. If case is ignored, and a matching global tag with or without matchingcase is found, this one is used, no further tags files are searched.
When a tag file name starts with "./", the '.' is replaced with the path ofthe current file. This makes it possible to use a tags file in the directorywhere the current file is (no matter what the current directory is). The ideaof using "./" is that you can define which tag file is searched first: In thecurrent directory ("tags,./tags") or in the directory of the current file("./tags,tags").
For example:
:set tags=./tags,tags,/home/user/commontags
In this example the tag will first be searched for in the file "tags" in thedirectory where the current file is. Next the "tags" file in the currentdirectory. If it is not found there, then the file "/home/user/commontags"will be searched for the tag.
This can be switched off by including the 'd' flag in
'cpoptions', to makeit Vi compatible. "./tags" will then be the tags file in the currentdirectory, instead of the tags file in the directory where the current fileis.
Instead of the comma a space may be used. Then a backslash is required forthe space to be included in the string option:
:set tags=tags\ /home/user/commontags
To include a space in a file name use three backslashes. To include a commain a file name use two backslashes. For example, use:
:set tags=tag\\\ file,/home/user/common\\,tags
for the files "tag file" and "/home/user/common,tags". The
'tags' option willhave the value "tag\ file,/home/user/common\,tags".
If the
'tagrelative' option is on (which is the default) and using a tag filein another directory, file names in that tag file are relative to thedirectory where the tag file is.
ctagsA tags file can be created with an external command, for example "ctags". Itwill contain a tag for each function. Some versions of "ctags" will also makea tag for each "#defined" macro, typedefs, enums, etc.
Some programs that generate tags files:ctagsAs found on most Unix systems. Only supports C. Onlydoes the basic work.universal ctagsA maintained version of ctags based on exuberantctags. See
https://ctags.io.
Exuberant_ctagsexuberant ctagsWorks for C, C++, Java, Fortran, Eiffel and others.See
https://ctags.sourceforge.net. No new versionsince 2009.
:helptags For Vim's
help filesptags.pyFor Python, in Python. Found in your Python sourcedirectory at Tools/scripts/ptags.py.ptagsFor Perl, in Perl. It can be found at
https://metacpan.org/pod/Vim::TagThe lines in the tags file must have one of these two formats:
1.{tagname}{TAB}{tagfile}{TAB}{tagaddress}2.{tagname}{TAB}{tagfile}{TAB}{tagaddress}{term}{field} ..
The first format is a normal tag, which is completely compatible with Vi. Itis the only format produced by traditional ctags implementations. This isoften used for functions that are global, also referenced in other files.
The lines in the tags file can end in<NL> or<CR><NL>. On the Macintosh<CR>also works. The<CR> and<NL> characters can never appear inside a line.
The second format is new. It includes additional information in optionalfields at the end of each line. It is backwards compatible with Vi. It isonly supported by new versions of ctags (such as Universal ctags or Exuberantctags).
{tagname}The identifier. Normally the name of a function, but it canbe any identifier. It cannot contain a
<Tab>.
{TAB}One
<Tab> character.
Note: previous versions allowed anywhite space here. This has been abandoned to allow spaces in
{tagfile}.
{tagfile}The file that contains the definition of
{tagname}. It canhave an absolute or relative path. It may contain environmentvariables and wildcards (although the use of wildcards isdoubtful). It cannot contain a
<Tab>.
{tagaddress}The Ex command that positions the cursor on the tag. It canbe any Ex command, although restrictions apply (see
tag-security). Posix only allows line numbers and searchcommands, which are mostly used.
{term};" The two characters semicolon and double quote. This isinterpreted by Vi as the start of a comment, which makes thefollowing be ignored. This is for backwards compatibilitywith Vi, it ignores the following fields. Example:
APPfile/^static int APP;$/;"v
When
{tagaddress} is not a line number or search pattern, then
{term} must be
|;". Here the bar ends the command (excludingthe bar) and
;" is used to have Vi ignore the rest of theline. Example:
APPfile.ccall cursor(3, 4)|;"v
{field} ..A list of optional fields. Each field has the form:
<Tab>{fieldname}:{value}
The{fieldname} identifies the field, and can only containalphabetical characters [a-zA-Z].The{value} is any string, but cannot contain a<Tab>.These characters are special:"\t" stands for a<Tab>"\r" stands for a<CR>"\n" stands for a<NL>"\\" stands for a single '\' character
There is one field that doesn't have a ':'. This is the kindof the tag. It is handled like it was preceded with "kind:".In the above example, this was "kind:v" (typically variable).See the documentation of ctags for the kinds it produces, withctags you can usectags --list-kinds .
The only other field currently recognized by Vim is "file:"(with an empty value). It is used for a static tag.
The first lines in the tags file can contain lines that start with!_TAG_These are sorted to the first lines, only rare tags that start with "!" cansort to before them. Vim recognizes two items. The first one is the linethat indicates if the file was sorted. When this line is found, Vim usesbinary searching for the tags file:
!_TAG_FILE_SORTED<Tab>1<Tab>{anything}
A tag file may be case-fold sorted to avoid a linear search when case isignored. (Case is ignored when
'ignorecase' is set and
'tagcase' is"followic", or when
'tagcase' is "ignore".) See
'tagbsearch' for details.The value '2' should be used then:
!_TAG_FILE_SORTED<Tab>2<Tab>{anything}
The other tag that Vim recognizes is the encoding of the tags file:
!_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything}
Here "utf-8" is the encoding used for the tags. Vim will then convert the tagbeing searched for from
'encoding' to the encoding of the tags file. And whenlisting tags the reverse happens. When the conversion fails the unconvertedtag is used.
tag-searchThe command can be any Ex command, but often it is a search command.Examples:
tag1file1/^main(argc, argv)/
tag2file2108
The command is always executed with
'magic' not set. The only specialcharacters in a search pattern are "^" (begin-of-line) and "$" (
<EOL>).See
pattern. Note that you must put a backslash before each backslash inthe search text. This is for backwards compatibility with Vi.
E434E435If the command is a normal search command (it starts and ends with "/" or"?"), some special handling is done:
Searching starts on line 1 of the file. The direction of the search is forward for "/", backward for "?". Note that
'wrapscan' does not matter, the whole file is always searched.
If the search fails, another try is done ignoring case. If that fails too, a search is done for:
"^tagname[ \t]*(" (the tag with '^' prepended and "[ \t]*(" appended). When using function names, this will find the function name when it is in column 0. This will help when the arguments to the function have changed since the tags file was made. If this search also fails another search is done with:
"^[#a-zA-Z_].*\<tagname[ \t]*(" This means: A line starting with '#' or an identifier and containing the tag followed by white space and a '('. This will find macro names and function names with a type prepended.
tag-old-staticUntil March 2019 (patch 8.1.1092) an outdated format was supported:
{tagfile}:{tagname}
{TAB}{tagfile}{TAB}{tagaddress} This format is for a static tag only. It is obsolete now, replaced bythe second format. It is only supported by Elvis 1.x, older Vim versions anda few versions of ctags. A static tag is often used for functions that arelocal, only referenced in the file
{tagfile}. Note that for the static tag,the two occurrences of
{tagfile} must be exactly the same. Also see
tags-option below, for how static tags are used.
The support was removed, since when you can update to the new Vim version youshould also be able to update ctags to one that supports the second format.
These commands look for a string in the current file and in all encounteredincluded files (recursively). This can be used to find the definition of avariable, function or macro. If you only want to search in the currentbuffer, use the commands listed at
pattern-searches.
When a line is encountered that includes another file, that file is searchedbefore continuing in the current buffer. Files included by included files arealso searched. When an include file could not be found it is silentlyignored. Use the
:checkpath command to discover which files could not befound, possibly your
'path' option is not set up correctly.
Note: theincluded file is searched, not a buffer that may be editing that file. Onlyfor the current file the lines in the buffer are used.
The string can be any keyword or a defined macro. For the keyword any matchwill be found. For defined macros only lines that match with the
'define'option will be found. The default is "^#\s*define", which is for C programs.For other languages you probably want to change this. See
'define' for anexample for C++. The string cannot contain an end-of-line, only matcheswithin a line are found.
When a match is found for a defined macro, the displaying of lines continueswith the next line when a line ends in a backslash.
The commands that start with "[" start searching from the start of the currentfile. The commands that start with "]" start at the current cursor position.
The
'include' option is used to define a line that includes another file. Thedefault is "\^#\s*include", which is for C programs.
Note: Vim does notrecognize C syntax, if the
'include' option matches a line inside"#ifdef/#endif" or inside a comment, it is searched anyway. The
'isfname'option is used to recognize the file name that comes after the matchedpattern.
The
'path' option is used to find the directory for the include files thatdo not have an absolute path.
The
'comments' option is used for the commands that display a single line orjump to a line. It defines patterns that may start a comment. Those linesare ignored for the search, unless [!] is used. One exception: When the linematches the pattern
"^# *define" it is not considered to be a comment.
If you want to list matches, and then select one to jump to, you could use amapping to do that for you. Here is an example:
:map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " .. nr .. "[\t"<CR>[i[iDisplay the first line that contains the keywordunder the cursor. The search starts at the beginningof the file. Lines that look like a comment areignored (see
'comments' option). If a count is given,the count'th matching line is displayed, and commentlines are not ignored.
]i]ilike "[i", but start at the current cursor position.
:is:isearch:[range]is[earch][!] [count] [/]pattern[/]Like "[i" and "]i", but search in [range] lines(default: whole file).See
:search-args for [/] and [!].
[I[IDisplay all lines that contain the keyword under thecursor. Filenames and line numbers are displayedfor the found lines. The search starts at thebeginning of the file.
]I]Ilike "[I", but start at the current cursor position.
:il:ilist:[range]il[ist][!] [/]pattern[/]Like "[I" and "]I", but search in [range] lines(default: whole file).See
:search-args for [/] and [!].
[_CTRL-I[
CTRL-IJump to the first line that contains the keywordunder the cursor. The search starts at the beginningof the file. Lines that look like a comment areignored (see
'comments' option). If a count is given,the count'th matching line is jumped to, and commentlines are not ignored.
]_CTRL-I]
CTRL-Ilike "[
CTRL-I", but start at the current cursorposition.
:ij:ijump:[range]ij[ump][!] [count] [/]pattern[/]Like "[
CTRL-I" and "]
CTRL-I", but search in[range] lines (default: whole file).See
:search-args for [/] and [!].
CTRL-W
CTRL-ICTRL-W_CTRL-ICTRL-W_iCTRL-W iOpen a new window, with the cursor on the first linethat contains the keyword under the cursor. Thesearch starts at the beginning of the file. Linesthat look like a comment line are ignored (see
'comments' option). If a count is given, the count'thmatching line is jumped to, and comment lines are notignored.
:isp:isplit:[range]isp[lit][!] [count] [/]pattern[/]Like "CTRL-W i" and "CTRL-W i", but search in[range] lines (default: whole file).See
:search-args for [/] and [!].
[d[dDisplay the first macro definition that contains themacro under the cursor. The search starts from thebeginning of the file. If a count is given, thecount'th matching line is displayed.
]d]dlike "[d", but start at the current cursor position.
:ds:dsearch:[range]ds[earch][!] [count] [/]string[/]Like "[d" and "]d", but search in [range] lines(default: whole file).See
:search-args for [/] and [!].
[D[DDisplay all macro definitions that contain the macrounder the cursor. Filenames and line numbers aredisplayed for the found lines. The search startsfrom the beginning of the file.
]D]Dlike "[D", but start at the current cursor position.
:dli:dlist:[range]dli[st][!] [/]string[/]Like
[D and
]D, but search in [range] lines(default: whole file).See
:search-args for [/] and [!].Note that
:dl works like
:delete with the "l"flag, not
:dlist.
[_CTRL-D[
CTRL-DJump to the first macro definition that contains thekeyword under the cursor. The search starts fromthe beginning of the file. If a count is given, thecount'th matching line is jumped to.
]_CTRL-D]
CTRL-Dlike "[
CTRL-D", but start at the current cursorposition.
:dj:djump:[range]dj[ump][!] [count] [/]string[/]Like "[
CTRL-D" and "]
CTRL-D", but search in[range] lines (default: whole file).See
:search-args for [/] and [!].
CTRL-W
CTRL-DCTRL-W_CTRL-DCTRL-W_dCTRL-W dOpen a new window, with the cursor on the firstmacro definition line that contains the keywordunder the cursor. The search starts from thebeginning of the file. If a count is given, thecount'th matching line is jumped to.
:dsp:dsplit:[range]dsp[lit][!] [count] [/]string[/]Like "CTRL-W d", but search in [range] lines(default: whole file).See
:search-args for [/] and [!].
:checkp[ath]!List all the included files.
:search-argsCommon arguments for the commands above:[!]When included, find matches in lines that are recognized as comments.When excluded, a match is ignored when the line is recognized as acomment (according to
'comments'), or the match is in a C comment(after "//" or inside
/* */). Note that a match may be missed if aline is recognized as a comment, but the comment ends halfway the line.And if the line is a comment, but it is not recognized (according to
'comments') a match may be found in it anyway. Example:
/* comment foobar */
A match for "foobar" is found, because this line is not recognized asa comment (even though syntax highlighting does recognize it).
Note: Since a macro definition mostly doesn't look like a comment, the[!] makes no difference for ":dlist", ":dsearch" and ":djump".[/]A pattern can be surrounded by "/". Without "/" only whole words arematched, using the pattern "\<pattern\>". Only after the second "/" anext command can be appended with "|". Example:
:isearch /string/ | echo "the last one"
For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the patternis used as a literal string, not as a search pattern.
It is possible to provide Vim with a function which will generate a list oftags used for commands like
:tag,
:tselect, Normal mode tag commands like
CTRL-] and for the
taglist() function.
The function used for generating the taglist is specified by setting the
'tagfunc' option. The function will be called with three arguments: patternThe tag identifier or pattern used during the tag search. flagsString containing flags to control the function behavior. infoDict containing the following entries: buf_ffname Full filename which can be used for priority. user_data Custom data String, if stored in the tag stack previously by tagfunc.
Note that "a:" needs to be prepended to the argument name when using it.
Currently up to three flags may be passed to the tag function: 'c'The function was invoked by a normal command being processed (mnemonic: the tag function may use the context around thecursor to perform a better job of generating the tag list.) 'i'In Insert mode, the user was completing a tag (with
i_CTRL-X_CTRL-] or
'complete' contains "`t`" or "`]`"). 'r'The first argument to tagfunc should be interpreted as a
pattern (see
tag-regexp), such as when using:
:tag /pat
It is also given when completing in insert mode.If this flag is not present, the argument is usually takenliterally as the full tag name.
Note that when
'tagfunc' is set, the priority of the tags described in
tag-priority does not apply. Instead, the priority is exactly as theordering of the elements in the list returned by the function.
E987The function should return a List of Dict entries. Each Dict must at leastinclude the following entries and each value must be a string:nameName of the tag.filenameName of the file where the tag is defined. It iseither relative to the current directory or a fullpath.cmdEx command used to locate the tag in the file. Thiscan be either an Ex search pattern or a line number.Note that the format is similar to that of
taglist(), which makes it possibleto use its output to generate the result.The following fields are optional:kindType of the tag.user_dataString of custom data stored in the tag stack whichcan be used to disambiguate tags between operations.
If the function returns
v:null instead of a List, a standard tag lookup willbe performed instead.
It is not allowed to change the tagstack from inside
'tagfunc'.
E986It is not allowed to close a window or change window from inside
'tagfunc'.
E1299The following is a hypothetical example of a function used for
'tagfunc'. Ituses the output of
taglist() to generate the result: a list of tags in theinverse order of file names.
function CompareFilenames(item1, item2) let f1 = a:item1['filename'] let f2 = a:item2['filename'] return f1 >=# f2 ? -1 : f1 <=# f2 ? 1 : 0endfunctionfunction TagFunc(pattern, flags, info) let result = taglist(a:pattern) call sort(result, "CompareFilenames") return resultendfuncset tagfunc=TagFunc