quickfix.txt ForVim version 9.1. Last change: 2025 Apr 06VIM REFERENCE MANUAL by Bram MoolenaarThis subjectis introduced insection30.1 of the user manual.1. Using QuickFix commandsquickfix2. The errorwindowquickfix-window3. Using more than onelist oferrorsquickfix-error-lists4. Using:make:make_makeprg5. Using:grepgrep6. Selectinga compilercompiler-select7. The error formaterror-file-format8. The directory stackquickfix-directory-stack9. Specific error file formatserrorformats10. Customizing thequickfixwindowquickfix-window-functionThequickfix commands are not available when the+quickfix feature wasdisabledat compile time.=============================================================================1. Using QuickFix commandsquickfixQuickfixE42Vim hasa special mode to speedup the edit-compile-edit cycle. Thisisinspired by thequickfix option of the Manx's AztecC compiler on the Amiga.The ideais to save the errormessages from the compiler ina file and use Vimto jump to theerrors one by one. You can examine each problem and fix it,without having to remember all the error messages.In Vim thequickfix commands are used more generally to findalist ofpositions in files. For example,:vimgrep findspattern matches. You canuse the positions inascript with thegetqflist() function. Thus you candoa lot more than the edit/compile/fix cycle!If you have the errormessages ina file you can start Vim with:vim -q filenameFrom inside Vim aneasy way to runa command and handle the outputis with the:make command (see below).The'errorformat' option should be set to match the errormessages from yourcompiler (seeerrorformat below).quickfix-stackquickfix-IDEachquickfixlist hasa unique identifier called thequickfix ID and thisnumber will not change withina Vim session. Thegetqflist() function can beused to get the identifier assigned toa list. Thereis alsoaquickfixlistnumber which may change whenever more than'chistory' lists are added toaquickfix stack.location-listE776A locationlistisa window-localquickfix list. You get one after commandslike:lvimgrep,:lgrep,:lhelpgrep,:lmake, etc., which createalocationlist instead ofaquickfixlistas the corresponding:vimgrep,:grep,:helpgrep,:make do.location-list-file-windowA locationlistis associated withawindow and eachwindow can haveaseparate location list.A locationlist can be associated with only onewindow. The locationlistis independent of thequickfix list.Whenawindow witha locationlistis split, the newwindow getsa copy of thelocation list. When there are no longer any references toa location list,the locationlistis destroyed.quickfix-changedtickEveryquickfix and locationlist hasa read-only changedtick variable thattracks the total number of changes made to the list. Every time thequickfixlistis modified, thiscountis incremented. This can be used to perform anaction only when thelist has changed. Thegetqflist() andgetloclist()functions can be used to query the current value of changedtick. You cannotchange the changedtick variable.The followingquickfix commands can be used. The locationlist commands aresimilar to thequickfix commands,replacing the 'c' prefix in thequickfixcommand with 'l'.E924If the currentwindow was closed by anautocommand while processingalocationlist command,it will be aborted.E925E926If the currentquickfix or locationlist was changed by anautocommand whileprocessingaquickfix or locationlist command,it will be aborted.:cc:cc[!][nr]Display error[nr]. If[nr]is omitted, the same:[nr]cc[!]erroris displayed again. Without [!] this doesn'twork when jumping to another buffer, the current bufferhas been changed, thereis the onlywindow for thebuffer and both'hidden' and'autowrite' are off.When jumping to another buffer with [!] any changes tothe current buffer are lost, unless'hidden'is set orthereis anotherwindow for this buffer.The'switchbuf' settings are respected when jumpingtoa buffer.When used in thequickfixwindow the line number canbe used, including "." for the current line and "$"for the last line.:ll:ll[!][nr]Sameas ":cc", except the locationlist for the:[nr]ll[!]currentwindowis used instead of thequickfix list.:cn:cne:cnextE553:[count]cn[ext][!]Display the[count] next error in thelist thatincludesa file name. If there are no file namesatall,go to the[count] next error. See:cc for[!] and'switchbuf'.:lne:lnext:[count]lne[xt][!]Sameas ":cnext", except the locationlist for thecurrentwindowis used instead of thequickfix list.:[count]cN[ext][!]:cp:cprevious:cprev:cN:cNext:[count]cp[revious][!]Display the[count] previous error in thelist thatincludesa file name. If there are no file namesatall,go to the[count] previous error. See:cc for[!] and'switchbuf'.:[count]lN[ext][!]:lp:lprevious:lprev:lN:lNext:[count]lp[revious][!]Sameas ":cNext" and ":cprevious", except the locationlist for the currentwindowis used instead of thequickfix list.:cabo:cabove:[count]cabo[ve]Go to the[count] error above the current line in thecurrent buffer. If[count]is omitted, then 1isused. If there are no errors, then an error messageis displayed. Assumes that the entries inaquickfixlist are sorted by their buffer number and linenumber. If there are multipleerrors on the same line,then only the first entryis used. If[count] exceedsthe number of entries above the current line, then thefirst error in the fileis selected.:lab:labove:[count]lab[ove]Sameas ":cabove", except the locationlist for thecurrentwindowis used instead of thequickfix list.:cbel:cbelow:[count]cbel[ow]Go to the[count] error below the current line in thecurrent buffer. If[count]is omitted, then 1isused. If there are no errors, then an error messageis displayed. Assumes that the entries inaquickfixlist are sorted by their buffer number and linenumber. If there are multipleerrors on the sameline, then only the first entryis used. If[count]exceeds the number of entries below the current line,then the last error in the fileis selected.:lbel:lbelow:[count]lbel[ow]Sameas ":cbelow", except the locationlist for thecurrentwindowis used instead of thequickfix list.:cbe:cbefore:[count]cbe[fore]Go to the[count] error before the current cursorposition in the current buffer. If[count]isomitted, then 1is used. If there are no errors, thenan error messageis displayed. Assumes that theentries inaquickfixlist are sorted by their buffer,line and column numbers. If[count] exceeds thenumber of entries before the current position, thenthe first error in the fileis selected.:lbe:lbefore:[count]lbe[fore]Sameas ":cbefore", except the locationlist for thecurrentwindowis used instead of thequickfix list.:caf:cafter:[count]caf[ter]Go to the[count] error after the current cursorposition in the current buffer. If[count]isomitted, then 1is used. If there are no errors, thenan error messageis displayed. Assumes that theentries inaquickfixlist are sorted by their buffer,line and column numbers. If[count] exceeds thenumber of entries after the current position, thenthe last error in the fileis selected.:laf:lafter:[count]laf[ter]Sameas ":cafter", except the locationlist for thecurrentwindowis used instead of thequickfix list.:cnf:cnfile:[count]cnf[ile][!]Display the first error in the[count] next file inthelist that includesa file name. If there are nofile namesat all or if thereis no next file,go tothe[count] next error. See:cc for [!] and'switchbuf'.:lnf:lnfile:[count]lnf[ile][!]Sameas ":cnfile", except the locationlist for thecurrentwindowis used instead of thequickfix list.:[count]cNf[ile][!]:cpf:cpfile:cNf:cNfile:[count]cpf[ile][!]Display the last error in the[count] previous file inthelist that includesa file name. If there are nofile namesat all or if thereis no next file,go tothe[count] previous error. See:cc for [!] and'switchbuf'.:[count]lNf[ile][!]:lpf:lpfile:lNf:lNfile:[count]lpf[ile][!]Sameas ":cNfile" and ":cpfile", except the locationlist for the currentwindowis used instead of thequickfix list.:crewind:cr:cr[ewind][!][nr]Display error[nr]. If[nr]is omitted, the FIRSTerroris displayed. See:cc.:lrewind:lr:lr[ewind][!][nr]Sameas ":crewind", except the locationlist for thecurrentwindowis used instead of thequickfix list.:cfirst:cfir:cfir[st][!][nr]Sameas ":crewind".:lfirst:lfir:lfir[st][!][nr]Sameas ":lrewind".:clast:cla:cla[st][!][nr]Display error[nr]. If[nr]is omitted, the LASTerroris displayed. See:cc.:llast:lla:lla[st][!][nr]Sameas ":clast", except the locationlist for thecurrentwindowis used instead of thequickfix list.:cq:cquit:cq[uit][!]:{N}cq[uit][!]:cq[uit][!]{N}Quit Vim with error code{N}.{N} defaults to one.Useful when Vimis called from another program:e.g.,a compiler will not compile the same file again,`git commit` will abort the committing process,fc(built-in for shells like bash and zsh) will notexecute the command, etc.{N} can also be zero, in whichcase Vim exitsnormally.WARNING: All changes in files are lost! Also when the[!]is not used. It works like ":qall!":qall,except that Vim returnsa non-zero exit code.:cf:cfi:cfile:cf[ile][!][errorfile]Read the error file and jump to the first error.Thisis done automatically when Vimis started withthe-q option. You can use this command when youkeep Vim running while compiling. If you give thename of the errorfile, the'errorfile' option willbe set to[errorfile]. See:cc for [!].If the encoding of the error file differs from the'encoding' option, you can use the'makeencoding'option to specify the encoding.:lf:lfi:lfile:lf[ile][!][errorfile]Sameas ":cfile", except the locationlist for thecurrentwindowis used instead of thequickfix list.You can not use the-q command-line option to setthe location list.:cg[etfile][errorfile]:cg:cgetfileRead the error file. Just like ":cfile" but don'tjump to the first error.If the encoding of the error file differs from the'encoding' option, you can use the'makeencoding'option to specify the encoding.:lg[etfile][errorfile]:lg:lge:lgetfileSameas ":cgetfile", except the locationlist for thecurrentwindowis used instead of thequickfix list.:caddf:caddfile:caddf[ile][errorfile]Read the error file and add theerrors from theerrorfile to the currentquickfix list. Ifaquickfixlistis not present, thena newlistis created.If the encoding of the error file differs from the'encoding' option, you can use the'makeencoding'option to specify the encoding.:laddf:laddfile:laddf[ile][errorfile]Sameas ":caddfile", except the locationlist for thecurrentwindowis used instead of thequickfix list.:cb:cbufferE681:[range]cb[uffer][!][bufnr]Read the errorlist from the current buffer.When[bufnr]is givenitmust be the number ofaloaded buffer. That buffer will then be used insteadof the current buffer.A range can be specified for the lines to be used.Otherwise all lines in the buffer are used.See:cc for [!].:lb:lbuffer:[range]lb[uffer][!][bufnr]Sameas ":cbuffer", except the locationlist for thecurrentwindowis used instead of thequickfix list.:cgetb:cgetbuffer:[range]cgetb[uffer][bufnr]Read the errorlist from the current buffer. Justlike ":cbuffer" but don't jump to the first error.:lgetb:lgetbuffer:[range]lgetb[uffer][bufnr]Sameas ":cgetbuffer", except the locationlist forthe currentwindowis used instead of thequickfixlist.:cad:cadd:caddbuffer:[range]cad[dbuffer][bufnr]Read the errorlist from the current buffer and addtheerrors to the currentquickfix list. Ifaquickfixlistis not present, thena newlistiscreated. Otherwise, sameas ":cbuffer".:laddb:laddbuffer:[range]laddb[uffer][bufnr]Sameas ":caddbuffer", except the locationlist forthe currentwindowis used instead of thequickfixlist.:cex:cexprE777:cex[pr][!]{expr}Createaquickfixlist using the result of{expr} andjump to the first error.If{expr}isa String, then each newline terminatedline in theStringis processed using the global valueof'errorformat' and the resultis added to thequickfix list.If{expr}isa List, then eachString item in thelistis processed and added to thequickfix list. NonString items in theList are ignored.See:cc for [!].Examples::cexpr system('grep -n xyz *'):cexpr getline(1, '$'):lex:lexpr:lex[pr][!]{expr}Sameas:cexpr, except the locationlist for thecurrentwindowis used instead of thequickfix list.:cgete:cgetexpr:cgete[xpr]{expr}Createaquickfixlist using the result of{expr}.Just like:cexpr, but don't jump to the first error.:lgete:lgetexpr:lgete[xpr]{expr}Sameas:cgetexpr, except the locationlist for thecurrentwindowis used instead of thequickfix list.:cadde:caddexpr:cadde[xpr]{expr}Evaluate{expr} and add the resulting lines to thecurrentquickfix list. Ifaquickfixlistis notpresent, thena newlistis created. The currentcursor position will not be changed. See:cexpr formore information.Example: :g/mypattern/caddexpr expand("%") .. ":" .. line(".") .. ":" .. getline("."):lad:ladd:laddexpr:lad[dexpr]{expr}Sameas ":caddexpr", except the locationlist for thecurrentwindowis used instead of thequickfix list.:cl:clist:cl[ist][from] [,[to]]List allerrors that are validquickfix-valid.If numbers[from] and/or[to] are given, the respectiverange oferrorsis listed.A negative number countsfrom the last error backwards, -1 being the last error.The:filter command can be used to display only thequickfix entries matchinga supplied pattern. Thepatternis matched against the filename, module name,pattern and text of the entry.:cl[ist] +{count}List the current and next{count} valid errors. Thisis similar to ":clist from from+count", where "from"is the current error position.:cl[ist]![from] [,[to]]List all errors.:cl[ist]! +{count}List the current and next{count} error lines. Thisis useful to see unrecognized lines after the currentone. For example, if ":clist" shows:8384 testje.java:252: error: cannot find symbolThen using ":cl! +3" shows the reason:8384 testje.java:252: error: cannot find symbol8385: ZexitCode = Fmainx();8386: ^8387: symbol: method Fmainx():lli[st][from] [,[to]]:lli:llistSameas ":clist", except the locationlist for thecurrentwindowis used instead of thequickfix list.:lli[st]![from] [,[to]]List all the entries in the locationlist for thecurrent window.If youinsert or delete lines, mostly the correct error locationis stillfound because hidden marks are used. Sometimes, when themark has beendeleted for some reason, the message "line changed"is shown to warn you thatthe error location may not be correct. If you quit Vim and start again themarks are lost and the error locations may not be correct anymore.Twoautocommands are available for running commands before and afteraquickfix command (':make', ':grep' and so on)is executed. SeeQuickFixCmdPre andQuickFixCmdPost for details.QuickFixCmdPost-exampleWhen'encoding' differs from the locale, the errormessages may haveadifferent encoding from what Vimis using. To convert themessages you canuse this code:function QfMakeConv() let qflist = getqflist() for i in qflist let i.text = iconv(i.text, "cp936", "utf-8") endfor call setqflist(qflist)endfunctionau QuickfixCmdPost make call QfMakeConv()Another optionis using'makeencoding'.quickfix-titleEveryquickfix and locationlist hasa title. By default the titleis set tothe command that created the list. Thegetqflist() andgetloclist()functions can be used to get the title ofaquickfix anda locationlistrespectively. Thesetqflist() andsetloclist()functions can be used tomodify the title ofaquickfix and locationlist respectively. Examples:call setqflist([], 'a', {'title' : 'Cmd output'})echo getqflist({'title' : 1})call setloclist(3, [], 'a', {'title' : 'Cmd output'})echo getloclist(3, {'title' : 1})quickfix-indexWhen you jump toa quickfix/locationlist entry using any of thequickfixcommands (e.g.:cc,:cnext,:cprev, etc.), that entry becomes thecurrently selected entry. Theindex of the currently selected entry inaquickfix/locationlist can be obtained using the getqflist()/getloclist()functions. Examples:echo getqflist({'idx' : 0}).idxecho getqflist({'id' : qfid, 'idx' : 0}).idxecho getloclist(2, {'idx' : 0}).idxFora newquickfix list, the first entryis selected and theindexis 1. Anyentry in any quickfix/locationlist can be setas the currently selected entryusing thesetqflist() function. Examples:call setqflist([], 'a', {'idx' : 12})call setqflist([], 'a', {'id' : qfid, 'idx' : 7})call setloclist(1, [], 'a', {'idx' : 7})quickfix-sizeYou can get the number of entries (size) inaquickfix anda locationlistusing thegetqflist() andgetloclist()functions respectively. Examples:echo getqflist({'size' : 1})echo getloclist(5, {'size' : 1})quickfix-contextAny Vim type can be associatedasa context withaquickfix or location list.Thesetqflist() and thesetloclist()functions can be used to associateacontext withaquickfix anda locationlist respectively. Thegetqflist()and thegetloclist()functions can be used to retrieve the context ofaquickfix anda locationlist respectively. Thisis useful fora Vimplugindealing with multiple quickfix/location lists.Examples:let somectx = {'name' : 'Vim', 'type' : 'Editor'}call setqflist([], 'a', {'context' : somectx})echo getqflist({'context' : 1})let newctx = ['red', 'green', 'blue']call setloclist(2, [], 'a', {'id' : qfid, 'context' : newctx})echo getloclist(2, {'id' : qfid, 'context' : 1})quickfix-parseYou can parsealist of lines using'errorformat' without creating ormodifyingaquickfixlist using thegetqflist() function. Examples:echo getqflist({'lines' : ["F1:10:Line10", "F2:20:Line20"]})echo getqflist({'lines' : systemlist('grep -Hn quickfix *')})This returnsa dictionary where the "items" key contains thelist ofquickfixentries parsed from lines. The following shows how to usea custom'errorformat' to parse the lines without modifying the'errorformat' option:echo getqflist({'efm' : '%f#%l#%m', 'lines' : ['F1#10#Line']})EXECUTEA COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST::cdo:cdo[!]{cmd}Execute{cmd} in each valid entry in thequickfix list.It works like doing this::cfirst:{cmd}:cnext:{cmd}etc.When the current file can't beabandoned and the [!]is not present, the command fails.When going to the next entry fails execution stops.The last buffer (or where an error occurred) becomesthe current buffer.{cmd} can contain'|' to concatenate several commands.Only valid entries in thequickfixlist are used.A range can be used to select entries, e.g.::10,$cdo cmdTo skip entries 1 to 9.Note: While this commandis executing, theSyntaxautocommand eventis disabled by addingit to'eventignore'. This considerably speeds up editingeach buffer.Also see:bufdo,:tabdo,:argdo,:windo,:ldo,:cfdo and:lfdo.:cfdo:cfdo[!]{cmd}Execute{cmd} in each file in thequickfix list.It works like doing this::cfirst:{cmd}:cnfile:{cmd}etc.Otherwiseit works the sameas:cdo.:ldo:ld[o][!]{cmd}Execute{cmd} in each valid entry in the locationlistfor the current window.It works like doing this::lfirst:{cmd}:lnext:{cmd}etc.Only valid entries in the locationlist are used.Otherwiseit works the sameas:cdo.:lfdo:lfdo[!]{cmd}Execute{cmd} in each file in the locationlist forthe current window.It works like doing this::lfirst:{cmd}:lnfile:{cmd}etc.Otherwiseit works the sameas:ldo.FILTERINGA QUICKFIX OR LOCATION LIST:cfilter-plugin:Cfilter:Lfilterpackage-cfilterIf you have too many entries inaquickfix list, you can use the cfilterplugin to reduce the number of entries. Load theplugin with: packadd cfilterThen you can use the following commands tofiltera quickfix/location list: :Cfilter[!] /{pat}/ :Lfilter[!] /{pat}/The:Cfilter command createsa newquickfixlist from the entries matching{pat} in the currentquickfix list.{pat}isa Vimregular-expressionpattern. Both the file name and the text of the entries are matched against{pat}. If the optional!is supplied, then the entries not matching{pat} areused. Thepattern can be optionally enclosed using one of the followingcharacters: ', ",/. If thepatternis empty, then the last used searchpatternis used.The:Lfilter command does the sameas:Cfilter but operates on the currentlocation list.The current quickfix/locationlistis not modified by these commands, so youcango back to the unfilteredlist using the:colder/:lolder command.=============================================================================2. The errorwindowquickfix-window:cope:copenw:quickfix_title:cope[n][height]Openawindow to show the currentlist of errors.When[height]is given, thewindow becomes that high(if thereis room). When[height]is omitted thewindowis made ten lines high.If there alreadyisaquickfix window,it will be madethe current window. Itis not possible to openasecondquickfix window. If[height]is given theexistingwindow will be resized to it.quickfix-bufferThewindow will containa special buffer, with'buftype' equal to "quickfix". Don't change this!Thewindow will have thew:quickfix_title variable setwhich will indicate the command that produced thequickfix list. This can be used to composea customstatus line if the value of'statusline'is adjustedproperly. Whenever this bufferis modified byaquickfix command or function, theb:changedtickvariableis incremented. You can get the number ofthis buffer using thegetqflist() andgetloclist()functions by passing the "qfbufnr" item. Foralocation list, this bufferis wiped out when thelocationlistis removed.:lop:lopen:lop[en][height]Openawindow to show the locationlist for thecurrent window. Works only when the locationlist forthe currentwindowis present. You can have more thanone locationwindow openedata time. Otherwise,itacts the sameas ":copen".:ccl:cclose:ccl[ose]Close thequickfix window.:lcl:lclose:lcl[ose]Close thewindow showing the locationlist for thecurrent window.:cw:cwindow:cw[indow][height]Open thequickfixwindow when there are recognizederrors. If thewindowis already open and there areno recognized errors, close the window.:lw:lwindow:lw[indow][height]Sameas ":cwindow", except use thewindow showing thelocationlist for the current window.:cbo:cbottom:cbo[ttom]Put the cursor in the last line of thequickfixwindowand scroll to makeit visible. Thisis useful forwhenerrors are added by an asynchronous callback.Only callit once ina while if there are manyupdates to avoida lot of redrawing.:lbo:lbottom:lbo[ttom]Sameas ":cbottom", except use thewindow showing thelocationlist for the current window.Normally thequickfixwindowisat the bottom of the screen. If there arevertical splits, it'sat the bottom of the rightmost column of windows. Tomakeit always occupy the full width::botright cwindowYou can move thewindow around withwindow-moving commands.For example, to moveit to the top:CTRL-WKThe'winfixheight' option will be set, which means that thewindow will mostlykeep its height, ignoring'winheight' and'equalalways'. You can change theheight manually (e.g., by dragging the status line aboveit with the mouse).In thequickfix window, each lineis one error. The line numberis equal tothe error number. The current entryis highlighted with the QuickFixLinehighlighting. You can changeit to your liking, e.g.::hi QuickFixLine ctermbg=Yellow guibg=YellowYou can use ":.cc" to jump to the error under the cursor.Hitting the<Enter> key or double-clicking the mouse ona line has the sameeffect. The file containing the erroris opened in thewindow above thequickfix window. If there alreadyisawindow for that file,itis usedinstead. If the buffer in the usedwindow has changed, and the erroris inanother file, jumping to the error will fail. You will first have to makesure thewindow containsa buffer which can be abandoned.When you selecta file from thequickfix window, the following steps are usedto findawindow to edit the file:1. Ifawindow displaying the selected fileis present in the currenttabpage (starting with thewindow before thequickfix window), then thatwindowis used.2. If the above step fails and if'switchbuf' contains "usetab" andawindow displaying the selected fileis present in any one of the tabpages (starting with the first tabpage) then thatwindowis used.3. If the above step fails thenawindow in the currenttabpage displayinga buffer with'buftype' not set (starting with thewindow before thequickfix window)is used.4. If the above step fails and if'switchbuf' contains "uselast", then the previously accessedwindowis used.5. If the above step fails then thewindow before thequickfixwindowis used. If thereis no previous window, then thewindow after thequickfixwindowis used.6. If the above step fails, thena new horizontally splitwindow above thequickfixwindowis used.CTRL-W_<Enter>CTRL-W_<CR>You can useCTRL-W<Enter> to opena newwindow and jump to the error there.When thequickfixwindow has been filled, twoautocommand events aretriggered. First the'filetype' optionis set to "qf", which triggers theFileType event (also seeqf.vim). Then theBufReadPost eventis triggered,using "quickfix" for the buffer name. This can be used to perform some actionon the listed errors. Example:au BufReadPost quickfix setlocal modifiable\ | silent exe 'g/^/s//\=line(".") .. " "/'\ | setlocal nomodifiableThis prepends the line number to each line.Note the use of "\=" in thesubstitutestring of the ":s" command, whichis used to evaluate anexpression.TheBufWinEnter eventis also triggered, again using "quickfix" for the buffername.Note: When adding to an existingquickfixlist theautocommand are nottriggered.Note: Making changes in thequickfixwindow has no effect on thelist oferrors.'modifiable'is off to avoid making changes. If you delete orinsertlines anyway, the relation between the text and the error numberis messed up.If you really want todo this, you could write the contents of thequickfixwindow toa file and use ":cfile" to haveit parsed and usedas the new errorlist.location-list-windowThe locationlistwindow displays the entries ina location list. When youopena locationlist window,itis created below the currentwindow anddisplays the locationlist for the current window. The locationlistwindowis similar to thequickfix window, except that you can have more than onelocationlistwindow openata time. When you usea locationlist command inthis window, the displayed locationlistis used.When you selecta file from the locationlist window, the following steps areused to findawindow to edit the file:1. Ifa non-quickfixwindow associated with the locationlistis present in the current tabpage, then thatwindowis used.2. If the above step fails and if the fileis already opened in anotherwindow in the current tabpage, then thatwindowis used.3. If the above step fails and'switchbuf' contains "usetab" and if the fileis opened inawindow in any one of the tabpages, then thatwindowis used.4. If the above step fails thenawindow in the currenttabpage showinga buffer with'buftype' not setis used.5. If the above step fails, then the fileis edited ina new window.In all of the above cases, if the locationlist for the selectedwindowis notyet set, thenitis set to the locationlist displayed in the locationlistwindow.quickfix-window-IDYou can use thegetqflist() andgetloclist()functions to obtain thewindow ID of thequickfixwindow and locationlistwindow respectively (ifpresent). Examples:echo getqflist({'winid' : 1}).winidecho getloclist(2, {'winid' : 1}).winidgetqflist-examplesThegetqflist() andgetloclist()functions can be used to get thevariousattributes ofaquickfix and locationlist respectively. Some examples forusing thesefunctions are below: " get the title of the current quickfix list :echo getqflist({'title' : 0}).title " get the identifier of the current quickfix list :let qfid = getqflist({'id' : 0}).id " get the identifier of the fourth quickfix list in the stack :let qfid = getqflist({'nr' : 4, 'id' : 0}).id " check whether a quickfix list with a specific identifier exists :if getqflist({'id' : qfid}).id == qfid " get the index of the current quickfix list in the stack :let qfnum = getqflist({'nr' : 0}).nr " get the items of a quickfix list specified by an identifier :echo getqflist({'id' : qfid, 'items' : 0}).items " get the number of entries in a quickfix list specified by an id :echo getqflist({'id' : qfid, 'size' : 0}).size " get the context of the third quickfix list in the stack :echo getqflist({'nr' : 3, 'context' : 0}).context " get the number of quickfix lists in the stack :echo getqflist({'nr' : '$'}).nr " get the number of times the current quickfix list is changed :echo getqflist({'changedtick' : 0}).changedtick " get the current entry in a quickfix list specified by an identifier :echo getqflist({'id' : qfid, 'idx' : 0}).idx " get all the quickfix list attributes using an identifier :echo getqflist({'id' : qfid, 'all' : 0}) " parse text from a List of lines and return a quickfix list :let myList = ["a.java:10:L10", "b.java:20:L20"] :echo getqflist({'lines' : myList}).items " parse text using a custom 'efm' and return a quickfix list :echo getqflist({'lines' : ['a.c#10#Line 10'], 'efm':'%f#%l#%m'}).items " get the quickfix list window id :echo getqflist({'winid' : 0}).winid " get the quickfix list window buffer number :echo getqflist({'qfbufnr' : 0}).qfbufnr " get the context of the current location list :echo getloclist(0, {'context' : 0}).context " get the location list window id of the third window :echo getloclist(3, {'winid' : 0}).winid " get the location list window buffer number of the third window :echo getloclist(3, {'qfbufnr' : 0}).qfbufnr " get the file window id of a location list window (winnr: 4) :echo getloclist(4, {'filewinid' : 0}).filewinidsetqflist-examplesThesetqflist() andsetloclist()functions can be used to set thevariousattributes ofaquickfix and locationlist respectively. Some examples forusing thesefunctions are below: " create an empty quickfix list with a title and a context :let t = 'Search results' :let c = {'cmd' : 'grep'} :call setqflist([], ' ', {'title' : t, 'context' : c}) " set the title of the current quickfix list :call setqflist([], 'a', {'title' : 'Mytitle'}) " change the current entry in the list specified by an identifier :call setqflist([], 'a', {'id' : qfid, 'idx' : 10}) " set the context of a quickfix list specified by an identifier :call setqflist([], 'a', {'id' : qfid, 'context' : {'val' : 100}}) " create a new quickfix list from a command output :call setqflist([], ' ', {'lines' : systemlist('grep -Hn main *.c')}) " parse text using a custom efm and add to a particular quickfix list :call setqflist([], 'a', {'id' : qfid,\ 'lines' : ["a.c#10#L10", "b.c#20#L20"], 'efm':'%f#%l#%m'}) " add items to the quickfix list specified by an identifier :let newItems = [{'filename' : 'a.txt', 'lnum' : 10, 'text' : "Apple"}, \ {'filename' : 'b.txt', 'lnum' : 20, 'text' : "Orange"}] :call setqflist([], 'a', {'id' : qfid, 'items' : newItems}) " empty a quickfix list specified by an identifier :call setqflist([], 'r', {'id' : qfid, 'items' : []}) " free all the quickfix lists in the stack :call setqflist([], 'f') " set the title of the fourth quickfix list :call setqflist([], 'a', {'nr' : 4, 'title' : 'SomeTitle'}) " create a new quickfix list at the end of the stack :call setqflist([], ' ', {'nr' : '$',\ 'lines' : systemlist('grep -Hn class *.java')}) " create a new location list from a command output :call setloclist(0, [], ' ', {'lines' : systemlist('grep -Hn main *.c')}) " replace the location list entries for the third window :call setloclist(3, [], 'r', {'items' : newItems})=============================================================================3. Using more than onelist oferrorsquickfix-error-listsSo farit has been assumed that thereis only onelist of errors. Actuallythere can be multiple used lists that are remembered; see'chistory' and'lhistory'.Whenstartinga new list, the previous ones are automatically kept. Twocommands can be used to access older error lists. They set one of theexisting error listsas the current one.:colder:colE380:col[der][count]Go to older error list. When[count]is given,dothis[count] times. When alreadyat the oldest errorlist, an error messageis given.:lolder:lol:lol[der][count]Sameas:colder, except use the locationlist forthe currentwindow instead of thequickfix list.:cnewer:cnewE381:cnew[er][count]Go to newer error list. When[count]is given,dothis[count] times. When alreadyat the newest errorlist, an error messageis given.:lnewer:lnew:lnew[er][count]Sameas:cnewer, except use the locationlist forthe currentwindow instead of thequickfix list.:chistory:chi:[count]chi[story]Show thelist of error lists. The currentlistismarked with ">". The output looks like: error list 1 of 3; 43 errors :make> error list 2 of 3; 0 errors :helpgrep tag error list 3 of 3; 15 errors :grep ex_help *.cWhen[count]is given, then the count'thquickfixlistis made the current list. Example:" Make the 4th quickfix list current:4chistory:lhistory:lhi:[count]lhi[story]Show thelist of location lists, otherwise like:chistory.When addinga new error list,it becomes the current list.When ":colder" has been used and ":make" or ":grep"is used to adda new errorlist, one newerlistis overwritten. Thisis especially useful if you arebrowsing with ":grep"grep. If you want to keep the more recent errorlists, use ":cnewer 99" first.To get the number of lists in thequickfix and locationlist stack, you canuse thegetqflist() andgetloclist()functions respectively with thelistnumber set to the special value '$'. Examples:echo getqflist({'nr' : '$'}).nrecho getloclist(3, {'nr' : '$'}).nrTo get the number of the currentlist in the stack:echo getqflist({'nr' : 0}).nr=============================================================================4. Using:make:make_makeprg:mak:make:mak[e][!][arguments]1. All relevantQuickFixCmdPreautocommands are executed.2. If the'autowrite' optionis on, write any changedbuffers3. An errorfile nameis made from'makeef'. If'makeef' doesn't contain "##", anda file with this name already exists,itis deleted.4. The program given with the'makeprg' optionis started (default "make") with the optional[arguments] and the outputis saved in the errorfile (forUnixitis also echoed on the screen).5. The errorfileis read using'errorformat'.6. All relevantQuickFixCmdPostautocommands are executed. See example below.7. If [!]is not given the first erroris jumped to.8. The errorfileis deleted.9. You can now move through theerrors with commands like:cnext and:cprevious, see above.This command does not accepta comment, any "characters are considered part of the arguments.If the encoding of the program output differs from the'encoding' option, you can use the'makeencoding'option to specify the encoding.:lmak:lmake:lmak[e][!][arguments]Sameas ":make", except the locationlist for thecurrentwindowis used instead of thequickfix list.The ":make" command executes the command given with the'makeprg' option.Thisis done by passing the command to the shell given with the'shell'option. This works almost like typing":!{makeprg}[arguments]{shellpipe}{errorfile}".{makeprg}is thestring given with the'makeprg' option. Any command can beused, not just "make". Characters '%' and '#' are expandedas usual onacommand-line. You can use "%<" toinsert the current file name withoutextension, or "#<" toinsert the alternate file name without extension, forexample: :set makeprg=make\ #<.o[arguments]is anything thatis typed after ":make".{shellpipe}is the'shellpipe' option.{errorfile}is the'makeef' option, with ## replaced to makeit unique.The placeholder "$*" can be used for the argumentlist in{makeprg} if thecommand needs some additional characters after its arguments. The$*isreplaced then by all arguments. Example: :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}or simpler :let &mp = 'latex \\nonstopmode \\input\{$*}'"$*" can be given multiple times, for example: :set makeprg=gcc\ -o\ $*\ $*The'shellpipe' option defaults to ">" for theAmiga and ">%s 2>&1" for Win32.This means that the output of the compileris saved ina file and not shown onthe screen directly. ForUnix "| tee"is used. The compiler outputis shownon the screen and saved ina file the same time. Depending on the shell used"|& tee" or "2>&1| tee"is the default, so stderr output will be included.If'shellpipe'is empty, the{errorfile} part will be omitted. Thisis usefulfor compilers that write to an errorfile themselves (e.g., Manx'sAmiga C).Using QuickFixCmdPost to fix the encodingIt may be that'encoding'is set to an encoding that differs from themessagesyour build program produces. This example shows how to fix this after Vim hasread the error messages:function QfMakeConv() let qflist = getqflist() for i in qflist let i.text = iconv(i.text, "cp936", "utf-8") endfor call setqflist(qflist)endfunctionau QuickfixCmdPost make call QfMakeConv()(Example by Faque Cheng)Another optionis using'makeencoding'.==============================================================================5. Using:vimgrep and:grepgreplidVim has two ways to find matches fora pattern: internal and external. Theadvantage of the internalgrepis thatit works on all systems and uses thepowerful Vim search patterns. An externalgrep program can be used when theVimgrep does notdo what you want.The internalmethod will be slower, because files are read into memory. Theadvantages are:- Line separators and encoding are automatically recognized,as ifa fileis being edited.- Uses Vim search patterns. Multi-line patterns can be used.- When plugins are enabled: compressed and remote files can be searched.gzipnetrwTo be able todo this Vim loads each fileas ifitis being edited. Whenthereis no match in the file the associated bufferis wiped out again. The'hidden' optionis ignored here to avoid running out of memory or filedescriptors when searching many files. However, when the:hide commandmodifieris used thebuffers are kept loaded. This makes following searchesin the same filesa lot faster.Note that:copen (or:lopen for:lgrep) may be used to opena buffercontaining the search results in linked form. The:silent command may beused to suppress the default full screengrep output. The ":grep!" form ofthe:grep command doesn't jump to the first match automatically. Thesecommands can be combined to createa NewGrep command: command! -nargs=+ NewGrep execute 'silent grep! <args>' | copen 425.1 Using Vim's internalgrep:vim:vimgrepE682E683:vim[grep][!] /{pattern}/[g][j][f]{file}...Search for{pattern} in the files{file}... and setthe errorlist to the matches. Files matching'wildignore' are ignored; files in'suffixes' aresearched last.{pattern}isa Vim search pattern. Instead ofenclosingit in/ any non-ID character (see'isident') can be used, so longasit does notappear in{pattern}.'ignorecase' applies. To overruleitput/\c in thepattern to ignorecase or/\C to match case.'smartcase'is not used.If{pattern}is empty (e.g.//is specified), the lastused searchpatternis used.last-patternFlags:'g' Without the 'g' flag each lineis added only once. With 'g' every matchis added.'j' Without the 'j' flag Vim jumps to the first match. With 'j' only thequickfixlistis updated. With the [!] any changes in the current buffer are abandoned.'f' When the 'f' flagis specified, fuzzystring matchingis used to find matching lines. In this case,{pattern}is treatedasa literalstring instead ofa regular expression. Seefuzzy-matching for more information about fuzzy matching strings.QuickFixCmdPre andQuickFixCmdPost are triggered.A file thatis opened for matching may usea buffernumber, butitis reused if possible to avoidconsuming buffer numbers.:{count}vim[grep]...Whena numberisput before the command thisis usedas the maximum number of matches to find. Use":1vimgreppattern file" to find only the first.Useful if you only want to check if thereisa matchand quit quickly when it's found.Every second or so the searched file nameis displayedto give you an idea of the progress made.Examples::vimgrep /an error/ *.c:vimgrep /\<FileName\>/ *.h include/*:vimgrep /myfunc/ **/*.cFor the use of "**" seestarstar-wildcard.:vim[grep][!]{pattern}{file}...Like above, but instead of enclosing thepattern inanon-ID character usea whitespace separated pattern.Thepatternmust start with an ID character.Example::vimgrep Error *.c:lv:lvimgrep:lv[imgrep][!] /{pattern}/[g][j][f]{file}...:lv[imgrep][!]{pattern}{file}...Sameas ":vimgrep", except the locationlist for thecurrentwindowis used instead of thequickfix list.:vimgrepa:vimgrepadd:vimgrepa[dd][!] /{pattern}/[g][j][f]{file}...:vimgrepa[dd][!]{pattern}{file}...Just like ":vimgrep", but instead of makinga newlistoferrors the matches are appended to the currentlist.:lvimgrepa:lvimgrepadd:lvimgrepa[dd][!] /{pattern}/[g][j][f]{file}...:lvimgrepa[dd][!]{pattern}{file}...Sameas ":vimgrepadd", except the locationlist forthe currentwindowis used instead of thequickfixlist.5.2 ExternalgrepVim can interface with "grep" and grep-like programs (suchas the GNUid-utils) ina similar way to its compiler integration (see:make above).[Unix trivia: The name for theUnix "grep" command comes from ":g/re/p", where"re" stands for Regular Expression.]:gr:grep:gr[ep][!][arguments]Just like ":make", but use'grepprg' instead of'makeprg' and'grepformat' instead of'errorformat'.When'grepprg'is "internal" this works like:vimgrep.Note that thepattern needs to beenclosed in separator characters then.If the encoding of the program output differs from the'encoding' option, you can use the'makeencoding'option to specify the encoding.:lgr:lgrep:lgr[ep][!][arguments]Sameas ":grep", except the locationlist for thecurrentwindowis used instead of thequickfix list.:grepa:grepadd:grepa[dd][!][arguments]Just like ":grep", but instead of makinga newlist oferrors the matches are appended to the current list.Example::call setqflist([]):bufdo grepadd! something %The first command makesa new errorlist whichisempty. The second command executes "grepadd" for eachlisted buffer.Note the use of! to avoid that":grepadd" jumps to the first error, whichis notallowed with:bufdo.An example that uses the argumentlist and avoidserrors for files without matches::silent argdo try \ | grepadd! something % \ | catch /E480:/ \ | endtry"If the encoding of the program output differs from the'encoding' option, you can use the'makeencoding'option to specify the encoding.:lgrepa:lgrepadd:lgrepa[dd][!][arguments]Sameas ":grepadd", except the locationlist for thecurrentwindowis used instead of thequickfix list.5.3 Setting up externalgrepIf you havea standard "grep" program installed, the:grep command may workwell with the defaults. Thesyntaxis very similar to the standard command::grep foo *.cWill search all files with the .c extension for thesubstring "foo". Thearguments to:grep are passed straight to the "grep" program, so you can usewhateveroptions your "grep" supports.By default,:grep invokesgrep with the-n option (show file and linenumbers). You can change this with the'grepprg' option. You will need to set'grepprg' if:a)You are usinga program that isn't called "grep"b)You have to callgrep witha full pathc)You want to pass otheroptions automatically (e.g.case insensitivesearch.)Once "grep" has executed, Vim parses the results using the'grepformat'option. This option works in the same wayas the'errorformat' option- seethat for details. You may need to change'grepformat' from the default ifyourgrep outputs ina non-standard format, or you are using some otherprogram witha special format.Once the results are parsed, Vim loads the first file containinga match andjumps to the appropriate line, in the same way thatit jumps toa compilererror inquickfix mode. You can then use the:cnext,:clist, etc.commands to see the other matches.5.4 Using:grep with id-utilsYou can set up:grep to work with the GNU id-utils like this::set grepprg=lid\ -Rgrep\ -s:set grepformat=%f:%l:%mthen:grep (regexp)works justas you'd expect.(provided you remembered to mkid first :)5.5 Browsing source code with:vimgrep or:grepUsing the stack of error lists that Vim keeps, you can browse your files tolook forfunctions and thefunctions they call. For example, suppose that youhave to add an argument to the read_file() function. You enter this command::vimgrep /\<read_file\>/ *.cYou use ":cn" togo along thelist of matches and add the argument. At oneplace you have to get the new argument froma higher level function msg(), andneed to change that one too. Thus you use::vimgrep /\<msg\>/ *.cWhilechanging the msg() functions, you find another function that needs toget the argument froma higher level. You can again use ":vimgrep" to findthese functions. Once you are finished with one function, you can use:coldertogo back to the previous one.This works like browsinga tree: ":vimgrep" goes one level deeper, creatingalist of branches. ":colder" goes back to the previous level. You can mixthis use of ":vimgrep" and "colder" to browse all the locations ina tree-likeway. If youdo this consistently, you will find all locations without theneed to write downa "todo" list.=============================================================================6. Selectinga compilercompiler-select:comp:compilerE666:comp[iler][!]{name}Setoptions to work with compiler{name}.Without the "!"options are set for thecurrent buffer. With "!" globaloptions areset.If you use ":compiler foo" in "file.foo" andthen ":compiler!bar" in another buffer, Vimwill keep on using "foo" in "file.foo".{not available when compiled without the+eval feature}The Vim plugins in the "compiler" directory will setoptions to use theselected compiler. For:compiler localoptions are set, for:compiler!global options.current_compilerTo support older Vim versions, the plugins always use "current_compiler" andnot "b:current_compiler". What the command actually doesis the following:- Delete the "current_compiler" and "b:current_compiler" variables.- Define the "CompilerSet" user command. With "!"it does ":set", without "!"it does ":setlocal".- Execute ":runtime! compiler/{name}.vim". The plugins are expected to setoptions with "CompilerSet" and set the "current_compiler" variable to the name of the compiler.- Delete the "CompilerSet" user command.- Set "b:current_compiler" to the value of "current_compiler".- Without "!" the old value of "current_compiler"is restored.Forwritinga compiler plugin, seewrite-compiler-plugin.Use thecompiler-makeplugin toundo the effect ofa compiler plugin.CPPCHECKquickfix-cppcheckcompiler-cppcheckUse g/b:`c_cppcheck_params` to set cppcheck parameters. The globalsettings by default include---verbose: Enablesverbose output.---force: Forces checking of all configurations.---inline-suppr: Allows inline suppressions.---enable=...: Enables specific checks like warnings, style, performance, portability, information, and missing includes.--j: Utilizes multiple processors if available, determined by thegetconf command if available (requires omitting the unusedFunction check)For C++ files (`filetype=='cpp'`), the--language=c++ optionis added toensure Cppcheck treats the fileas C++.If compile_commands.jsonis present in the current directory,itis addedasa--project parameter to the command line. Otherwise, by default thedirectories in &path are passedas include directories. These can be set byg/b:`c_cppcheck_includes`asalist of-I flags. Tim Pope's vim-apathyplug-in [0] can expand &path. To also append the folders ina git repo use let &l:path = join(systemlist('git ls-tree -d --name-only -r HEAD'), ',')[0]https://github.com/tpope/vim-apathyDOTNETcompiler-dotnetThe .NET CLI compiler outputs botherrors and warnings by default. The outputmay be limited to include only errors, by setting the g:dotnet_errors_onlyvariable tov:true.The associated project nameis included in each error and warning. To suppressthe project name, set the g:dotnet_show_project_file variable tov:false.Example: limit output to only display errors, and suppress the project name:let dotnet_errors_only = v:truelet dotnet_show_project_file = v:falsecompiler dotnetGCCquickfix-gcccompiler-gccThere's one variable you can set for the GCC compiler:g:compiler_gcc_ignore_unmatched_linesIgnore lines that don't match any patternsdefined for GCC. Useful if output fromcommands run from make are generatingfalsepositives.JAVACcompiler-javacCommonly used compileroptions can be added to'makeprg' by setting theb/g:javac_makeprg_params variable. For example:let g:javac_makeprg_params = "-Xlint:all -encoding utf-8"MAVENcompiler-mavenCommonly used compileroptions can be added to'makeprg' by setting theb/g:maven_makeprg_params variable. For example:let g:maven_makeprg_params = "-DskipTests -U -X"SPOTBUGScompiler-spotbugsSpotBugsisa static analysis tool that can be used to findbugs in Java.It scans the Java bytecode of all classes in the currently open buffer.(Therefore, `:compiler! spotbugs`is not supported.)Commonly used compileroptions can be added to'makeprg' by setting the"b:" or "g:spotbugs_makeprg_params" variable. For example:let b:spotbugs_makeprg_params = "-longBugCodes -effort:max -low"The global defaultis "-workHard -experimental".By default, theclass files are searched in the directory where the sourcefiles are placed. However, typical Java projects use distinct directoriesfor source files andclass files. To make both known to SpotBugs, assigntheir paths (distinct and relative to their common root directory) to thefollowing properties (using the example ofa common Maven project):let g:spotbugs_properties = {\ 'sourceDirPath':['src/main/java'],\ 'classDirPath':['target/classes'],\ 'testSourceDirPath':['src/test/java'],\ 'testClassDirPath':['target/test-classes'],\ }Note that source andclass path entries are expected to come in pairs: defineboth "sourceDirPath" and "classDirPath" when you are consideringat least one,and apply the same logic to "testSourceDirPath" and "testClassDirPath".Note that values for the path keys describe only for SpotBugs where to lookfor files; refer to the documentation for particular compiler plugins for moreinformation.The default pre- and post-compiler actions are provided for Ant, Maven, andJavac compiler plugins and can be selected by assigning the name ofa compilerplugin (`ant`,maven, orjavac) to the "compiler" key:let g:spotbugs_properties = {\ 'compiler':'maven',\ }This single settingis essentially equivalent to all the settings below, withthe exception made for the "PreCompilerAction" and "PreCompilerTestAction"values: their listedFuncrefs will obtain no-op implementations whereas theimplicit Funcrefs of the "compiler" key will obtain the requested defaults ifavailable.let g:spotbugs_properties = {\ 'PreCompilerAction':\ function('spotbugs#DefaultPreCompilerAction'),\ 'PreCompilerTestAction':\ function('spotbugs#DefaultPreCompilerTestAction'),\ 'PostCompilerAction':\ function('spotbugs#DefaultPostCompilerAction'),\ 'sourceDirPath':['src/main/java'],\ 'classDirPath':['target/classes'],\ 'testSourceDirPath':['src/test/java'],\ 'testClassDirPath':['target/test-classes'],\ }With default actions, the compiler of choice will attempt to rebuild theclassfiles for the buffer (and possibly for the whole project)as soonasa Javasyntax fileis loaded; then,spotbugs will attempt to analyze the quality ofthe compilation unit of the buffer.Vim commands proficient in'makeprg' [0] can be composed with default actions.Begin by considering which of the supported keys, "DefaultPreCompilerCommand","DefaultPreCompilerTestCommand", or "DefaultPostCompilerCommand", you need towrite an implementation for, observing that each of these keys corresponds toa particular "*Action" key. Followit by defininga new function that alwaysdeclares an only parameter of typestring and puts to usea command equivalentof:make, and assigning itsFuncref to the selected key. For example:function! GenericPostCompilerCommand(arguments) abortexecute 'make ' . a:argumentsendfunctionlet g:spotbugs_properties = {\ 'DefaultPostCompilerCommand':\ function('GenericPostCompilerCommand'),\ }When "PostCompilerAction"is available, "PostCompilerActionExecutor"is alsosupported. Its valuemust beaFuncref pointing toa function that alwaysdeclaresa single parameter of typestring and decides whether:execute canbe dispatched on its argument, containinga pending post-compiler action,after ascertaining the current status of:cc (or:ll):function! GenericPostCompilerActionExecutor(action) aborttrycccatch /\<E42:/execute a:actionendtryendfunctionComplementary, some or all of the available "Pre*Action"s (or "*Pre*Command"s)may run `:doautocmd java_spotbugs_post User` in their implementations before:make (or its equivalent) to definea once-onlyShellCmdPost:autocmdthat will arrange for "PostCompilerActionExecutor" to be invoked; and then run`:doautocmd java_spotbugs_post ShellCmdPost` to consume this event:function! GenericPreCompilerCommand(arguments) abortif !exists('g:spotbugs_compilation_done')doautocmd java_spotbugs_post Userexecute 'make ' . a:arguments" only run doautocmd when :make was synchronous" see note belowdoautocmd java_spotbugs_post ShellCmdPost " XXX: (a)let g:spotbugs_compilation_done = 1elseccendifendfunctionfunction! GenericPreCompilerTestCommand(arguments) abortif !exists('g:spotbugs_test_compilation_done')doautocmd java_spotbugs_post Userexecute 'make ' . a:arguments" only run doautocmd when :make was synchronous" see note belowdoautocmd java_spotbugs_post ShellCmdPost " XXX: (b)let g:spotbugs_test_compilation_done = 1elseccendifendfunctionlet g:spotbugs_properties = {\ 'compiler':'maven',\ 'DefaultPreCompilerCommand':\ function('GenericPreCompilerCommand'),\ 'DefaultPreCompilerTestCommand':\ function('GenericPreCompilerTestCommand'),\ 'PostCompilerActionExecutor':\ function('GenericPostCompilerActionExecutor'),\ }Ifa command equivalent of:makeis capable of asynchronous execution andconsumingShellCmdPost events, `:doautocmd java_spotbugs_post ShellCmdPost`must be removed from such "*Action" (or "*Command") implementations (i.e. thelines(a) and(b) in the listed examples) to retaina sequential order fornon-blocking execution, and any notification (see below)must be suppressed.AShellCmdPost:autocmd can be associated with any:augroup by assigningits name to the "augroupForPostCompilerAction" key.When default actions are not suited toa desired workflow, proceed bywritingarbitraryfunctions yourself and matching their Funcrefs to the supportedkeys: "PreCompilerAction", "PreCompilerTestAction", and "PostCompilerAction".The next example re-implements the default pre-compiler actions fora Mavenproject and requests other default Maven settings with the "compiler" entry:function! MavenPreCompilerAction() abortcall spotbugs#DeleteClassFiles()compiler mavenmake compileccendfunctionfunction! MavenPreCompilerTestAction() abortcall spotbugs#DeleteClassFiles()compiler mavenmake test-compileccendfunctionlet g:spotbugs_properties = {\ 'compiler':'maven',\ 'PreCompilerAction':\ function('MavenPreCompilerAction'),\ 'PreCompilerTestAction':\ function('MavenPreCompilerTestAction'),\ }Note that all entered custom settings will take precedence over the matchingdefault settings in "g:spotbugs_properties".Note thatitis necessary to notify theplugin of the result ofa pre-compileraction before further work can be undertaken. Using:cc after:make (or:ll after:lmake)as the last command of an actionis the supported meansof such communication.Two commands, "SpotBugsRemoveBufferAutocmd" and "SpotBugsDefineBufferAutocmd",are provided totoggle actions for buffer-local autocommands. For example, toalso run actions on anyBufWritePost andSigUSR1 event, add these lines to~/.vim/after/ftplugin/java.vim:if exists(':SpotBugsDefineBufferAutocmd') == 2SpotBugsDefineBufferAutocmd BufWritePost SigUSR1endifOtherwise, you can turn to `:doautocmd java_spotbugs User`at any time.The "g:spotbugs_properties" variableis consulted by the Javafiletypeplugin(ft-java-plugin) to arrange for the described automation, and, therefore,itmust be defined beforeFileType events can take place for thebuffers loadedwith Java source files. It could, for example, be set ina project-localvimrc loaded by [1].Both "g:spotbugs_properties" and "b:spotbugs_properties" are recognized andmust be modifiable(:unlockvar). The "*Command" entries are always treatedas globalfunctions to be shared among all Java buffers.The SpotBugs Java library and, by extension, its distributed shell scriptsdonot support in the-textui mode listed pathnames with directory filenamesthat contain blank characters [2]. To work around this limitation, considermakinga symbolic link to sucha directory froma directory that does not haveblank characters in its name and passing this information to SpotBugs:let g:spotbugs_alternative_path = {\ 'fromPath':'path/to/dir_without_blanks',\ 'toPath':'path/to/dir with blanks',\ }[0]https://github.com/Konfekt/vim-compilers[1]https://github.com/MarcWeber/vim-addon-local-vimrc[2]https://github.com/spotbugs/spotbugs/issues/909GNU MAKEcompiler-makeSince the default make programis "make", the compilerplugin for make,:compiler make, will reset the'makeprg' and'errorformat' option tothe default values and unlet anyvariables that may have been set byaprevious compiler plugin.MANX AZTEC Cquickfix-manxcompiler-manxTo use Vim with Manx's AztecC compiler on theAmiga you shoulddo thefollowing:- Set the CCEDIT environment variable with the command:mset "CCEDIT=vim -q"- Compile with the-qf option. If the compiler finds any errors, Vimis started and the cursoris positioned on the first error. The error message will be displayed on the last line. You cango to othererrors with the commands mentioned above. You can fix theerrors and write the file(s).- If you exit Vim normally the compiler will re-compile the same file. If you exit with the:cq command, the compiler will terminate. Do this if you cannot fix the error, or if another file needs to be compiled first.There are some restrictions to theQuickfix mode on the Amiga. Thecompiler only writes the first 25errors to the errorfile (Manx'sdocumentation does not say how to get more). If you want to find the others,you will have to fixa fewerrors and exit the editor. After recompiling,up to 25 remainingerrors will be found.If Vim was started from the compiler, the:sh and some:! commands will notwork, because Vimis then running in the same processas the compiler andstdin (standard input) will not be interactive.GROFFquickfix-groffcompiler-groffThe GROFF compilerplugin uses the mommacro set (documented in the groff_mommanpage)as input and expects that the output file type extensionis passed tomake, say:make html or:make pdf.Additional arguments can be passed to groff by setting them inb:groff_compiler_args org:groff_compiler_args. Thelanguage argumentpassed to groffis set using'spelllang';it can be overridden by settingb:groff_compiler_lang. The default encodingisUTF-8 and can be changedby settingb:groff_compiler_encoding org:groff_compiler_encoding.PANDOCquickfix-pandoccompiler-pandocThe Pandoc compilerplugin expects that an output file type extensionispassed to make, say:make html or:make pdf.Additional arguments can be passed to pandoc:- either by appending them to make, say `:make html --self-contained`.- or setting them inb:pandoc_compiler_args org:pandoc_compiler_args.The--from argumentis an educated guess using the buffer file type;it can be overridden by settingb:pandoc_compiler_from.The `--metadata lang` argumentis set using'spelllang';If--from=markdownis assumed and no title set ina title header orYAML block, then the filename (without extension)is usedas the title.PERLquickfix-perlcompiler-perlThePerl compilerplugin doesn't actually compile, but invokes Perl's internalsyntax checking feature and parses the output for possibleerrors so you cancorrect them in quick-fix mode.Warnings are forced regardless of "no warnings" or "$^W=0" within the filebeing checked. To disable this set g:perl_compiler_force_warnings toa zerovalue. For example:let g:perl_compiler_force_warnings = 0MYPY TYPE CHECKERcompiler-mypyCommonly used compileroptions can be added to'makeprg' by setting theb/g:mypy_makeprg_params variable. For example:let b:mypy_makeprg_params = "--warn-unused-ignores"The global defaultis "--strict --ignore-missing-imports".RUFF LINTERcompiler-ruffCommonly used compileroptions can be added to'makeprg' by setting theb/g:ruff_makeprg_params variable. For example:let b:ruff_makeprg_params = "--max-line-length "..&textwidthThe global defaultis "--preview".PYLINT LINTERcompiler-pylintCommonly used compileroptions can be added to'makeprg' by setting theb/g:pylint_makeprg_params variable. For example:let b:pylint_makeprg_params = "--max-line-length "..&textwidthThe global defaultis "--jobs=0" to use (almost) all cores.PYUNIT COMPILERcompiler-pyunitThisis not actuallya compiler, buta unittesting framework for thePython language. Itis included into standardPythondistributionstarting from version 2.0. For older versions, you can getit fromhttp://pyunit.sourceforge.net.When you run your tests with thehelp of the framework, possibleerrorsare parsed by Vim and presented for you in quick-fix mode.Unfortunately, thereis no standard way to run the tests.The alltests.pyscript seems to be used quite often, that's all.Useful values for the'makeprg'options therefore are: setlocal makeprg=./alltests.py " Runa testsuite setlocal makeprg=python\%:S " Runa single testcaseAlso seehttp://vim.sourceforge.net/tip_view.php?tip_id=280.PYTEST COMPILERcompiler-pytestCommonly used compileroptions can be added to'makeprg' by setting theb/g:pytest_makeprg_params variable. For example: let b:pytest_makeprg_params = "--verbose --no-summary --disable-warnings"The global defaultis "--tb=short --quiet";Python warnings are suppressed.TEX COMPILERcompiler-texIncluded in thedistribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim)uses make command if possible. If the compiler findsa file named "Makefile"or "makefile" in the current directory,it supposes that you want to processyour *TeX files with make, and the makefile does the right work. In thiscasecompiler sets'errorformat' for *TeX output and leaves'makeprg' untouched. Ifneither "Makefile" nor "makefile"is found, the compiler will not use make.You can force the compiler to ignore makefiles by definingb:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked forexistence only).If the compiler chose not to use make,it needs to choosea right program forprocessing your input. If b:tex_flavor org:tex_flavor (in this precedence)variable exists,it defines TeX flavor for:make (actually, thisis the nameof executed command), and if bothvariablesdo not exist,it defaults to"latex". For example, while editing chapter2.tex \input-ed from mypaper.texwritten in AMS-TeX::let b:tex_flavor = 'amstex':compiler tex[editing...]:make mypaperNote that youmust specifya name of the file to processas an argument (toprocess the right file when editing \input-ed or \include-ed file; portablesolution for substituting% for no argumentsis welcome). Thisis not in thesemantics of make, where you specifya target, not source, but you may specifyfilename without extension ".tex" and mean thisas "make filename.dvi orfilename.pdf or filename.some_result_extension according to compiler".Note: tex command linesyntaxis set to usable both for MikTeX (suggestionby Srinath Avadhanula) and teTeX (checked by Artem Chuprina). Suggestionfromerrorformat-LaTeXis too complex to keepit working for differentshells and OSes and also does not allow to use other available TeX options,if any. If your TeX doesn't support "-interaction=nonstopmode", pleasereportit with different means to express \nonstopmode from the command line.TSC COMPILERcompiler-tscThe executable and compileroptions can be added to'makeprg' by setting theb/g:tsc_makeprg variable. For example:let b:tsc_makeprg = "npx tsc --noEmit"TYPST COMPILERcompiler-typstVim includesa compilerplugin for Typst files. This compileris enabledautomatically in Typstbuffers by the Typstfiletypepluginft-typst-plugin.Run:make to compile the current Typst file.g:typst_cmdBy default Vim will use "typst"as the command to run the Typst compiler. Thiscan be changed by setting theg:typst_cmd variable:let g:typst_cmd = "/path/to/other/command"=============================================================================7. The error formaterror-file-formaterrorformatE372E373E374E375E376E377E378The'errorformat' optionspecifiesalist of formats that are recognized. Thefirst format that matches with an error messageis used. You can add severalformats for differentmessages your compiler produces, or even entries formultiple compilers. Seeefm-entries.Each entry in'errorformat'isa scanf-likestring that describes the format.First, you need to know how scanf works. Look in the documentation of yourC compiler. Below you find the% items that Vim understands. Others areinvalid.Special characters in'errorformat' are comma and backslash. Seeefm-entries for how to deal with them.Note thata literal "%"is matchedby "%%", thusitis not escaped witha backslash.Keep in mind that in the:make and:grep output all NUL characters arereplaced with SOH (0x01).Note: By default the difference between upper andlowercaseis ignored. Ifyou want to match case, add "\C" to thepattern/\C.Vim will read lines of any length, but only the first 4095 bytes are used, therestis ignored. Items can only be 1023 bytes long.Basic items%ffile name (findsa string)%bbuffer number (findsa number)%omodule name (findsa string)%lline number (findsa number)%eend line number (findsa number)%ccolumn number (findsa number representing charactercolumn of the error, byte index,a<tab>is 1character column)%vvirtual column number (findsa number representingscreen column of the error (1<tab>== 8 screencolumns))%kend column number (findsa number representingthe character column of the error, byte index, oranumber representing screenend column of the error ifit's used with %v)%terror type (findsa single character):e- error messagew- warning messagei- info messagen-note message%nerror number (findsa number)%merror message (findsa string)%rmatches the "rest" ofa single-line file message %O/P/Q%ppointer line (findsa sequence of '-', '.','' ortabs and uses the length for the column number)%*{conv}any scanf non-assignable conversion%%the single '%' character%ssearch text (findsa string)The "%f" conversion may depend on the current'isfname' setting. "~/"isexpanded to thehome directory and environmentvariables are expanded.The "%f" and "%m" conversions have to detect theend of the string. Thisnormally happens by matching following characters and items. When nothingisfollowing the rest of the lineis matched. If "%f"is followed bya '%' orabackslash,it will look fora sequence of'isfname' characters.OnMS-Windowsa leading "C:" will be included in "%f", even when using "%f:".This means thata file name whichisa single alphabeticalletter will not bedetected.The "%b" conversionis used to parsea buffer number. Thisis useful forreferring to lines ina scratch buffer ora buffer with no name. Ifa bufferwith the matching number doesn't exist, then that lineis usedasa non-errorline.The "%p" conversionis normally followed bya "^". It's used for compilersthat outputa line like: ^or ---------^to indicate the column of the error. Thisis to be used ina multi-line errormessage. Seeerrorformat-javac fora useful example.The "%s" conversionspecifies the text to search for, to locate the error line.The textis usedasa literal string. The anchors "^" and "$" are added tothe text to locate the error line exactly matching the search text and thetextis prefixed with the "\V" atom to makeit "very nomagic". The "%s"conversion can be used to locate lines withouta line number in the erroroutput. Like the output of the "grep" shell command.When thepatternis present the line number will not be used.The "%o" conversionspecifies the module name inquickfix entry. If presentit will be used inquickfix errorwindow instead of the filename. The modulenameis used only for displaying purposes, the file nameis used when jumpingto the file.Changing directoryThe followinguppercase conversion characters specify the type of specialformat strings. At most one of them may be givenasa prefixat the beginningofa single comma-separated format pattern.Some compilers producemessages that consist of directory names that have tobe prepended to each file name read by %f (example: GNU make). The followingcodes can be used to scan these directory names; they will be stored in aninternal directory stack.E379%D"enter directory" format string; expectsa following %f that finds the directory name%X"leave directory" format string; expects following %fWhen defining an "enter directory" or "leave directory" format, the "%D" or"%X" has to be givenat the start of that substring. Vim tracks the directorychanges and prepends the current directory to each erroneous file found witharelative path. Seequickfix-directory-stack for details,tips andlimitations.Multi-linemessageserrorformat-multi-lineItis possible to read the output of programs that produce multi-linemessages, i.e. error strings that consume more than one line. Possibleprefixes are:%Estart ofa multi-line error message%Wstart ofa multi-line warning message%Istart ofa multi-line informational message%Nstart ofa multi-linenote message%Astart ofa multi-line message (unspecified type)%>for next line start with currentpattern againefm-%>%Ccontinuation ofa multi-line message%Zend ofa multi-line messageThese can be used with '+' and '-', seeefm-ignore below.Using "\n" in thepattern won't work to match multi-line messages.Example: Your compiler happens to write outerrors in the following format(leading line numbers not being part of the actual output): 1Error 275 2line 42 3column 3 4' ' expected after '--'The appropriate error formatstring has to look like this: :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%mAnd the:clist error message generated for this error is: 1:42 col 3 error 275:'' expected after '--'Another example: Think ofaPython interpreter that produces the followingerror message (line numbers are not part of the actual output): 1============================================================== 2FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest) 3-------------------------------------------------------------- 4Traceback (most recent call last): 5 File "unittests/dbfacadeTest.py", line 89, in testFoo 6 self.assertEquals(34, dtid) 7 File "/usr/lib/python2.2/unittest.py", line 286, in 8 failUnlessEqual 9 raise self.failureException, \ 10AssertionError: 34 != 33 11 12-------------------------------------------------------------- 13Ran 27 tests in 0.063sSay you want:clist write the relevant information of this message only,namely: 5 unittests/dbfacadeTest.py:89: AssertionError: 34 != 33Then the error formatstring could be definedas follows: :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%mNote that the %Cstringis given before the %A here: since theexpression' %.%#' (which stands for the regularexpression'.*') matches every linestarting witha space, followed by any characters to theend of the line,it also hides line 7 which would triggera separate error message otherwise.Error format strings are always parsedpattern bypattern until the firstmatch occurs.efm-%>The %> item can be used to avoid trying patterns that appear earlier in'errorformat'. Thisis useful for patterns that match just about anything.For example, if the error looks like this:Error in line 123 of foo.c:unknown variable "i"This can be found with::set efm=xxx,%E%>Error in line %l of %f:,%Z%mWhere "xxx" hasapattern that would also match the second line.Important: Thereis no memory of what part of theerrorformat matched before;every line in the error file getsa complete new run through the error formatlines. For example, if one has: setlocal efm=aa,bb,cc,dd,eeWhere aa, bb, etc. are error format strings. Each line of the error file willbe matched to thepattern aa, then bb, then cc, etc. Just becausecc matchedthe previous error line does _not_ mean thatdd will be tried first on thecurrent line, even ifcc anddd are multi-lineerrorformat strings.Separate file nameerrorformat-separate-filenameThese prefixes are useful if the file nameis given once and multiplemessagesfollow that refer to this file name.%Osingle-line file message: overread the matched part%Psingle-line file message: push file %f onto the stack%Qsingle-line file message: pop the last file from stackExample: Givena compiler that produces the following error logfile (withoutleading line numbers): 1[a1.tt] 2(1,17) error: ';' missing 3(21,2) warning: variable 'z' not defined 4(67,3) error:end of file found beforestring ended 5 6[a2.tt] 7 8[a3.tt] 9NEW compiler v1.1 10(2,2) warning: variable 'x' not defined 11(67,3) warning: 's' already definedThis logfile lists severalmessages for each file enclosed in [...] which areproperly parsed by an error format like this: :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-QA call of:clist writes them accordingly with their correct filenames: 2 a1.tt:1 col 17 error: ';' missing 3 a1.tt:21 col 2 warning: variable 'z' not defined 4 a1.tt:67 col 3 error:end of file found beforestring ended 8 a3.tt:2 col 2 warning: variable 'x' not defined 9 a3.tt:67 col 3 warning: 's' already definedUnlike the other prefixes that all match against whole lines, %P, %Q and %Ocan be used to match several patterns in the same line. Thusitis possibleto parse even nested files like in the following line:{"file1" {"file2" error1} error2{"file3" error3 {"file4" error4 error5}}}The %O then parses over strings thatdo not contain any push/pop file nameinformation. Seeerrorformat-LaTeX for an extended example.Ignoring and using wholemessagesefm-ignoreThe codes '+' or '-' can be combined with theuppercase codes above; in thatcase they have to precede the letter, e.g. '%+A' or '%-G':%-do not include the matching multi-line in any output%+include the whole matching line in the %m errorstringOne prefixis only useful in combination with '+' or '-', namely %G. It parsesover lines containing general information like compiler version strings orother headers that can be skipped.%-Gignore this message%+Ggeneral messagePattern matchingThe scanf()-like "%*[]"notationis supported for backward-compatibilitywith previous versions of Vim. However,itis also possible to specify(nearly) any Vim supported regularexpression in format strings.Sincemeta characters of the regularexpression language can be part ofordinary matching strings or file names (and therefore internally have tobe escaped),meta symbols have to be written with leading '%':%\The single '\' character.Note that this has to beescaped("%\\") in ":set errorformat=" definitions.%.The single '.' character.%#The single'*'(!) character.%^The single '^' character.Note that thisis notuseful, thepattern already matches start of line.%$The single '$' character.Note that thisis notuseful, thepattern already matchesend of line.%[The single '[' character fora[] character range.%~The single '~' character.When using character classes in expressions (see/\i for an overview),terms containing the "\+" quantifier can be written in the scanf() "%*"notation. Example: "%\\d%\\+"("\d\+", "any number")is equivalent to "%*\\d".Importantnote: The \(...\) grouping of sub-matches can not be used in formatspecifications becauseitis reserved for internal conversions.Multiple entries in'errorformat'efm-entriesTo be able to detect output from several compilers, several format patternsmay beput in'errorformat', separated by commas (note: blanks after the commaare ignored). The firstpattern that hasa complete matchis used. If nomatchis found, matching parts from the last one will be used, although thefile nameis removed and the error messageis set to the whole message. Ifthereisapattern that may match output from several compilers (but not inaright way),putit after one thatis more restrictive.To includea comma inapattern precedeit withabackslash (you have to typetwo ina ":set" command). To includeabackslash itself give two backslashes(you have to type four ina ":set" command). You also need toputabackslashbeforeaspace for ":set".Valid matchesquickfix-validIfa line does not completely match one of the entries in'errorformat', thewhole lineisput in the error message and the entryis marked "not valid"These lines are skipped with the ":cn" and ":cp" commands (unless thereisno valid lineat all). You can use ":cl!" to display all the error messages.If the error format does not containa file name Vim cannot switch to thecorrect file. You will have todo this by hand.ExamplesThe format of the file from theAmiga Aztec compiler is:filename>linenumber:columnnumber:errortype:errornumber:errormessagefilenamename of the file in which the error was detectedlinenumberline number where the error was detectedcolumnnumbercolumn number where the error was detectederrortypetype of the error, normallya single 'E' or 'W'errornumbernumber of the error (for lookup in the manual)errormessagedescription of the errorThis can be matched with this'errorformat' entry:%f>%l:%c:%t:%n:%mSome examples forC compilers that produce single-line error outputs:%f:%l:\ %t%*[^0123456789]%n:\ %mfor Manx/AztecC errormessages(scanf() doesn't understand[0-9])%f\ %l\ %t%*[^0-9]%n:\ %mfor SASC\"%f\"\\,%*[^0-9]%l:\ %mfor genericC compilers%f:%l:\ %mfor GCC%f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f',%Dgmake[%*\\d]:\ Leaving\ directory\ `%f'for GCC with gmake (concat the lines!)%f(%l)\ :\%*[^:]:\ %mold SCOC compiler (pre-OS5)%f(%l)\ :\ %t%*[^0-9]%n:\ %midem, with error type and number%f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%mfor GCC, with some extrasExtended examples for the handling of multi-linemessages are given below,seeerrorformat-Jikes anderrorformat-LaTeX.Note thebackslash in front ofaspace and doublequote. Itis required forthe:set command. There are two backslashes in front ofa comma, one for the:set command and one to avoid recognizing the commaasa separator of errorformats.FilteringmessagesIf you havea compiler that produces errormessages thatdo not fit in theformat string, you could writea program that translates the errormessagesinto this format. You can use this program with the ":make" command bychanging the'makeprg' option. For example: :set mp=make\ \\\|&\ error_filterThe backslashes before the pipe character are required to avoidit to berecognizedasa command separator. Thebackslash before eachspaceisrequired for the set command.=============================================================================8. The directory stackquickfix-directory-stackQuickfix maintainsa stack for saving all used directories parsed from themake output. For GNU-make thisis rather simple,asit always prints theabsolute path of all directoriesit enters and leaves. Regardless if thisisdone viaa'cd' command in the makefile or with the parameter "-C dir" (changeto directory before reading the makefile). It may be useful to use the switch"-w" to force GNU-make to print out the working directory before and afterprocessing.Maintaining the correct directoryis more complicated if you don't useGNU-make. AIX-make for example doesn't print any information about itsworking directory. Then you need to enhance the makefile. In the makefile ofLessTif thereisa command which echoes "Making{target} in{dir}". Thespecial problem hereis thatit doesn't print information on leaving thedirectory and thatit doesn't print the absolute path.To solve the problem with relative paths and missing "leave directory"messages Vim uses the following algorithm:1) Check if the given directoryisa subdirectory of the current directory. If thisis true, storeitas the current directory.2) Ifitis nota subdir of the current directory, try if thisisa subdirectory of one of the upper directories.3) If the directory still isn't found,itis assumed to bea subdirectory of Vim's current directory.Additionallyitis checked for every file, ifit really exists in theidentified directory. If not,itis searched in all other directories of thedirectory stack (NOT the directory subtree!). Ifitis still not found,itisassumed thatitis in Vim's current directory.There are limitations in this algorithm. These examples assume that make justprints information about enteringa directory in the form "Making all in dir".1) Assume you have following directories and files: ./dir1 ./dir1/file1.c ./file1.c If make processes the directory "./dir1" before the current directory and thereis an error in the file "./file1.c", you willend up with the file "./dir1/file.c" loaded by Vim. This can only be solved witha "leave directory" message.2) Assume you have following directories and files: ./dir1 ./dir1/dir2 ./dir2 You get the following: Make output Directory interpreted by Vim ------------------------ ---------------------------- Making all in dir1 ./dir1 Making all in dir2 ./dir1/dir2 Making all in dir2 ./dir1/dir2 This can be solved byprinting absolute directories in the "enter directory" message or byprinting "leave directory" messages.To avoid this problem, ensure to print absolute directory names and "leavedirectory" messages.Examples for Makefiles:Unix: libs: for dn in $(LIBDIRS);do\(cd $$dn; echo "Entering dir '$$(pwd)'"; make); \echo "Leaving dir";\ doneAdd %DEntering\ dir\ '%f',%XLeaving\ dirto your'errorformat' to handle the above output.Note that Vim doesn't check if the directory name ina "leave directory"messagesis the current directory. Thisis why you could just use the message"Leaving dir".=============================================================================9. Specific error file formatserrorformatserrorformat-JikesJikes(TM),a source-to-bytecode Java compiler published by IBM Research,produces simple multi-line error messages.An'errorformat'string matching the producedmessagesis shown below.The following lines can be placed in the user'svimrc to overwrite Vim'srecognized default formats, or see:set+= how toinstall this formatadditionally to the default. :set efm=%A%f:%l:%c:%*\\d:%*\\d:,\%C%*\\s%trror:%m,\%+C%*[^:]%trror:%m,\%C%*\\s%tarning:%m,\%C%mJikes(TM) producesa single-line error message when invoked with the option"+E", and can be matched with the following: :setl efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%merrorformat-javacThis'errorformat' has been reported to work well for javac, which outputsaline with "^" to indicate the column of the error: :setl efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%#or: :setl efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%#Hereis an alternative from Michael F. Lamb forUnix that filters theerrorsfirst: :setl errorformat=%Z%f:%l:\ %m,%A%p^,%-G%*[^sl]%.%# :setl makeprg=javac\ %:S\ 2>&1\ \\\|\ vim-javac-filterYou need toput the following in "vim-javac-filter" somewhere in your path(e.g., in ~/bin) and makeit executable: #!/bin/sed -f /\^$/s/\t/\ /g;/:[0-9]\+:/{h;d};/^[ \t]*\^/G;In English, that sed script:- Changes single tabs to single spaces and- Moves the line with the filename, line number, error message to just after the pointer line. That way, the unused error text between doesn't break vim's notion ofa "multi-line message" and also doesn't force us to includeitasa "continuation ofa multi-line message."errorformat-antFor ant (http://jakarta.apache.org/) the aboveerrorformat has to be modifiedto honour the leading[javac] in front of each javac output line: :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#The'errorformat' can also be configured to handle ant together with eitherjavac or jikes. If you're using jikes, you should tell ant to use jikes' +Ecommand line switch which forces jikes to generate one-line error messages.Thisis what the second line (ofa build.xml file) below does: <property name = "build.compiler" value = "jikes"/> <property name = "build.compiler.emacs" value = "true"/>The'errorformat' which handles ant with both javac and jikes is: :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m, \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#errorformat-jadeparsing jade (seehttp://www.jclark.com/)errorsis simple: :set efm=jade:%f:%l:%c:%t:%merrorformat-LaTeXThe followingis an example how an'errorformat'string can be specifiedfor the (La)TeX typesetting system which displays errormessages overmultiple lines. The output of ":clist" and ":cc" etc. commands displaysmulti-lines ina single line, leading whitespaceis removed.It should beeasy to adopt the above LaTeXerrorformat to any compiler outputconsisting of multi-line errors.The commands can be placed inavimrc file or some other Vimscript file,e.g.ascript containing LaTeX related stuff whichis loaded only when editingLaTeX sources.Make sure to copy all lines of the example (in the given order), afterwardsremove the comment lines. For the '\'notationat the start of some lines seeline-continuation.First prepare'makeprg' such that LaTeX will report multipleerrors;do not stop when the first error has occurred: :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}Start of multi-line error messages: :set efm=%E!\ LaTeX\ %trror:\ %m,\%E!\ %m,Start of multi-line warning messages; the first two alsoinclude the line number. Meaning of some regular expressions:- "%.%#"(".*") matchesa (possibly empty)string- "%*\\d"("\d\+") matchesa number\%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#,\%+W%.%#\ at\ lines\ %l--%*\\d,\%WLaTeX\ %.%#Warning:\ %m,Possible continuations of error/warning messages; the firstone also includes the line number:\%Cl.%l\ %m,\%+C\ \ %m.,\%+C%.%#-%.%#,\%+C%.%#[]%.%#,\%+C[]%.%#,\%+C%.%#%[{}\\]%.%#,\%+C<%.%#>%.%#,\%C\ \ %m,Lines that match the following patternsdo not contain anyimportant information;do not include them in messages:\%-GSee\ the\ LaTeX%m,\%-GType\ \ H\ <return>%m,\%-G\ ...%.%#,\%-G%.%#\ (C)\ %.%#,\%-G(see\ the\ transcript%.%#),Generally exclude any empty or whitespace-only line frombeing displayed:\%-G\\s%#,The LaTeX output log does not specify the names of erroneoussource files per line; rather they are given globally,enclosed in parentheses.The following patterns try to match these names and storethem in an internal stack. The patterns possibly scan overthe same input line (one after another), the trailing "%r"conversion indicates the "rest" of the line that will beparsed in the nextgo until theend of lineis reached.Overreada file name enclosed in '('...')';do not pushitona stack since the file apparently does not contain anyerror:\%+O(%f)%r,Pusha file name onto the stack. The nameis given after '(':\%+P(%f%r,\%+P\ %\\=(%f%r,\%+P%*[^()](%f%r,\%+P[%\\d%[^()]%#(%f%r,Pop the last stored file name whena ')'is scanned:\%+Q)%r,\%+Q%*[^()])%r,\%+Q[%\\d%*[^()])%rNote that in some cases file names in the LaTeX output log cannot be parsedproperly. The parser might have been messed up by unbalanced parenthesesthen. The above example tries to catch the most relevant cases only.You can customize the given setting to suit your own purposes, for example,all the annoying "Overfull..." warnings could be excluded from beingrecognizedas an error.Alternatively to filtering the LaTeX compiler output,itis also possibleto directly read the *.log file thatis produced by the[La]TeX compiler.This contains even more useful information about possible error causes.However, to properly parse sucha complex file, an externalfilter shouldbe used. See the description further above how to make suchafilter knownby Vim.errorformat-PerlIn $VIMRUNTIME/tools you can find the efm_perl.pl script, which filtersPerlerrormessages intoa format thatquickfix mode will understand. See thestart of the file about how to use it. (Thisscriptis deprecated, seecompiler-perl.)=============================================================================10. Customizing thequickfixwindowquickfix-window-functionThe default format for the lines displayed in thequickfixwindow and locationlistwindow is:<filename>|<lnum> col<col>|<text>The values displayed in each line correspond to the "bufnr", "lnum", "col" and"text" fields returned by thegetqflist() function.For some quickfix/location lists, the displayed text needs to be customized.For example, if only the filenameis present foraquickfix entry, then thetwo "|" field separator characters after the filename are not needed. Anotherusecaseis to customize the path displayed fora filename. By default, thecomplete path (which may be too long)is displayed for files which are notunder the current directory tree. The file path may need to be simplified toacommon parent directory.The displayed text can be customized by setting the'quickfixtextfunc' optiontoa Vim function. This function will be called withadict argument andshould returnaList of strings to be displayed in thequickfix or locationlist window. Thedict argument will have the following fields:quickfixset to 1 when called foraquickfixlist and0 when called fora location list.winidfora location list, set to the id of thewindow with thelocation list. Foraquickfix list, set to 0. Can be used ingetloclist() to get the locationlist entry. idquickfix or locationlist identifier start_idxindex of the first entry for which text should be returned end_idxindex of the last entry for which text should be returnedThe function should returna single line of text to display in thequickfixwindow for each entry from start_idx to end_idx. The function can obtaininformation about the entries using thegetqflist() function and specifyingthequickfixlist identifier "id". Fora location list,getloclist() functioncan be used with the "winid" argument. If an emptylistis returned, then thedefault formatis used to display all the entries. If an item in the returnedlistis an empty string, then the default formatis used to display thecorresponding entry.Ifaquickfix or locationlist specific customizationis needed, then the'quickfixtextfunc' attribute of thelist can be set using thesetqflist() orsetloclist() function. This overrides the global'quickfixtextfunc' option.The example below displays thelist of old files(v:oldfiles) inaquickfixwindow. As thereis no line, column number and error text informationassociated with each entry, the'quickfixtextfunc' function returns only thefilename.Example: " create a quickfix list from v:oldfiles call setqflist([], ' ', {'lines' : v:oldfiles, 'efm' : '%f',\ 'quickfixtextfunc' : 'QfOldFiles'}) func QfOldFiles(info)" get information about a range of quickfix entrieslet items = getqflist({'id' : a:info.id, 'items' : 1}).itemslet l = []for idx in range(a:info.start_idx - 1, a:info.end_idx - 1) " use the simplified file name call add(l, fnamemodify(bufname(items[idx].bufnr), ':p:.'))endforreturn l endfunc vim:tw=78:ts=8:noet:ft=help:norl: