codekingpro/portable-devtools
114k
1*quickfix.txt* For Vim version 9.2. Last change: 2026 Feb 142 3 4 VIM REFERENCE MANUAL by Bram Moolenaar5 6 7This subject is introduced in section |30.1| of the user manual.8 91. Using QuickFix commands |quickfix|102. The error window |quickfix-window|113. Using more than one list of errors |quickfix-error-lists|124. Using :make |:make_makeprg|135. Using :grep |grep|146. Selecting a compiler |compiler-select|157. The error format |error-file-format|168. The directory stack |quickfix-directory-stack|179. Specific error file formats |errorformats|1810. Customizing the quickfix window |quickfix-window-function|19 20The quickfix commands are not available when the |+quickfix| feature was21disabled at compile time.22 23=============================================================================241. Using QuickFix commands *quickfix* *Quickfix* *E42*25 26Vim has a special mode to speedup the edit-compile-edit cycle. This is27inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga.28The idea is to save the error messages from the compiler in a file and use Vim29to jump to the errors one by one. You can examine each problem and fix it,30without having to remember all the error messages.31 32In Vim the quickfix commands are used more generally to find a list of33positions in files. For example, |:vimgrep| finds pattern matches. You can34use the positions in a script with the |getqflist()| function. Thus you can35do a lot more than the edit/compile/fix cycle!36 37If you have the error messages in a file you can start Vim with: >38 vim -q filename39 40From inside Vim an easy way to run a command and handle the output is with the41|:make| command (see below).42 43The 'errorformat' option should be set to match the error messages from your44compiler (see |errorformat| below).45 46 *quickfix-stack* *quickfix-ID* *E1545*47Each quickfix list has a unique identifier called the quickfix ID and this48number will not change within a Vim session. The |getqflist()| function can be49used to get the identifier assigned to a list. There is also a quickfix list50number which may change whenever more than 'chistory' lists are added to a51quickfix stack.52 53 *location-list* *E776*54A location list is a window-local quickfix list. You get one after commands55like `:lvimgrep`, `:lgrep`, `:lhelpgrep`, `:lmake`, etc., which create a56location list instead of a quickfix list as the corresponding `:vimgrep`,57`:grep`, `:helpgrep`, `:make` do.58 *location-list-file-window*59A location list is associated with a window and each window can have a60separate location list. A location list can be associated with only one61window. The location list is independent of the quickfix list.62 63When a window with a location list is split, the new window gets a copy of the64location list. When there are no longer any references to a location list,65the location list is destroyed.66 67 *quickfix-changedtick*68Every quickfix and location list has a read-only changedtick variable that69tracks the total number of changes made to the list. Every time the quickfix70list is modified, this count is incremented. This can be used to perform an71action only when the list has changed. The |getqflist()| and |getloclist()|72functions can be used to query the current value of changedtick. You cannot73change the changedtick variable.74 75The following quickfix commands can be used. The location list commands are76similar to the quickfix commands, replacing the 'c' prefix in the quickfix77command with 'l'.78 79 *E924*80If the current window was closed by an |autocommand| while processing a81location list command, it will be aborted.82 83 *E925* *E926*84If the current quickfix or location list was changed by an |autocommand| while85processing a quickfix or location list command, it will be aborted.86 87 *:cc*88:cc[!] [nr] Display error [nr]. If [nr] is omitted, the same89:[nr]cc[!] error is displayed again. Without [!] this doesn't90 work when jumping to another buffer, the current91 buffer has been changed, there is the only window for92 the buffer and both 'hidden' and 'autowrite' are off.93 When jumping to another buffer with [!] any changes to94 the current buffer are lost, unless 'hidden' is set or95 there is another window for this buffer.96 The 'switchbuf' settings are respected when jumping97 to a buffer.98 When used in the quickfix window the line number can99 be used, including "." for the current line and "$"100 for the last line.101 102 *:ll*103:ll[!] [nr] Same as ":cc", except the location list for the104:[nr]ll[!] current window is used instead of the quickfix list.105 106 *:cn* *:cne* *:cnext* *E553*107:[count]cn[ext][!] Display the [count] next error in the list that108 includes a file name. If there are no file names at109 all, go to the [count] next error. See |:cc| for110 [!] and 'switchbuf'.111 112 *:lne* *:lnext*113:[count]lne[xt][!] Same as ":cnext", except the location list for the114 current window is used instead of the quickfix list.115 116:[count]cN[ext][!] *:cp* *:cprevious* *:cprev* *:cN* *:cNext*117:[count]cp[revious][!] Display the [count] previous error in the list that118 includes a file name. If there are no file names at119 all, go to the [count] previous error. See |:cc| for120 [!] and 'switchbuf'.121 122 123:[count]lN[ext][!] *:lp* *:lprevious* *:lprev* *:lN* *:lNext*124:[count]lp[revious][!] Same as ":cNext" and ":cprevious", except the location125 list for the current window is used instead of the126 quickfix list.127 128 *:cabo* *:cabove*129:[count]cabo[ve] Go to the [count] error above the current line in the130 current buffer. If [count] is omitted, then 1 is131 used. If there are no errors, then an error message132 is displayed. Assumes that the entries in a quickfix133 list are sorted by their buffer number and line134 number. If there are multiple errors on the same135 line, then only the first entry is used. If [count]136 exceeds the number of entries above the current line,137 then the first error in the file is selected.138 139 *:lab* *:labove*140:[count]lab[ove] Same as ":cabove", except the location list for the141 current window is used instead of the quickfix list.142 143 *:cbel* *:cbelow*144:[count]cbel[ow] Go to the [count] error below the current line in the145 current buffer. If [count] is omitted, then 1 is146 used. If there are no errors, then an error message147 is displayed. Assumes that the entries in a quickfix148 list are sorted by their buffer number and line149 number. If there are multiple errors on the same150 line, then only the first entry is used. If [count]151 exceeds the number of entries below the current line,152 then the last error in the file is selected.153 154 *:lbel* *:lbelow*155:[count]lbel[ow] Same as ":cbelow", except the location list for the156 current window is used instead of the quickfix list.157 158 *:cbe* *:cbefore*159:[count]cbe[fore] Go to the [count] error before the current cursor160 position in the current buffer. If [count] is161 omitted, then 1 is used. If there are no errors, then162 an error message is displayed. Assumes that the163 entries in a quickfix list are sorted by their buffer,164 line and column numbers. If [count] exceeds the165 number of entries before the current position, then166 the first error in the file is selected.167 168 *:lbe* *:lbefore*169:[count]lbe[fore] Same as ":cbefore", except the location list for the170 current window is used instead of the quickfix list.171 172 *:caf* *:cafter*173:[count]caf[ter] Go to the [count] error after the current cursor174 position in the current buffer. If [count] is175 omitted, then 1 is used. If there are no errors, then176 an error message is displayed. Assumes that the177 entries in a quickfix list are sorted by their buffer,178 line and column numbers. If [count] exceeds the179 number of entries after the current position, then180 the last error in the file is selected.181 182 *:laf* *:lafter*183:[count]laf[ter] Same as ":cafter", except the location list for the184 current window is used instead of the quickfix list.185 186 *:cnf* *:cnfile*187:[count]cnf[ile][!] Display the first error in the [count] next file in188 the list that includes a file name. If there are no189 file names at all or if there is no next file, go to190 the [count] next error. See |:cc| for [!] and191 'switchbuf'.192 193 *:lnf* *:lnfile*194:[count]lnf[ile][!] Same as ":cnfile", except the location list for the195 current window is used instead of the quickfix list.196 197:[count]cNf[ile][!] *:cpf* *:cpfile* *:cNf* *:cNfile*198:[count]cpf[ile][!] Display the last error in the [count] previous file in199 the list that includes a file name. If there are no200 file names at all or if there is no next file, go to201 the [count] previous error. See |:cc| for [!] and202 'switchbuf'.203 204 205:[count]lNf[ile][!] *:lpf* *:lpfile* *:lNf* *:lNfile*206:[count]lpf[ile][!] Same as ":cNfile" and ":cpfile", except the location207 list for the current window is used instead of the208 quickfix list.209 210 *:crewind* *:cr*211:cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST212 error is displayed. See |:cc|.213 214 *:lrewind* *:lr*215:lr[ewind][!] [nr] Same as ":crewind", except the location list for the216 current window is used instead of the quickfix list.217 218 *:cfirst* *:cfir*219:cfir[st][!] [nr] Same as ":crewind".220 221 *:lfirst* *:lfir*222:lfir[st][!] [nr] Same as ":lrewind".223 224 *:clast* *:cla*225:cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST226 error is displayed. See |:cc|.227 228 *:llast* *:lla*229:lla[st][!] [nr] Same as ":clast", except the location list for the230 current window is used instead of the quickfix list.231 232 *:cq* *:cquit*233:cq[uit][!]234:{N}cq[uit][!]235:cq[uit][!] {N} Quit Vim with error code {N}. {N} defaults to one.236 Useful when Vim is called from another program:237 e.g., a compiler will not compile the same file again,238 `git commit` will abort the committing process, `fc`239 (built-in for shells like bash and zsh) will not240 execute the command, etc.241 {N} can also be zero, in which case Vim exits242 normally.243 WARNING: All changes in files are lost! Also when the244 [!] is not used. It works like ":qall!" |:qall|,245 except that Vim returns a non-zero exit code.246 247 *:cf* *:cfi* *:cfile*248:cf[ile][!] [errorfile] Read the error file and jump to the first error.249 This is done automatically when Vim is started with250 the -q option. You can use this command when you251 keep Vim running while compiling. If you give the252 name of the errorfile, the 'errorfile' option will253 be set to [errorfile]. See |:cc| for [!].254 If the encoding of the error file differs from the255 'encoding' option, you can use the 'makeencoding'256 option to specify the encoding.257 258 *:lf* *:lfi* *:lfile*259:lf[ile][!] [errorfile] Same as ":cfile", except the location list for the260 current window is used instead of the quickfix list.261 You can not use the -q command-line option to set262 the location list.263 264 265:cg[etfile] [errorfile] *:cg* *:cgetfile*266 Read the error file. Just like ":cfile" but don't267 jump to the first error.268 If the encoding of the error file differs from the269 'encoding' option, you can use the 'makeencoding'270 option to specify the encoding.271 272 273:lg[etfile] [errorfile] *:lg* *:lge* *:lgetfile*274 Same as ":cgetfile", except the location list for the275 current window is used instead of the quickfix list.276 277 *:caddf* *:caddfile*278:caddf[ile] [errorfile] Read the error file and add the errors from the279 errorfile to the current quickfix list. If a quickfix280 list is not present, then a new list is created.281 If the encoding of the error file differs from the282 'encoding' option, you can use the 'makeencoding'283 option to specify the encoding.284 285 *:laddf* *:laddfile*286:laddf[ile] [errorfile] Same as ":caddfile", except the location list for the287 current window is used instead of the quickfix list.288 289 *:cb* *:cbuffer* *E681*290:[range]cb[uffer][!] [bufnr]291 Read the error list from the current buffer.292 When [bufnr] is given it must be the number of a293 loaded buffer. That buffer will then be used instead294 of the current buffer.295 A range can be specified for the lines to be used.296 Otherwise all lines in the buffer are used.297 See |:cc| for [!].298 299 *:lb* *:lbuffer*300:[range]lb[uffer][!] [bufnr]301 Same as ":cbuffer", except the location list for the302 current window is used instead of the quickfix list.303 304 *:cgetb* *:cgetbuffer*305:[range]cgetb[uffer] [bufnr]306 Read the error list from the current buffer. Just307 like ":cbuffer" but don't jump to the first error.308 309 *:lgetb* *:lgetbuffer*310:[range]lgetb[uffer] [bufnr]311 Same as ":cgetbuffer", except the location list for312 the current window is used instead of the quickfix313 list.314 315 *:cad* *:cadd* *:caddbuffer*316:[range]cad[dbuffer] [bufnr]317 Read the error list from the current buffer and add318 the errors to the current quickfix list. If a319 quickfix list is not present, then a new list is320 created. Otherwise, same as ":cbuffer".321 322 *:laddb* *:laddbuffer*323:[range]laddb[uffer] [bufnr]324 Same as ":caddbuffer", except the location list for325 the current window is used instead of the quickfix326 list.327 328 *:cex* *:cexpr* *E777*329:cex[pr][!] {expr} Create a quickfix list using the result of {expr} and330 jump to the first error.331 If {expr} is a String, then each newline terminated332 line in the String is processed using the global value333 of 'errorformat' and the result is added to the334 quickfix list.335 If {expr} is a List, then each String item in the list336 is processed and added to the quickfix list. Non337 String items in the List are ignored.338 See |:cc| for [!].339 Examples: >340 :cexpr system('grep -n xyz *')341 :cexpr getline(1, '$')342<343 *:lex* *:lexpr*344:lex[pr][!] {expr} Same as |:cexpr|, except the location list for the345 current window is used instead of the quickfix list.346 347 *:cgete* *:cgetexpr*348:cgete[xpr] {expr} Create a quickfix list using the result of {expr}.349 Just like |:cexpr|, but don't jump to the first error.350 351 *:lgete* *:lgetexpr*352:lgete[xpr] {expr} Same as |:cgetexpr|, except the location list for the353 current window is used instead of the quickfix list.354 355 *:cadde* *:caddexpr*356:cadde[xpr] {expr} Evaluate {expr} and add the resulting lines to the357 current quickfix list. If a quickfix list is not358 present, then a new list is created. The current359 cursor position will not be changed. See |:cexpr| for360 more information.361 Example: >362 :g/mypattern/caddexpr expand("%") .. ":" .. line(".") .. ":" .. getline(".")363<364 *:lad* *:ladd* *:laddexpr*365:lad[dexpr] {expr} Same as ":caddexpr", except the location list for the366 current window is used instead of the quickfix list.367 368 *:cl* *:clist*369:cl[ist] [from] [, [to]]370 List all errors that are valid |quickfix-valid|.371 If numbers [from] and/or [to] are given, the372 respective range of errors is listed. A negative373 number counts from the last error backwards, -1 being374 the last error.375 The |:filter| command can be used to display only the376 quickfix entries matching a supplied pattern. The377 pattern is matched against the filename, module name,378 pattern and text of the entry.379 380:cl[ist] +{count} List the current and next {count} valid errors. This381 is similar to ":clist from from+count", where "from"382 is the current error position.383 384:cl[ist]! [from] [, [to]]385 List all errors.386 387:cl[ist]! +{count} List the current and next {count} error lines. This388 is useful to see unrecognized lines after the current389 one. For example, if ":clist" shows:390 8384 testje.java:252: error: cannot find symbol ~391 Then using ":cl! +3" shows the reason:392 8384 testje.java:252: error: cannot find symbol ~393 8385: ZexitCode = Fmainx(); ~394 8386: ^ ~395 8387: symbol: method Fmainx() ~396 397:lli[st] [from] [, [to]] *:lli* *:llist*398 Same as ":clist", except the location list for the399 current window is used instead of the quickfix list.400 401:lli[st]! [from] [, [to]]402 List all the entries in the location list for the403 current window.404 405If you insert or delete lines, mostly the correct error location is still406found because hidden marks are used. Sometimes, when the mark has been407deleted for some reason, the message "line changed" is shown to warn you that408the error location may not be correct. If you quit Vim and start again the409marks are lost and the error locations may not be correct anymore.410 411Two autocommands are available for running commands before and after a412quickfix command (':make', ':grep' and so on) is executed. See413|QuickFixCmdPre| and |QuickFixCmdPost| for details.414 415 *QuickFixCmdPost-example*416When 'encoding' differs from the locale, the error messages may have a417different encoding from what Vim is using. To convert the messages you can418use this code: >419 function QfMakeConv()420 let qflist = getqflist()421 for i in qflist422 let i.text = iconv(i.text, "cp936", "utf-8")423 endfor424 call setqflist(qflist)425 endfunction426 427 au QuickfixCmdPost make call QfMakeConv()428Another option is using 'makeencoding'.429 430 *quickfix-title*431Every quickfix and location list has a title. By default the title is set to432the command that created the list. The |getqflist()| and |getloclist()|433functions can be used to get the title of a quickfix and a location list434respectively. The |setqflist()| and |setloclist()| functions can be used to435modify the title of a quickfix and location list respectively. Examples: >436 call setqflist([], 'a', {'title' : 'Cmd output'})437 echo getqflist({'title' : 1})438 call setloclist(3, [], 'a', {'title' : 'Cmd output'})439 echo getloclist(3, {'title' : 1})440<441 *quickfix-index*442When you jump to a quickfix/location list entry using any of the quickfix443commands (e.g. |:cc|, |:cnext|, |:cprev|, etc.), that entry becomes the444currently selected entry. The index of the currently selected entry in a445quickfix/location list can be obtained using the getqflist()/getloclist()446functions. Examples: >447 echo getqflist({'idx' : 0}).idx448 echo getqflist({'id' : qfid, 'idx' : 0}).idx449 echo getloclist(2, {'idx' : 0}).idx450<451For a new quickfix list, the first entry is selected and the index is 1. Any452entry in any quickfix/location list can be set as the currently selected entry453using the setqflist() function. Examples: >454 call setqflist([], 'a', {'idx' : 12})455 call setqflist([], 'a', {'id' : qfid, 'idx' : 7})456 call setloclist(1, [], 'a', {'idx' : 7})457<458 *quickfix-size*459You can get the number of entries (size) in a quickfix and a location list460using the |getqflist()| and |getloclist()| functions respectively. Examples: >461 echo getqflist({'size' : 1})462 echo getloclist(5, {'size' : 1})463<464 *quickfix-context*465Any Vim type can be associated as a context with a quickfix or location list.466The |setqflist()| and the |setloclist()| functions can be used to associate a467context with a quickfix and a location list respectively. The |getqflist()|468and the |getloclist()| functions can be used to retrieve the context of a469quickfix and a location list respectively. This is useful for a Vim plugin470dealing with multiple quickfix/location lists.471Examples: >472 473 let somectx = {'name' : 'Vim', 'type' : 'Editor'}474 call setqflist([], 'a', {'context' : somectx})475 echo getqflist({'context' : 1})476 477 let newctx = ['red', 'green', 'blue']478 call setloclist(2, [], 'a', {'id' : qfid, 'context' : newctx})479 echo getloclist(2, {'id' : qfid, 'context' : 1})480<481 *quickfix-parse*482You can parse a list of lines using 'errorformat' without creating or483modifying a quickfix list using the |getqflist()| function. Examples: >484 echo getqflist({'lines' : ["F1:10:Line10", "F2:20:Line20"]})485 echo getqflist({'lines' : systemlist('grep -Hn quickfix *')})486This returns a dictionary where the "items" key contains the list of quickfix487entries parsed from lines. The following shows how to use a custom488'errorformat' to parse the lines without modifying the 'errorformat' option: >489 echo getqflist({'efm' : '%f#%l#%m', 'lines' : ['F1#10#Line']})490<491 492EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST:493 *:cdo*494:cdo[!] {cmd} Execute {cmd} in each valid entry in the quickfix495 list. It works like doing this: >496 :cfirst497 :{cmd}498 :cnext499 :{cmd}500 etc.501< When the current file can't be |abandon|ed and the [!]502 is not present, the command fails.503 When going to the next entry fails execution stops.504 The last buffer (or where an error occurred) becomes505 the current buffer.506 {cmd} can contain '|' to concatenate several commands.507 508 Only valid entries in the quickfix list are used.509 A range can be used to select entries, e.g.: >510 :10,$cdo cmd511< To skip entries 1 to 9.512 513 Note: While this command is executing, the Syntax514 autocommand event is disabled by adding it to515 'eventignore'. This considerably speeds up editing516 each buffer.517 Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|,518 |:ldo|, |:cfdo| and |:lfdo|.519 520 *:cfd* *:cfdo*521:cfd[o][!] {cmd} Execute {cmd} in each file in the quickfix list.522 It works like doing this: >523 :cfirst524 :{cmd}525 :cnfile526 :{cmd}527 etc.528< Otherwise it works the same as `:cdo`.529 530 *:ld* *:ldo*531:ld[o][!] {cmd} Execute {cmd} in each valid entry in the location list532 for the current window.533 It works like doing this: >534 :lfirst535 :{cmd}536 :lnext537 :{cmd}538 etc.539< Only valid entries in the location list are used.540 Otherwise it works the same as `:cdo`.541 542 *:lfd* *:lfdo*543:lfd[o][!] {cmd} Execute {cmd} in each file in the location list for544 the current window.545 It works like doing this: >546 :lfirst547 :{cmd}548 :lnfile549 :{cmd}550 etc.551< Otherwise it works the same as `:ldo`.552 553FILTERING A QUICKFIX OR LOCATION LIST:554 *cfilter-plugin* *:Cfilter* *:Lfilter* *package-cfilter*555If you have too many entries in a quickfix list, you can use the cfilter556plugin to reduce the number of entries. Load the plugin with: >vim557 558 packadd cfilter559 560Then you can use the following commands to filter a quickfix/location list: >561 562 :Cfilter[!] /{pat}/563 :Lfilter[!] /{pat}/564 565The |:Cfilter| command creates a new quickfix list from the entries matching566{pat} in the current quickfix list. {pat} is a Vim |regular-expression|567pattern. Both the file name and the text of the entries are matched against568{pat}. If the optional ! is supplied, then the entries not matching {pat} are569used. The pattern can be optionally enclosed using one of the following570characters: ', ", /. If the pattern is empty, then the last used search571pattern is used.572 573The |:Lfilter| command does the same as |:Cfilter| but operates on the current574location list.575 576The current quickfix/location list is not modified by these commands, so you577can go back to the unfiltered list using the |:colder|/|:lolder| command.578 579=============================================================================5802. The error window *quickfix-window*581 582 *:cope* *:copen* *w:quickfix_title*583:cope[n] [height] Open a window to show the current list of errors.584 585 When [height] is given, the window becomes that high586 (if there is room). When [height] is omitted the587 window is made ten lines high.588 589 If there already is a quickfix window, it will be made590 the current window. It is not possible to open a591 second quickfix window. If [height] is given the592 existing window will be resized to it.593 594 *quickfix-buffer*595 The window will contain a special buffer, with596 'buftype' equal to "quickfix". Don't change this!597 The window will have the w:quickfix_title variable set598 which will indicate the command that produced the599 quickfix list. This can be used to compose a custom600 status line if the value of 'statusline' is adjusted601 properly. Whenever this buffer is modified by a602 quickfix command or function, the |b:changedtick|603 variable is incremented. You can get the number of604 this buffer using the getqflist() and getloclist()605 functions by passing the "qfbufnr" item. For a606 location list, this buffer is wiped out when the607 location list is removed.608 609 *:lop* *:lopen*610:lop[en] [height] Open a window to show the location list for the611 current window. Works only when the location list for612 the current window is present. You can have more than613 one location window opened at a time. Otherwise, it614 acts the same as ":copen".615 616 *:ccl* *:cclose*617:ccl[ose] Close the quickfix window.618 619 *:lcl* *:lclose*620:lcl[ose] Close the window showing the location list for the621 current window.622 623 *:cw* *:cwindow*624:cw[indow] [height] Open the quickfix window when there are recognized625 errors. If the window is already open and there are626 no recognized errors, close the window.627 628 When opening the window and [height] is given, the629 window becomes that high (if there is room). When630 [height] is omitted the window is made ten lines high.631 632 *:lw* *:lwindow*633:lw[indow] [height] Same as ":cwindow", except use the window showing the634 location list for the current window.635 636 *:cbo* *:cbottom*637:cbo[ttom] Put the cursor in the last line of the quickfix window638 and scroll to make it visible. This is useful for639 when errors are added by an asynchronous callback.640 Only call it once in a while if there are many641 updates to avoid a lot of redrawing.642 643 *:lbo* *:lbottom*644:lbo[ttom] Same as ":cbottom", except use the window showing the645 location list for the current window.646 647Normally the quickfix window is at the bottom of the screen. If there are648vertical splits, it's at the bottom of the rightmost column of windows. To649make it always occupy the full width: >650 :botright cwindow651You can move the window around with |window-moving| commands.652For example, to move it to the top: CTRL-W K653The 'winfixheight' option will be set, which means that the window will mostly654keep its height, ignoring 'winheight' and 'equalalways'. You can change the655height manually (e.g., by dragging the status line above it with the mouse).656 657In the quickfix window, each line is one error. The line number is equal to658the error number. The current entry is highlighted with the QuickFixLine659highlighting. You can change it to your liking, e.g.: >660 :hi QuickFixLine ctermbg=Yellow guibg=Yellow661 662You can use ":.cc" to jump to the error under the cursor.663Hitting the <Enter> key or double-clicking the mouse on a line has the same664effect. The file containing the error is opened in the window above the665quickfix window. If there already is a window for that file, it is used666instead. If the buffer in the used window has changed, and the error is in667another file, jumping to the error will fail. You will first have to make668sure the window contains a buffer which can be abandoned.669 670When you select a file from the quickfix window, the following steps are used671to find a window to edit the file:672 6731. If a window displaying the selected file is present in the current tabpage674 (starting with the window before the quickfix window), then that window is675 used.6762. If the above step fails and if 'switchbuf' contains "usetab" and a window677 displaying the selected file is present in any one of the tabpages678 (starting with the first tabpage) then that window is used.6793. If the above step fails then a window in the current tabpage displaying a680 buffer with 'buftype' not set (starting with the window before the quickfix681 window) is used.6824. If the above step fails and if 'switchbuf' contains "uselast", then the683 previously accessed window is used.6845. If the above step fails then the window before the quickfix window is used.685 If there is no previous window, then the window after the quickfix window686 is used.6876. If the above step fails, then a new horizontally split window above the688 quickfix window is used.689 690 *CTRL-W_<Enter>* *CTRL-W_<CR>*691You can use CTRL-W <Enter> to open a new window and jump to the error there.692 693When the quickfix window has been filled, two autocommand events are694triggered. First the 'filetype' option is set to "qf", which triggers the695FileType event (also see |qf.vim|). Then the BufReadPost event is triggered,696using "quickfix" for the buffer name. This can be used to perform some action697on the listed errors. Example: >698 au BufReadPost quickfix setlocal modifiable699 \ | silent exe 'g/^/s//\=line(".") .. " "/'700 \ | setlocal nomodifiable701This prepends the line number to each line. Note the use of "\=" in the702substitute string of the ":s" command, which is used to evaluate an703expression.704The BufWinEnter event is also triggered, again using "quickfix" for the buffer705name.706 707Note: When adding to an existing quickfix list the autocommand are not708triggered.709 710Note: Making changes in the quickfix window has no effect on the list of711errors. 'modifiable' is off to avoid making changes. If you delete or insert712lines anyway, the relation between the text and the error number is messed up.713If you really want to do this, you could write the contents of the quickfix714window to a file and use ":cfile" to have it parsed and used as the new error715list.716 717 *location-list-window*718The location list window displays the entries in a location list. When you719open a location list window, it is created below the current window and720displays the location list for the current window. The location list window721is similar to the quickfix window, except that you can have more than one722location list window open at a time. When you use a location list command in723this window, the displayed location list is used.724 725When you select a file from the location list window, the following steps are726used to find a window to edit the file:727 7281. If a non-quickfix window associated with the location list is present in729 the current tabpage, then that window is used.7302. If the above step fails and if the file is already opened in another window731 in the current tabpage, then that window is used.7323. If the above step fails and 'switchbuf' contains "usetab" and if the file733 is opened in a window in any one of the tabpages, then that window is used.7344. If the above step fails then a window in the current tabpage showing a735 buffer with 'buftype' not set is used.7365. If the above step fails, then the file is edited in a new window.737 738In all of the above cases, if the location list for the selected window is not739yet set, then it is set to the location list displayed in the location list740window.741 742 *quickfix-window-ID*743You can use the |getqflist()| and |getloclist()| functions to obtain the744window ID of the quickfix window and location list window respectively (if745present). Examples: >746 echo getqflist({'winid' : 1}).winid747 echo getloclist(2, {'winid' : 1}).winid748<749 *getqflist-examples*750The |getqflist()| and |getloclist()| functions can be used to get the various751attributes of a quickfix and location list respectively. Some examples for752using these functions are below:753>754 " get the title of the current quickfix list755 :echo getqflist({'title' : 0}).title756 757 " get the identifier of the current quickfix list758 :let qfid = getqflist({'id' : 0}).id759 760 " get the identifier of the fourth quickfix list in the stack761 :let qfid = getqflist({'nr' : 4, 'id' : 0}).id762 763 " check whether a quickfix list with a specific identifier exists764 :if getqflist({'id' : qfid}).id == qfid765 766 " get the index of the current quickfix list in the stack767 :let qfnum = getqflist({'nr' : 0}).nr768 769 " get the items of a quickfix list specified by an identifier770 :echo getqflist({'id' : qfid, 'items' : 0}).items771 772 " get the number of entries in a quickfix list specified by an id773 :echo getqflist({'id' : qfid, 'size' : 0}).size774 775 " get the context of the third quickfix list in the stack776 :echo getqflist({'nr' : 3, 'context' : 0}).context777 778 " get the number of quickfix lists in the stack779 :echo getqflist({'nr' : '$'}).nr780 781 " get the number of times the current quickfix list is changed782 :echo getqflist({'changedtick' : 0}).changedtick783 784 " get the current entry in a quickfix list specified by an identifier785 :echo getqflist({'id' : qfid, 'idx' : 0}).idx786 787 " get all the quickfix list attributes using an identifier788 :echo getqflist({'id' : qfid, 'all' : 0})789 790 " parse text from a List of lines and return a quickfix list791 :let myList = ["a.java:10:L10", "b.java:20:L20"]792 :echo getqflist({'lines' : myList}).items793 794 " parse text using a custom 'efm' and return a quickfix list795 :echo getqflist({'lines' : ['a.c#10#Line 10'], 'efm':'%f#%l#%m'}).items796 797 " get the quickfix list window id798 :echo getqflist({'winid' : 0}).winid799 800 " get the quickfix list window buffer number801 :echo getqflist({'qfbufnr' : 0}).qfbufnr802 803 " get the context of the current location list804 :echo getloclist(0, {'context' : 0}).context805 806 " get the location list window id of the third window807 :echo getloclist(3, {'winid' : 0}).winid808 809 " get the location list window buffer number of the third window810 :echo getloclist(3, {'qfbufnr' : 0}).qfbufnr811 812 " get the file window id of a location list window (winnr: 4)813 :echo getloclist(4, {'filewinid' : 0}).filewinid814<815 *setqflist-examples*816The |setqflist()| and |setloclist()| functions can be used to set the various817attributes of a quickfix and location list respectively. Some examples for818using these functions are below:819>820 " create an empty quickfix list with a title and a context821 :let t = 'Search results'822 :let c = {'cmd' : 'grep'}823 :call setqflist([], ' ', {'title' : t, 'context' : c})824 825 " set the title of the current quickfix list826 :call setqflist([], 'a', {'title' : 'Mytitle'})827 828 " change the current entry in the list specified by an identifier829 :call setqflist([], 'a', {'id' : qfid, 'idx' : 10})830 831 " set the context of a quickfix list specified by an identifier832 :call setqflist([], 'a', {'id' : qfid, 'context' : {'val' : 100}})833 834 " create a new quickfix list from a command output835 :call setqflist([], ' ', {'lines' : systemlist('grep -Hn main *.c')})836 837 " parse text using a custom efm and add to a particular quickfix list838 :call setqflist([], 'a', {'id' : qfid,839 \ 'lines' : ["a.c#10#L10", "b.c#20#L20"], 'efm':'%f#%l#%m'})840 841 " add items to the quickfix list specified by an identifier842 :let newItems = [{'filename' : 'a.txt', 'lnum' : 10, 'text' : "Apple"},843 \ {'filename' : 'b.txt', 'lnum' : 20, 'text' : "Orange"}]844 :call setqflist([], 'a', {'id' : qfid, 'items' : newItems})845 846 " empty a quickfix list specified by an identifier847 :call setqflist([], 'r', {'id' : qfid, 'items' : []})848 849 " free all the quickfix lists in the stack850 :call setqflist([], 'f')851 852 " set the title of the fourth quickfix list853 :call setqflist([], 'a', {'nr' : 4, 'title' : 'SomeTitle'})854 855 " create a new quickfix list at the end of the stack856 :call setqflist([], ' ', {'nr' : '$',857 \ 'lines' : systemlist('grep -Hn class *.java')})858 859 " create a new location list from a command output860 :call setloclist(0, [], ' ', {'lines' : systemlist('grep -Hn main *.c')})861 862 " replace the location list entries for the third window863 :call setloclist(3, [], 'r', {'items' : newItems})864<865=============================================================================8663. Using more than one list of errors *quickfix-error-lists*867 868So far it has been assumed that there is only one list of errors. Actually869there can be multiple used lists that are remembered; see 'chistory' and870'lhistory'.871When starting a new list, the previous ones are automatically kept. Two872commands can be used to access older error lists. They set one of the873existing error lists as the current one.874 875 *:colder* *:col* *E380*876:col[der] [count] Go to older error list. When [count] is given, do877 this [count] times. When already at the oldest error878 list, an error message is given.879 880 *:lolder* *:lol*881:lol[der] [count] Same as `:colder`, except use the location list for882 the current window instead of the quickfix list.883 884 *:cnewer* *:cnew* *E381*885:cnew[er] [count] Go to newer error list. When [count] is given, do886 this [count] times. When already at the newest error887 list, an error message is given.888 889 *:lnewer* *:lnew*890:lnew[er] [count] Same as `:cnewer`, except use the location list for891 the current window instead of the quickfix list.892 893 *:chistory* *:chi*894:[count]chi[story] Show the list of error lists. The current list is895 marked with ">". The output looks like:896 error list 1 of 3; 43 errors :make ~897 > error list 2 of 3; 0 errors :helpgrep tag ~898 error list 3 of 3; 15 errors :grep ex_help *.c ~899 900 When [count] is given, then the count'th quickfix901 list is made the current list. Example: >902 " Make the 4th quickfix list current903 :4chistory904<905 *:lhistory* *:lhi*906:[count]lhi[story] Show the list of location lists, otherwise like907 `:chistory`.908 909When adding a new error list, it becomes the current list.910 911When ":colder" has been used and ":make" or ":grep" is used to add a new error912list, one newer list is overwritten. This is especially useful if you are913browsing with ":grep" |grep|. If you want to keep the more recent error914lists, use ":cnewer 99" first.915 916To get the number of lists in the quickfix and location list stack, you can917use the |getqflist()| and |getloclist()| functions respectively with the list918number set to the special value '$'. Examples: >919 echo getqflist({'nr' : '$'}).nr920 echo getloclist(3, {'nr' : '$'}).nr921To get the number of the current list in the stack: >922 echo getqflist({'nr' : 0}).nr923<924=============================================================================9254. Using :make *:make_makeprg*926 927 *:mak* *:make*928:mak[e][!] [arguments] 1. All relevant |QuickFixCmdPre| autocommands are929 executed.930 2. If the 'autowrite' option is on, write any changed931 buffers932 3. An errorfile name is made from 'makeef'. If933 'makeef' doesn't contain "##", and a file with this934 name already exists, it is deleted.935 4. The program given with the 'makeprg' option is936 started (default "make") with the optional937 [arguments] and the output is saved in the938 errorfile (for Unix it is also echoed on the939 screen).940 5. The errorfile is read using 'errorformat'.941 6. All relevant |QuickFixCmdPost| autocommands are942 executed. See example below.943 7. If [!] is not given the first error is jumped to.944 8. The errorfile is deleted.945 9. You can now move through the errors with commands946 like |:cnext| and |:cprevious|, see above.947 This command does not accept a comment, any "948 characters are considered part of the arguments.949 If the encoding of the program output differs from the950 'encoding' option, you can use the 'makeencoding'951 option to specify the encoding.952 953 *:lmak* *:lmake*954:lmak[e][!] [arguments]955 Same as ":make", except the location list for the956 current window is used instead of the quickfix list.957 958The ":make" command executes the command given with the 'makeprg' option.959This is done by passing the command to the shell given with the 'shell'960option. This works almost like typing961 962 ":!{makeprg} [arguments] {shellpipe} {errorfile}".963 964{makeprg} is the string given with the 'makeprg' option. Any command can be965used, not just "make". Characters '%' and '#' are expanded as usual on a966command-line. You can use "%<" to insert the current file name without967extension, or "#<" to insert the alternate file name without extension, for968example: >969 :set makeprg=make\ #<.o970 971[arguments] is anything that is typed after ":make".972{shellpipe} is the 'shellpipe' option.973{errorfile} is the 'makeef' option, with ## replaced to make it unique.974 975The placeholder "$*" can be used for the argument list in {makeprg} if the976command needs some additional characters after its arguments. The $* is977replaced then by all arguments. Example: >978 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}979or simpler >980 :let &mp = 'latex \\nonstopmode \\input\{$*}'981"$*" can be given multiple times, for example: >982 :set makeprg=gcc\ -o\ $*\ $*983 984The 'shellpipe' option defaults to ">" for the Amiga and ">%s 2>&1" for Win32.985This means that the output of the compiler is saved in a file and not shown on986the screen directly. For Unix "| tee" is used. The compiler output is shown987on the screen and saved in a file the same time. Depending on the shell used988"|& tee" or "2>&1| tee" is the default, so stderr output will be included.989 990If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful991for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).992 993 994Using QuickFixCmdPost to fix the encoding ~995 996It may be that 'encoding' is set to an encoding that differs from the messages997your build program produces. This example shows how to fix this after Vim has998read the error messages: >999 1000 function QfMakeConv()1001 let qflist = getqflist()1002 for i in qflist1003 let i.text = iconv(i.text, "cp936", "utf-8")1004 endfor1005 call setqflist(qflist)1006 endfunction1007 1008 au QuickfixCmdPost make call QfMakeConv()1009 1010(Example by Faque Cheng)1011Another option is using 'makeencoding'.1012 1013==============================================================================10145. Using :vimgrep and :grep *grep* *lid*1015 1016Vim has two ways to find matches for a pattern: internal and external. The1017advantage of the internal grep is that it works on all systems and uses the1018powerful Vim search patterns. An external grep program can be used when the1019Vim grep does not do what you want.1020 1021The internal method will be slower, because files are read into memory. The1022advantages are:1023- Line separators and encoding are automatically recognized, as if a file is1024 being edited.1025- Uses Vim search patterns. Multi-line patterns can be used.1026- When plugins are enabled: compressed and remote files can be searched.1027 |gzip| |netrw|1028 1029To be able to do this Vim loads each file as if it is being edited. When1030there is no match in the file the associated buffer is wiped out again. The1031'hidden' option is ignored here to avoid running out of memory or file1032descriptors when searching many files. However, when the |:hide| command1033modifier is used the buffers are kept loaded. This makes following searches1034in the same files a lot faster.1035 1036Note that |:copen| (or |:lopen| for |:lgrep|) may be used to open a buffer1037containing the search results in linked form. The |:silent| command may be1038used to suppress the default full screen grep output. The ":grep!" form of1039the |:grep| command doesn't jump to the first match automatically. These1040commands can be combined to create a NewGrep command: >1041 1042 command! -nargs=+ NewGrep execute 'silent grep! <args>' | copen 421043 1044 10455.1 Using Vim's internal grep1046 1047 *:vim* *:vimgrep* *E682* *E683*1048:vim[grep][!] /{pattern}/[g][j][f] {file} ...1049 Search for {pattern} in the files {file} ... and set1050 the error list to the matches. Files matching1051 'wildignore' are ignored; files in 'suffixes' are1052 searched last.1053 1054 {pattern} is a Vim search pattern. Instead of1055 enclosing it in / any non-ID character (see1056 'isident') can be used, so long as it does not appear1057 in {pattern}.1058 'ignorecase' applies. To overrule it put |/\c| in the1059 pattern to ignore case or |/\C| to match case.1060 'smartcase' is not used.1061 If {pattern} is empty (e.g. // is specified), the last1062 used search pattern is used. |last-pattern|1063 1064 Flags:1065 'g' Without the 'g' flag each line is added only1066 once. With 'g' every match is added.1067 1068 'j' Without the 'j' flag Vim jumps to the first1069 match. With 'j' only the quickfix list is1070 updated. With the [!] any changes in the current1071 buffer are abandoned.1072 1073 'f' When the 'f' flag is specified, fuzzy string1074 matching is used to find matching lines. In this1075 case, {pattern} is treated as a literal string1076 instead of a regular expression. See1077 |fuzzy-matching| for more information about fuzzy1078 matching strings.1079 1080 |QuickFixCmdPre| and |QuickFixCmdPost| are triggered.1081 A file that is opened for matching may use a buffer1082 number, but it is reused if possible to avoid1083 consuming buffer numbers.1084 1085:{count}vim[grep] ...1086 When a number is put before the command this is used1087 as the maximum number of matches to find. Use1088 ":1vimgrep pattern file" to find only the first.1089 Useful if you only want to check if there is a match1090 and quit quickly when it's found.1091 1092 Every second or so the searched file name is displayed1093 to give you an idea of the progress made.1094 Examples: >1095 :vimgrep /an error/ *.c1096 :vimgrep /\<FileName\>/ *.h include/*1097 :vimgrep /myfunc/ **/*.c1098< For the use of "**" see |starstar-wildcard|.1099 1100:vim[grep][!] {pattern} {file} ...1101 Like above, but instead of enclosing the pattern in a1102 non-ID character use a white space separated pattern.1103 The pattern must start with an ID character.1104 Example: >1105 :vimgrep Error *.c1106<1107 *:lv* *:lvimgrep*1108:lv[imgrep][!] /{pattern}/[g][j][f] {file} ...1109:lv[imgrep][!] {pattern} {file} ...1110 Same as ":vimgrep", except the location list for the1111 current window is used instead of the quickfix list.1112 1113 *:vimgrepa* *:vimgrepadd*1114:vimgrepa[dd][!] /{pattern}/[g][j][f] {file} ...1115:vimgrepa[dd][!] {pattern} {file} ...1116 Just like ":vimgrep", but instead of making a new list1117 of errors the matches are appended to the current1118 list.1119 1120 *:lvimgrepa* *:lvimgrepadd*1121:lvimgrepa[dd][!] /{pattern}/[g][j][f] {file} ...1122:lvimgrepa[dd][!] {pattern} {file} ...1123 Same as ":vimgrepadd", except the location list for1124 the current window is used instead of the quickfix1125 list.1126 11275.2 External grep1128 1129Vim can interface with "grep" and grep-like programs (such as the GNU1130id-utils) in a similar way to its compiler integration (see |:make| above).1131 1132[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where1133"re" stands for Regular Expression.]1134 1135 *:gr* *:grep*1136:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of1137 'makeprg' and 'grepformat' instead of 'errorformat'.1138 When 'grepprg' is "internal" this works like1139 |:vimgrep|. Note that the pattern needs to be1140 enclosed in separator characters then.1141 If the encoding of the program output differs from the1142 'encoding' option, you can use the 'makeencoding'1143 option to specify the encoding.1144 1145 *:lgr* *:lgrep*1146:lgr[ep][!] [arguments] Same as ":grep", except the location list for the1147 current window is used instead of the quickfix list.1148 1149 *:grepa* *:grepadd*1150:grepa[dd][!] [arguments]1151 Just like ":grep", but instead of making a new list of1152 errors the matches are appended to the current list.1153 Example: >1154 :call setqflist([])1155 :bufdo grepadd! something %1156< The first command makes a new error list which is1157 empty. The second command executes "grepadd" for each1158 listed buffer. Note the use of ! to avoid that1159 ":grepadd" jumps to the first error, which is not1160 allowed with |:bufdo|.1161 An example that uses the argument list and avoids1162 errors for files without matches: >1163 :silent argdo try1164 \ | grepadd! something %1165 \ | catch /E480:/1166 \ | endtry"1167<1168 If the encoding of the program output differs from the1169 'encoding' option, you can use the 'makeencoding'1170 option to specify the encoding.1171 1172 *:lgrepa* *:lgrepadd*1173:lgrepa[dd][!] [arguments]1174 Same as ":grepadd", except the location list for the1175 current window is used instead of the quickfix list.1176 11775.3 Setting up external grep1178 1179If you have a standard "grep" program installed, the :grep command may work1180well with the defaults. The syntax is very similar to the standard command: >1181 1182 :grep foo *.c1183 1184Will search all files with the .c extension for the substring "foo". The1185arguments to :grep are passed straight to the "grep" program, so you can use1186whatever options your "grep" supports.1187 1188By default, :grep invokes grep with the -n option (show file and line1189numbers). You can change this with the 'grepprg' option. You will need to1190set 'grepprg' if:1191 1192a) You are using a program that isn't called "grep"1193b) You have to call grep with a full path1194c) You want to pass other options automatically (e.g. case insensitive1195 search.)1196 1197Once "grep" has executed, Vim parses the results using the 'grepformat'1198option. This option works in the same way as the 'errorformat' option - see1199that for details. You may need to change 'grepformat' from the default if1200your grep outputs in a non-standard format, or you are using some other