tagsrch.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Bram MoolenaarTags and special searchestags-and-searchesSeesection29.1 of the user manual for an introduction.1. Jump toatagtag-commands2. Tag stacktag-stack3. Tag matchlisttag-matchlist4. Tags detailstag-details5. Tags file formattags-file-format6. Include file searchesinclude-search7. Using'tagfunc'tag-function==============================================================================1. Jump toatagtag-commandstagtagsAtagis an identifier that appears ina "tags" file. Itisa sort of labelthat can be jumped to. For example: InC programs each function name can beusedasa tag. The "tags" file has to be generated bya program like ctags,before thetag commands can be used.With the ":tag" command the cursor will be positioned on the tag. With theCTRL-] command, the keyword on which the cursoris standingis usedas thetag. If the cursoris not ona keyword, the first keyword to the right of thecursoris used.The ":tag" command works very well forC programs. If you seea call toafunction and wonder what that function does, position the cursor inside of thefunction name and hitCTRL-]. This will bring you to the function definition.Aneasy way backis with theCTRL-T command. Also read about thetag stackbelow.:ta:tagE426E429:[count]ta[g][!]{name}Jump to the definition of{name}, using theinformation in thetags file(s). Put{name} in thetag stack. Seetag-! for [!].{name} can bearegexp pattern, seetag-regexp.When there are several matchingtags for{name}, jumpto the[count] one. When[count]is omitted thefirst oneis jumped to. Seetag-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. Sameas ":tag{name}", where{name}is thekeyword under or after cursor.When there are several matchingtags for{name}, jumpto the[count] one. When no[count]is given thefirst oneis jumped to. Seetag-matchlist forjumping to other matching tags.v_CTRL-]{Visual}CTRL-]Sameas ":tag{name}", where{name}is the text thatis highlighted.telnet-CTRL-]CTRL-]is the default telnetescape key. When you typeCTRL-] to jump toatag, you will get the telnet prompt instead. Most versions of telnet allowchanging or disabling the defaultescape key. See the telnet man page. Youcan 'telnet-E{Hostname}' to disable theescape character, or 'telnet-e{EscapeCharacter}{Hostname}' to specify anotherescape character. Ifpossible, try to use "ssh" instead of "telnet" to avoid this problem.tag-priorityWhen there are multiple matches fora tag, this priorityis used:1. "FSC"A full matching statictag for the current file.2. "FC"A full matching globaltag for the current file.3. "F "A full matching globaltag for another file.4. "FS "A full matching statictag for another file.5. " SC" An ignore-case matching statictag for the current file.6. "C" An ignore-case matching globaltag for the current file.7. " " An ignore-case matching globaltag for another file.8. "S " An ignore-case matching statictag for another file.Note that when the current file changes, the prioritylistis mostly notchanged, to avoid confusion when using ":tnext". Itis changed when using":tag{name}".The ignore-case matches are not found fora ":tag" command when:-'tagcase'is "followic" and the'ignorecase' optionis off-'tagcase'is "followscs" and the'ignorecase' optionis off and the'smartcase' optionis off or thepattern contains an uppercase character.-'tagcase'is "match"-'tagcase'is "smart" and thepattern contains an uppercase character.The ignore-case matches are found when:-apatternis used (starting witha "/")- for ":tselect"- when'tagcase'is "followic" and'ignorecase'is on- when'tagcase'is "followscs" and'ignorecase'is on or the'smartcase' optionis on and thepattern does not contain an uppercase character- when'tagcase'is "ignore"- when'tagcase'is "smart" and thepattern does not contain an uppercase characterNote that using ignore-casetag searching disables binary searching in thetags file, which causesa slowdown. This can be avoided by fold-casesortingthetag file. See the'tagbsearch' option for an explanation.==============================================================================2. Tag stacktag-stacktagstackE425On thetag stackis remembered whichtags you jumped to, and from where.Tags are only pushed onto the stack when the'tagstack' optionis set.g<RightMouse>g<RightMouse><C-RightMouse><C-RightMouse>CTRL-TCTRL-TJump to[count] older entry in thetag stack(default 1).:po:popE555E556:[count]po[p][!]Jump to[count] older entry intag stack (default 1).Seetag-! for [!].:[count]ta[g][!]Jump to[count] newer entry intag stack (default 1).Seetag-! for [!].:tags:tagsShow the contents of thetag stack. The activeentryis marked witha '>'.The output of ":tags" looks like this:# TOtag FROM line in file/text 1 1 main 1 harddisk2:text/vim/test> 2 2 FuncA58i= FuncA(10); 3 1 FuncC 357 harddisk2:text/vim/src/amiga.cThislist shows thetags that you jumped to and the cursor position beforethat jump. The oldertags areat the top, the newerat the bottom.The '>' points to the active entry. Thisis thetag 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 thetag 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 textat the position.An indentis removed anda long lineis truncated to fit in the window.You can jump to previously usedtags with several commands. Some examples:":pop" orCTRL-Tto position before previoustag{count}CTRL-Tto position before{count} oldertag":tag"to newertag":0tag"to last usedtagThe most obvious way to use thisis 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 togo back to main you canuseCTRL-T twice. Then you canCTRL-] to FuncB.If you issuea ":ta{name}" orCTRL-] command, thistagis insertedat thecurrent position in the stack. If the stack was full (it can hold up to 20entries), the oldest entryis deleted and the older entriesshift oneposition up (theirindex numberis decremented by one). If the last usedentry was notat the bottom, the entries below the last used one aredeleted. This means that an old branch in the call graphis lost. After thecommands explained above thetag stack will look like this:# TOtagFROM line in file/text 1 1 main1 harddisk2:text/vim/test 2 1 FuncB 59 harddisk2:text/vim/src/main.cThegettagstack() function returns thetag stack ofa specified window. Thesettagstack() function modifies thetag stack ofa window.tagstack-examplesWrite to thetag stack just like:tag but witha 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')endifSet currentindex of thetag stack to 4:call settagstack(1005, {'curidx' : 4})Pusha new item onto thetag 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 thetag stack whileit doesn't contain anything you willget an error message.==============================================================================3. Tag matchlisttag-matchlistE427E428When there are several matching tags, these commands can be used to jumpbetween them.Note that these commands don't change thetag stack, they keepthe same entry.:ts:tselect:ts[elect][!][name]List thetags that match[name], using theinformation in thetags file(s).When[name]is not given, the lasttag name from thetag stackis used.Seetag-! for [!].Witha '>' in the first columnis indicated whichisthe current position in thelist (if thereis one).[name] can bearegexp pattern, seetag-regexp.Seetag-priority for the priorities used in thelisting.Example output: # pri kind tagfile 1 Ff mch_delayos_amiga.cmch_delay(msec, ignoreinput)> 2 Ff mch_delayos_msdos.cmch_delay(msec, ignoreinput) 3 Ff mch_delayos_unix.cmch_delay(msec, ignoreinput)Type number and <Enter> (empty cancels):Seetag-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 thetags file.The "info" column shows information that could befound in thetags file. It depends on the programthat produced thetags file.When thelistis long, you may get themore-prompt.If you already see thetag you want to use, you cantype 'q' and enter the number.:sts:stselect:sts[elect][!][name]Does ":tselect[!][name]" and splits thewindow forthe selected tag.g]g]LikeCTRL-], but use ":tselect" instead of ":tag".v_g]{Visual}g]Sameas "g]", but use the highlighted textas theidentifier.:tj:tjump:tj[ump][!][name]Like ":tselect", but jump to thetag directly whenthereis only one match.:stj:stjump:stj[ump][!][name]Does ":tjump[!][name]" and splits thewindow for theselected tag.g_CTRL-]gCTRL-]LikeCTRL-], but use ":tjump" instead of ":tag".v_g_CTRL-]{Visual}gCTRL-]Sameas "gCTRL-]", but use the highlighted textasthe identifier.:tn:tnext:[count]tn[ext][!]Jump to[count] next matchingtag (default 1). Seetag-! for [!].:tp:tprevious:[count]tp[revious][!]Jump to[count] previous matchingtag (default 1).Seetag-! for [!].:tN:tNext:[count]tN[ext][!]Sameas ":tprevious".:tr:trewind:[count]tr[ewind][!]Jump to first matching tag. If[count]is given, jumpto[count]th matching tag. Seetag-! for [!].:tf:tfirst:[count]tf[irst][!]Sameas ":trewind".:tl:tlast:tl[ast][!]Jump to last matching tag. Seetag-! for [!].:lt:ltag:lt[ag][!][name]Jump totag[name] and add the matchingtags toa newlocationlist for the current window.[name] can bearegexp pattern, seetag-regexp. When[name]isnot given, the lasttag name from thetag stackisused. The searchpattern to locate thetag lineisprefixed with "\V" toescape all the specialcharacters (very nomagic). The locationlist showingthe matchingtagsis independent of thetag stack.Seetag-! for [!].When thereis no other message, Vim shows which matchingtag has been jumpedto, and the number of matching tags:tag 1 of 3 or moreThe " or more"is used to indicate that Vim didn't try all thetags 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 showit again (and jump to thesametagas last time)::0tntag-skip-fileWhena matchingtagis found for which the file doesn't exist, this matchisskipped and the next matchingtagis used. Vim reports this, to notify you ofmissing files. When theend of thelist of matches has been reached, an errormessageis given.tag-previewThetag matchlist can also be used in the preview window. The commands arethe sameas above, witha "p" prepended.{not available when compiled without the |+quickfix| feature}:pts:ptselect:pts[elect][!][name]Does ":tselect[!][name]" and shows the newtag ina"Preview" window. See:ptag for more info.:ptj:ptjump:ptj[ump][!][name]Does ":tjump[!][name]" and shows the newtag ina"Preview" window. See:ptag for more info.:ptn:ptnext:[count]ptn[ext][!]":tnext" in the preview window. See:ptag.:ptp:ptprevious:[count]ptp[revious][!]":tprevious" in the preview window. See:ptag.:ptN:ptNext:[count]ptN[ext][!]Sameas ":ptprevious".:ptr:ptrewind:[count]ptr[ewind][!]":trewind" in the preview window. See:ptag.:ptf:ptfirst:[count]ptf[irst][!]Sameas ":ptrewind".:ptl:ptlast:ptl[ast][!]":tlast" in the preview window. See:ptag.==============================================================================4. Tags detailstag-detailsstatic-tagA statictagisatag thatis defined fora specific file. InaC programthis could bea static function.InVi jumping toatag sets the current search pattern. This means that the"n" command after jumping toatag does not search for the samepattern thatit did before jumping to the tag. Vim does notdo thisas we considerit tobea bug. If you really want the oldVi behavior, set the 't' flag in'cpoptions'.tag-binary-searchVim uses binary searching in thetags file to find the desiredtag quickly(when enabledat compile time+tag_binary). But this only works if thetags file was sorted on ASCII byte value. Therefore, if no match was found,another tryis done witha linear search. If you only want the linear search,reset the'tagbsearch' option. Or better: Sort thetags file!Note that the binary searchingis disabled when not looking foratag withaspecific name. This happens when ignoringcase and whena regularexpressionis used that doesn't start witha fixed string. Tag searching can bea lotslower then. The former can be avoided by case-foldsorting thetags file.See'tagbsearch' for details.tag-regexpThe ":tag" and ":tselect" commands accepta regularexpression argument. Seepattern for the special characters that can be used.When the argument starts with '/',itis usedasa pattern. If the argumentdoes not start with '/',itis taken literally,asa fulltag name.Examples: :tag mainjumps to thetag "main" that has the highest priority. :tag /^getjumps to thetag that starts with "get" and has the highest priority. :tag /normlists all thetags that contain "norm", including "id_norm".When the argument both exists literally, and match when usedasa regexp,aliteral match hasa higher priority. For example, ":tag /open" matches "open"before "open_file" and "file_open".When usingapatterncaseis ignored. If you want to matchcase use "\C" inthe pattern.tag-!If thetagis in the current file this will always work. Otherwise theperformed actions depend on whether the current file was changed, whethera!is added to the command and on the'autowrite' and'winfixbuf' options: tag in file winfixbufautowritecurrent file changed! optionoption action ----------------------------------------------------------------------------- yesxx offx gototag nonox offx read other file, gototag noyesyes offxabandon current file, read other file, gototag noyesno off on write current file, read other file, gototag noyesno off off fail yesxyesxx gototag nonono onx fail noyesno onx fail noyesno on on fail noyesno on off fail ------------------------------------------------------------------------------ If thetagis in the current file, the command will always work.- If thetagis 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 thetagis in another file, the current file was changed anda!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 thetagis in another file, the current file was changed and the'autowrite' optionis on, the current file will be written, the other file will be made the current file and read into the buffer.- If thetagis in another file, the current file was changed and the'autowrite' optionis 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 thetagisput on the stack anyway. If you want to lose the changes you can use the ":tag!" command.- If thetagis in another file and thewindow includes'winfixbuf', the command will fail. If thetagis in the same file thenit 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. Seetrojan-horse andsandbox.When the{tagaddress} changesa buffer, you will geta warning message:"WARNING:tag command changeda buffer!!!"Ina future versionchanging the buffer will be impossible. All this forsecurity reasons: Somebody might hidea nasty command in thetags file, whichwould otherwisego unnoticed. Example::$d|/tag-function-name/InVi the ":tag" command sets the last searchpattern when thetagis searchedfor. In Vim thisis not done, the previous searchpatternis stillremembered, unless the 't' flagis present in'cpoptions'.emacs-tagsemacs_tagsE430Emacs styletag files are only supported if Vim was compiled with the+emacs_tags feature enabled. Sorry, thereis no explanation about Emacstagfiles here,itis only supported for backwards compatibility :-).Lines in Emacstags files can be very long. Vim only deals with lines of upto about 510 bytes. To see whether lines are ignored set'verbose' to 5 orhigher. Non-Emacstags file lines can be any length.tags-optionThe'tags' optionisalist of file names. Each of these filesis searchedfor the tag. This can be used to usea differenttags file than the defaultfile "tags". It can also be used to accessa commontags file.The next file in thelistis not used when:-A matching statictag for the current buffer has been found.-A matching globaltag has been found.This also depends on whethercaseis ignored. Caseis ignored when:-'tagcase'is "followic" and'ignorecase'is set-'tagcase'is "ignore"-'tagcase'is "smart" and thepattern only contains lowercase characters.-'tagcase'is "followscs" and'smartcase'is set and thepattern only contains lowercase characters.Ifcaseis not ignored, and thetags file only hasa match without matchingcase, the nexttags fileis searched fora match with matching case. If notag with matchingcaseis found, the first match without matchingcaseisused. Ifcaseis ignored, anda matching globaltag with or without matchingcaseis found, this oneis used, no furthertags files are searched.Whenatag file name starts with "./", the '.'is replaced with the path ofthe current file. This makesit possible to useatags file in the directorywhere the current fileis (no matter what the current directory is). The ideaof using "./"is that you can define whichtag fileis 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/commontagsIn this example thetag will first be searched for in the file "tags" in thedirectory where the current file is. Next the "tags" file in the currentdirectory. Ifitis 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 makeitVi compatible. "./tags" will then be thetags file in the currentdirectory, instead of thetags file in the directory where the current fileis.Instead of the commaaspace may be used. Thenabackslashis required forthespace to be included in thestring option::set tags=tags\ /home/user/commontagsTo includeaspace ina file name use three backslashes. To includea commaina file name use two backslashes. For example, use::set tags=tag\\\ file,/home/user/common\\,tagsfor the files "tag file" and "/home/user/common,tags". The'tags' option willhave the value "tag\ file,/home/user/common\,tags".If the'tagrelative' optionis on (whichis the default) and usingatag filein another directory, file names in thattag file are relative to thedirectory where thetag file is.==============================================================================5. Tags file formattags-file-formatE431ctagsAtags file can be created with an external command, for example "ctags". Itwill containatag for each function. Some versions of "ctags" will also makeatag for each "#defined" macro, typedefs, enums, etc.Some programs that generatetags files:ctagsAs found on mostUnix systems. Only supports C. Onlydoes the basic work.universalctagsA maintained version ofctags based on exuberantctags. Seehttps://ctags.io.Exuberant_ctagsexuberantctagsThisisa very good one. It works for C, C++, Java,Fortran, Eiffel and others. It can generatetags formany items. Seehttp://ctags.sourceforge.net.No new version since 2009.etagsConnected to Emacs. Supports many languages.:helptags For Vim'shelp filesptags.pyFor Python, in Python. Found in yourPython sourcedirectoryat Tools/scripts/ptags.py.ptagsFor Perl, in Perl. It can be foundathttps://metacpan.org/pod/Vim::TaggnatxrefFor Ada. Seehttp://www.gnuada.org/. gnatxrefispart of the gnat package.The lines in thetags filemust have one of these two formats:1.{tagname}{TAB}{tagfile}{TAB}{tagaddress}2.{tagname}{TAB}{tagfile}{TAB}{tagaddress}{term}{field} ..Previously an old format was supported, seetag-old-static.The first formatisa normal tag, whichis completely compatible with Vi. Itis the only format produced by traditionalctags implementations. Thisisoften used forfunctions that are global, also referenced in other files.The lines in thetags file canend in<NL> or<CR><NL>. On theMacintosh<CR>also works. The<CR> and<NL> characters can never appear insidea line.The second formatis new. It includes additional information in optionalfieldsat theend of each line. Itis backwards compatible with Vi. Itisonly supported by new versions ofctags (suchas Universalctags or Exuberantctags).{tagname}The identifier. Normally the name ofa function, butit canbe any identifier. It cannot containa<Tab>.{TAB}One<Tab> character.Note: previous versions allowed anywhitespace 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 andwildcards (although the use ofwildcardsisdoubtful). It cannot containa<Tab>.{tagaddress}TheEx command that positions the cursor on the tag. It canbe anyEx command, although restrictions apply (seetag-security).Posix only allows line numbers and searchcommands, which are mostly used.{term};" The two characters semicolon and doublequote. Thisisinterpreted byVias the start ofa comment, which makes thefollowing be ignored. Thisis for backwards compatibilitywith Vi,it ignores the following fields. Example:APPfile/^static int APP;$/;"vWhen{tagaddress}is nota line number or search pattern, then{term}must be |;". Here thebar ends the command (excludingthe bar) and;"is used to haveVi ignore the rest of theline. Example:APPfile.ccall cursor(3, 4)|;"v{field} ..Alist 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 containa<Tab>.These characters are special:"\t" stands fora<Tab>"\r" stands fora<CR>"\n" stands fora<NL>"\\" stands fora single '\' characterThereis one field that doesn't havea ':'. Thisis the kindof the tag. Itis handled likeit was preceded with "kind:".In the above example, this was "kind:v" (typically variable).See the documentation ofctags for the kindsit produces, withctags you can use `ctags --list-kinds`.The only other field currently recognized by Vimis "file:"(with an empty value). Itis used fora static tag.The first lines in thetags file can contain lines that start with!_TAG_These are sorted to the first lines, only raretags that start with "!" cansort to before them. Vim recognizes two items. The first oneis the linethat indicates if the file was sorted. When this lineis found, Vim usesbinary searching for thetags file:!_TAG_FILE_SORTED<Tab>1<Tab>{anything}Atag file may be case-fold sorted to avoida linear search whencaseisignored. (Caseis 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 othertag that Vim recognizesis the encoding of thetags file:!_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything}Here "utf-8"is the encoding used for the tags. Vim will then convert thetagbeing searched for from'encoding' to the encoding of thetags file. And whenlistingtags the reverse happens. When the conversion fails the unconvertedtagis used.tag-searchThe command can be anyEx command, but oftenitisa search command.Examples:tag1file1/^main(argc, argv)/tag2file2108The commandis always executed with'magic' not set. The only specialcharacters ina searchpattern are "^" (begin-of-line) and "$" (<EOL>).Seepattern.Note that youmustputabackslash before eachbackslash inthe search text. Thisis for backwards compatibility with Vi.E434E435If the commandisa normal search command (it starts and ends with "/" or"?"), some special handlingis done:- Searching starts on line 1 of the file. The direction of the searchis forward for "/", backward for "?".Note that'wrapscan' does not matter, the whole fileis always searched.- If the search fails, another tryis done ignoring case. If that fails too,a searchis done for:"^tagname[ \t]*(" (thetag with '^' prepended and "[ \t]*(" appended). When using function names, this will find the function name whenitis in column 0. This willhelp when the arguments to the function have changed since thetags file was made. If this search also fails another searchis done with:"^[#a-zA-Z_].*\<tagname[ \t]*(" This means:A linestarting with '#' or an identifier and containing thetag followed by whitespace anda '('. This will findmacro names and function names witha type prepended.tag-old-staticUntil March 2019 (patch 8.1.1092) an outdated format was supported:{tagfile}:{tagname}{TAB}{tagfile}{TAB}{tagaddress}This formatis fora statictag only. Itis obsolete now, replaced bythe second format. Itis only supported byElvis 1.x, older Vim versions anda few versions of ctags.A statictagis often used forfunctions 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 seetags-option below, for how statictags are used.The support was removed, since when you can update to the newVim version youshould also be able to updatectags to one that supports the second format.==============================================================================6. Include file searchesinclude-searchdefinition-searchE387E388E389These commands look forastring in the current file and in all encounteredincluded files (recursively). This can be used to find the definition ofavariable, function or macro. If you only want to search in the currentbuffer, use the commands listedatpattern-searches.These commands are not available when the+find_in_path feature was disabledat compile time.Whena lineis encountered that includes another file, that fileis searchedbefore continuing in the current buffer. Files included by included files arealso searched. When an include file could not be founditis silentlyignored. Use the:checkpath command to discover which files could not befound, possibly your'path' optionis not set up correctly.Note: theincluded fileis searched, nota buffer that may be editing that file. Onlyfor the current file the lines in the buffer are used.Thestring can be any keyword ora defined macro. For the keyword any matchwill be found. For defined macros only lines that match with the'define'option will be found. The defaultis "^#\s*define", whichis forC programs.For other languages you probably want to change this. See'define' for anexample for C++. Thestring cannot contain an end-of-line, only matcheswithina line are found.Whena matchis found fora defined macro, the displaying of lines continueswith the next line whena line ends ina backslash.The commands that start with "[" start searching from the start of the currentfile. The commands that start with "]" startat the current cursor position.The'include' optionis used to definea line that includes another file. Thedefaultis "\^#\s*include", whichis forC programs.Note: Vim does notrecognizeC syntax, if the'include' option matchesa line inside"#ifdef/#endif" or insidea comment,itis searched anyway. The'isfname'optionis used to recognize the file name that comes after the matchedpattern.The'path' optionis used to find the directory for the include files thatdo not have an absolute path.The'comments' optionis used for the commands that displaya single line orjump toa line. It defines patterns that may starta comment. Those linesare ignored for the search, unless [!]is used. One exception: When the linematches thepattern "^# *define"itis not considered to bea comment.If you want tolist matches, and then select one to jump to, you could useamapping todo that for you. Hereis 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 startsat the beginningof the file. Lines that look likea comment areignored (see'comments' option). Ifacountis given,the count'th matching lineis displayed, and commentlines are not ignored.]i]ilike "[i", but startat 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 startsat thebeginning of the file.]I]Ilike "[I", but startat 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 startsat the beginningof the file. Lines that look likea comment areignored (see'comments' option). Ifacountis given,the count'th matching lineis jumped to, and commentlines are not ignored.]_CTRL-I]CTRL-Ilike "[CTRL-I", but startat 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-WCTRL-ICTRL-W_CTRL-ICTRL-W_iCTRL-WiOpena new window, with the cursor on the first linethat contains the keyword under the cursor. Thesearch startsat the beginning of the file. Linesthat look likea comment line are ignored (see'comments' option). Ifacountis given, the count'thmatching lineis jumped to, and comment lines are notignored.:isp:isplit:[range]isp[lit][!][count] [/]pattern[/]Like "CTRL-Wi" and "CTRL-Wi", but search in[range] lines (default: whole file).See:search-args for [/] and [!].[d[dDisplay the firstmacro definition that contains themacro under the cursor. The search starts from thebeginning of the file. Ifacountis given, thecount'th matching lineis displayed.]d]dlike "[d", but startat 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 allmacrodefinitions that contain themacrounder the cursor. Filenames and line numbers aredisplayed for the found lines. The search startsfrom the beginning of the file.]D]Dlike "[D", but startat 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 firstmacro definition that contains thekeyword under the cursor. The search starts fromthe beginning of the file. Ifacountis given, thecount'th matching lineis jumped to.]_CTRL-D]CTRL-Dlike "[CTRL-D", but startat 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-WCTRL-DCTRL-W_CTRL-DCTRL-W_dCTRL-WdOpena new window, with the cursor on the firstmacro definition line that contains the keywordunder the cursor. The search starts from thebeginning of the file. Ifacountis given, thecount'th matching lineis jumped to.:dsp:dsplit:[range]dsp[lit][!][count] [/]string[/]Like "CTRL-Wd", but search in[range] lines(default: whole file).See:search-args for [/] and [!].:che:chec:check:checkpath:che[ckpath]List all the included files that could not be found.:che[ckpath]!List all the included files.:search-argsCommon arguments for the commands above:[!]When included, find matches in lines that are recognizedas comments.When excluded,a matchis ignored when the lineis recognizedasacomment (according to'comments'), or the matchis inaC comment(after "//" or inside/* */).Note thata match may be missed ifalineis recognizedasa comment, but the comment ends halfway theline. And if the lineisa comment, butitis not recognized(according to'comments')a match may be found init anyway. Example:/* comment foobar */A match for "foobar"is found, because this lineis not recognizedasa comment (even thoughsyntax highlighting does recognize it).Note: Sinceamacro definition mostly doesn't look likea comment, the[!] makes no difference for ":dlist", ":dsearch" and ":djump".[/]Apattern can be surrounded by '/'. Without '/' only whole words arematched, using thepattern "\<pattern\>". Only after the second '/'anext command can be appended with'|'. Example::isearch /string/ | echo "the last one"Fora ":djump", ":dsplit", ":dlist" and ":dsearch" command thepatternis usedasa literal string, notasa search pattern.==============================================================================7. Using'tagfunc'tag-functionItis possible to provide Vim witha function which will generatealist oftags used for commands like:tag,:tselect,Normal modetag commands likeCTRL-] and for thetaglist() function.The function used for generating the taglistis specified by setting the'tagfunc' option. The function will be called with three arguments:patternThetag identifier orpattern used during thetag search. flagsString containing flags tocontrol 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 thetag stack previously by tagfunc.Note that ina legacy function "a:" needs to be prepended to the argument namewhen using it.Currently up to three flags may be passed to thetag function: 'c'The function was invoked bya normal command being processed (mnemonic: thetag function may use the context around thecursor to performa betterjob of generating thetag list.) 'i'InInsert mode, the user was completingatag (withi_CTRL-X_CTRL-] or'complete' contains "t" or "]"). 'r'The first argument to tagfunc should be interpretedasapattern (seetag-regexp), suchas when using: :tag /patItis also given when completing ininsert mode.If this flagis not present, the argumentis usually takenliterallyas the fulltag name.Note that when'tagfunc'is set, the priority of thetags described intag-priority does not apply. Instead, the priorityis exactlyas theordering of the elements in thelist returned by the function.E987The function should returnaList ofDict entries. EachDictmustat leastinclude the following entries and each valuemust bea string:nameName of the tag.filenameName of the file where thetagis defined. Itiseither relative to the current directory ora fullpath.cmdEx command used to locate thetag in the file. Thiscan be either anEx searchpattern ora line number.Note that the formatis similar to that oftaglist(), which makesit possibleto use its output to generate the result.The following fields are optional:kindType of the tag.user_dataString of custom data stored in thetag stack whichcan be used to disambiguatetags between operations.If the function returnsv:null instead ofa List,a standardtag lookup willbe performed instead.Itis not allowed to change thetagstack from inside'tagfunc'.E986Itis not allowed to closeawindow or changewindow from inside'tagfunc'.E1299The followingisa hypothetical example ofa function used for'tagfunc'. Ituses the output oftaglist() to generate the result:alist oftags 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=TagFuncNote: When executingtaglist() the'tagfunc' function won't be calledrecursively. vim:tw=78:ts=8:noet:ft=help:norl: