1*quickfix.txt* For Vim version 7.4. Last change: 2015 Sep 08 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 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| 18 19{Vi does not have any of these commands} 20 21The quickfix commands are not available when the |+quickfix| feature was 22disabled at compile time. 23 24============================================================================= 251. Using QuickFix commands *quickfix* *Quickfix* *E42* 26 27Vim has a special mode to speedup the edit-compile-edit cycle. This is 28inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga. 29The idea is to save the error messages from the compiler in a file and use Vim 30to jump to the errors one by one. You can examine each problem and fix it, 31without having to remember all the error messages. 32 33In Vim the quickfix commands are used more generally to find a list of 34positions in files. For example, |:vimgrep| finds pattern matches. You can 35use the positions in a script with the |getqflist()| function. Thus you can 36do a lot more than the edit/compile/fix cycle! 37 38If you are using Manx's Aztec C compiler on the Amiga look here for how to use 39it with Vim: |quickfix-manx|. If you are using another compiler you should 40save the error messages in a file and start Vim with "vim -q filename". An 41easy way to do this is with the |:make| command (see below). The 42'errorformat' option should be set to match the error messages from your 43compiler (see |errorformat| below). 44 45 *location-list* *E776* 46A location list is similar to a quickfix list and contains a list of positions 47in files. A location list is associated with a window and each window can 48have a separate location list. A location list can be associated with only 49one window. The location list is independent of the quickfix list. 50 51When a window with a location list is split, the new window gets a copy of the 52location list. When there are no references to a location list, the location 53list is destroyed. 54 55The following quickfix commands can be used. The location list commands are 56similar to the quickfix commands, replacing the 'c' prefix in the quickfix 57command with 'l'. 58 59 *:cc* 60:cc[!] [nr] Display error [nr]. If [nr] is omitted, the same 61 error is displayed again. Without [!] this doesn't 62 work when jumping to another buffer, the current buffer 63 has been changed, there is the only window for the 64 buffer and both 'hidden' and 'autowrite' are off. 65 When jumping to another buffer with [!] any changes to 66 the current buffer are lost, unless 'hidden' is set or 67 there is another window for this buffer. 68 The 'switchbuf' settings are respected when jumping 69 to a buffer. 70 71 *:ll* 72:ll[!] [nr] Same as ":cc", except the location list for the 73 current window is used instead of the quickfix list. 74 75 *:cn* *:cnext* *E553* 76:[count]cn[ext][!] Display the [count] next error in the list that 77 includes a file name. If there are no file names at 78 all, go to the [count] next error. See |:cc| for 79 [!] and 'switchbuf'. 80 81 *:lne* *:lnext* 82:[count]lne[xt][!] Same as ":cnext", except the location list for the 83 current window is used instead of the quickfix list. 84 85:[count]cN[ext][!] *:cp* *:cprevious* *:cN* *:cNext* 86:[count]cp[revious][!] Display the [count] previous error in the list that 87 includes a file name. If there are no file names at 88 all, go to the [count] previous error. See |:cc| for 89 [!] and 'switchbuf'. 90 91 92:[count]lN[ext][!] *:lp* *:lprevious* *:lN* *:lNext* 93:[count]lp[revious][!] Same as ":cNext" and ":cprevious", except the location 94 list for the current window is used instead of the 95 quickfix list. 96 97 *:cnf* *:cnfile* 98:[count]cnf[ile][!] Display the first error in the [count] next file in 99 the list that includes a file name. If there are no 100 file names at all or if there is no next file, go to 101 the [count] next error. See |:cc| for [!] and 102 'switchbuf'. 103 104 *:lnf* *:lnfile* 105:[count]lnf[ile][!] Same as ":cnfile", except the location list for the 106 current window is used instead of the quickfix list. 107 108:[count]cNf[ile][!] *:cpf* *:cpfile* *:cNf* *:cNfile* 109:[count]cpf[ile][!] Display the last error in the [count] previous file in 110 the list that includes a file name. If there are no 111 file names at all or if there is no next file, go to 112 the [count] previous error. See |:cc| for [!] and 113 'switchbuf'. 114 115 116:[count]lNf[ile][!] *:lpf* *:lpfile* *:lNf* *:lNfile* 117:[count]lpf[ile][!] Same as ":cNfile" and ":cpfile", except the location 118 list for the current window is used instead of the 119 quickfix list. 120 121 *:crewind* *:cr* 122:cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST 123 error is displayed. See |:cc|. 124 125 *:lrewind* *:lr* 126:lr[ewind][!] [nr] Same as ":crewind", except the location list for the 127 current window is used instead of the quickfix list. 128 129 *:cfirst* *:cfir* 130:cfir[st][!] [nr] Same as ":crewind". 131 132 *:lfirst* *:lfir* 133:lfir[st][!] [nr] Same as ":lrewind". 134 135 *:clast* *:cla* 136:cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST 137 error is displayed. See |:cc|. 138 139 *:llast* *:lla* 140:lla[st][!] [nr] Same as ":clast", except the location list for the 141 current window is used instead of the quickfix list. 142 143 *:cq* *:cquit* 144:cq[uit][!] Quit Vim with an error code, so that the compiler 145 will not compile the same file again. 146 WARNING: All changes in files are lost! Also when the 147 [!] is not used. It works like ":qall!" |:qall|, 148 except that Vim returns a non-zero exit code. 149 150 *:cf* *:cfile* 151:cf[ile][!] [errorfile] Read the error file and jump to the first error. 152 This is done automatically when Vim is started with 153 the -q option. You can use this command when you 154 keep Vim running while compiling. If you give the 155 name of the errorfile, the 'errorfile' option will 156 be set to [errorfile]. See |:cc| for [!]. 157 158 *:lf* *:lfile* 159:lf[ile][!] [errorfile] Same as ":cfile", except the location list for the 160 current window is used instead of the quickfix list. 161 You can not use the -q command-line option to set 162 the location list. 163 164 165:cg[etfile] [errorfile] *:cg* *:cgetfile* 166 Read the error file. Just like ":cfile" but don't 167 jump to the first error. 168 169 170:lg[etfile] [errorfile] *:lg* *:lgetfile* 171 Same as ":cgetfile", except the location list for the 172 current window is used instead of the quickfix list. 173 174 *:caddf* *:caddfile* 175:caddf[ile] [errorfile] Read the error file and add the errors from the 176 errorfile to the current quickfix list. If a quickfix 177 list is not present, then a new list is created. 178 179 *:laddf* *:laddfile* 180:laddf[ile] [errorfile] Same as ":caddfile", except the location list for the 181 current window is used instead of the quickfix list. 182 183 *:cb* *:cbuffer* *E681* 184:cb[uffer][!] [bufnr] Read the error list from the current buffer. 185 When [bufnr] is given it must be the number of a 186 loaded buffer. That buffer will then be used instead 187 of the current buffer. 188 A range can be specified for the lines to be used. 189 Otherwise all lines in the buffer are used. 190 See |:cc| for [!]. 191 192 *:lb* *:lbuffer* 193:lb[uffer][!] [bufnr] Same as ":cbuffer", except the location list for the 194 current window is used instead of the quickfix list. 195 196 *:cgetb* *:cgetbuffer* 197:cgetb[uffer] [bufnr] Read the error list from the current buffer. Just 198 like ":cbuffer" but don't jump to the first error. 199 200 *:lgetb* *:lgetbuffer* 201:lgetb[uffer] [bufnr] Same as ":cgetbuffer", except the location list for 202 the current window is used instead of the quickfix 203 list. 204 205 *:cad* *:caddbuffer* 206:cad[dbuffer] [bufnr] Read the error list from the current buffer and add 207 the errors to the current quickfix list. If a 208 quickfix list is not present, then a new list is 209 created. Otherwise, same as ":cbuffer". 210 211 *:laddb* *:laddbuffer* 212:laddb[uffer] [bufnr] Same as ":caddbuffer", except the location list for 213 the current window is used instead of the quickfix 214 list. 215 216 *:cex* *:cexpr* *E777* 217:cex[pr][!] {expr} Create a quickfix list using the result of {expr} and 218 jump to the first error. 219 If {expr} is a String, then each new-line terminated 220 line in the String is processed using the global value 221 of 'errorformat' and the result is added to the 222 quickfix list. 223 If {expr} is a List, then each String item in the list 224 is processed and added to the quickfix list. Non 225 String items in the List are ignored. 226 See |:cc| for [!]. 227 Examples: > 228 :cexpr system('grep -n xyz *') 229 :cexpr getline(1, '$') 230< 231 *:lex* *:lexpr* 232:lex[pr][!] {expr} Same as |:cexpr|, except the location list for the 233 current window is used instead of the quickfix list. 234 235 *:cgete* *:cgetexpr* 236:cgete[xpr] {expr} Create a quickfix list using the result of {expr}. 237 Just like |:cexpr|, but don't jump to the first error. 238 239 *:lgete* *:lgetexpr* 240:lgete[xpr] {expr} Same as |:cgetexpr|, except the location list for the 241 current window is used instead of the quickfix list. 242 243 *:cadde* *:caddexpr* 244:cadde[xpr] {expr} Evaluate {expr} and add the resulting lines to the 245 current quickfix list. If a quickfix list is not 246 present, then a new list is created. The current 247 cursor position will not be changed. See |:cexpr| for 248 more information. 249 Example: > 250 :g/mypattern/caddexpr expand("%") . ":" . line(".") . ":" . getline(".") 251< 252 *:lad* *:laddexpr* 253:lad[dexpr] {expr} Same as ":caddexpr", except the location list for the 254 current window is used instead of the quickfix list. 255 256 *:cl* *:clist* 257:cl[ist] [from] [, [to]] 258 List all errors that are valid |quickfix-valid|. 259 If numbers [from] and/or [to] are given, the respective 260 range of errors is listed. A negative number counts 261 from the last error backwards, -1 being the last error. 262 The 'switchbuf' settings are respected when jumping 263 to a buffer. 264 265:cl[ist]! [from] [, [to]] 266 List all errors. 267 268 *:lli* *:llist* 269:lli[st] [from] [, [to]] 270 Same as ":clist", except the location list for the 271 current window is used instead of the quickfix list. 272 273:lli[st]! [from] [, [to]] 274 List all the entries in the location list for the 275 current window. 276 277If you insert or delete lines, mostly the correct error location is still 278found because hidden marks are used. Sometimes, when the mark has been 279deleted for some reason, the message "line changed" is shown to warn you that 280the error location may not be correct. If you quit Vim and start again the 281marks are lost and the error locations may not be correct anymore. 282 283If vim is built with |+autocmd| support, two autocommands are available for 284running commands before and after a quickfix command (':make', ':grep' and so 285on) is executed. See |QuickFixCmdPre| and |QuickFixCmdPost| for details. 286 287 *QuickFixCmdPost-example* 288When 'encoding' differs from the locale, the error messages may have a 289different encoding from what Vim is using. To convert the messages you can 290use this code: > 291 function QfMakeConv() 292 let qflist = getqflist() 293 for i in qflist 294 let i.text = iconv(i.text, "cp936", "utf-8") 295 endfor 296 call setqflist(qflist) 297 endfunction 298 299 au QuickfixCmdPost make call QfMakeConv() 300 301 302EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST: 303 *:cdo* 304:cdo[!] {cmd} Execute {cmd} in each valid entry in the quickfix list. 305 It works like doing this: > 306 :cfirst 307 :{cmd} 308 :cnext 309 :{cmd} 310 etc. 311< When the current file can't be |abandon|ed and the [!] 312 is not present, the command fails. 313 When an error is detected excecution stops. 314 The last buffer (or where an error occurred) becomes 315 the current buffer. 316 {cmd} can contain '|' to concatenate several commands. 317 318 Only valid entries in the quickfix list are used. 319 A range can be used to select entries, e.g.: > 320 :10,$cdo cmd 321< To skip entries 1 to 9. 322 323 Note: While this command is executing, the Syntax 324 autocommand event is disabled by adding it to 325 'eventignore'. This considerably speeds up editing 326 each buffer. 327 {not in Vi} {not available when compiled without the 328 |+listcmds| feature} 329 Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|, 330 |:ldo|, |:cfdo| and |:lfdo|. 331 332 *:cfdo* 333:cfdo[!] {cmd} Execute {cmd} in each file in the quickfix list. 334 It works like doing this: > 335 :cfirst 336 :{cmd} 337 :cnfile 338 :{cmd} 339 etc. 340< Otherwise it works the same as `:cdo`. 341 {not in Vi} {not available when compiled without the 342 |+listcmds| feature} 343 344 *:ldo* 345:ld[o][!] {cmd} Execute {cmd} in each valid entry in the location list 346 for the current window. 347 It works like doing this: > 348 :lfirst 349 :{cmd} 350 :lnext 351 :{cmd} 352 etc. 353< Only valid entries in the location list are used. 354 Otherwise it works the same as `:cdo`. 355 {not in Vi} {not available when compiled without the 356 |+listcmds| feature} 357 358 *:lfdo* 359:lfdo[!] {cmd} Execute {cmd} in each file in the location list for 360 the current window. 361 It works like doing this: > 362 :lfirst 363 :{cmd} 364 :lnfile 365 :{cmd} 366 etc. 367< Otherwise it works the same as `:ldo`. 368 {not in Vi} {not available when compiled without the 369 |+listcmds| feature} 370 371============================================================================= 3722. The error window *quickfix-window* 373 374 *:cope* *:copen* *w:quickfix_title* 375:cope[n] [height] Open a window to show the current list of errors. 376 377 When [height] is given, the window becomes that high 378 (if there is room). When [height] is omitted the 379 window is made ten lines high. 380 381 If there already is a quickfix window, it will be made 382 the current window. It is not possible to open a 383 second quickfix window. If [height] is given the 384 existing window will be resized to it. 385 386 The window will contain a special buffer, with 387 'buftype' equal to "quickfix". Don't change this! 388 The window will have the w:quickfix_title variable set 389 which will indicate the command that produced the 390 quickfix list. This can be used to compose a custom 391 status line if the value of 'statusline' is adjusted 392 properly. 393 394 *:lop* *:lopen* 395:lop[en] [height] Open a window to show the location list for the 396 current window. Works only when the location list for 397 the current window is present. You can have more than 398 one location window opened at a time. Otherwise, it 399 acts the same as ":copen". 400 401 *:ccl* *:cclose* 402:ccl[ose] Close the quickfix window. 403 404 *:lcl* *:lclose* 405:lcl[ose] Close the window showing the location list for the 406 current window. 407 408 *:cw* *:cwindow* 409:cw[indow] [height] Open the quickfix window when there are recognized 410 errors. If the window is already open and there are 411 no recognized errors, close the window. 412 413 *:lw* *:lwindow* 414:lw[indow] [height] Same as ":cwindow", except use the window showing the 415 location list for the current window. 416 417Normally the quickfix window is at the bottom of the screen. If there are 418vertical splits, it's at the bottom of the rightmost column of windows. To 419make it always occupy the full width: > 420 :botright cwindow 421You can move the window around with |window-moving| commands. 422For example, to move it to the top: CTRL-W K 423The 'winfixheight' option will be set, which means that the window will mostly 424keep its height, ignoring 'winheight' and 'equalalways'. You can change the 425height manually (e.g., by dragging the status line above it with the mouse). 426 427In the quickfix window, each line is one error. The line number is equal to 428the error number. You can use ":.cc" to jump to the error under the cursor. 429Hitting the <Enter> key or double-clicking the mouse on a line has the same 430effect. The file containing the error is opened in the window above the 431quickfix window. If there already is a window for that file, it is used 432instead. If the buffer in the used window has changed, and the error is in 433another file, jumping to the error will fail. You will first have to make 434sure the window contains a buffer which can be abandoned. 435 *CTRL-W_<Enter>* *CTRL-W_<CR>* 436You can use CTRL-W <Enter> to open a new window and jump to the error there. 437 438When the quickfix window has been filled, two autocommand events are 439triggered. First the 'filetype' option is set to "qf", which triggers the 440FileType event. Then the BufReadPost event is triggered, using "quickfix" for 441the buffer name. This can be used to perform some action on the listed 442errors. Example: > 443 au BufReadPost quickfix setlocal modifiable 444 \ | silent exe 'g/^/s//\=line(".")." "/' 445 \ | setlocal nomodifiable 446This prepends the line number to each line. Note the use of "\=" in the 447substitute string of the ":s" command, which is used to evaluate an 448expression. 449The BufWinEnter event is also triggered, again using "quickfix" for the buffer 450name. 451 452Note: Making changes in the quickfix window has no effect on the list of 453errors. 'modifiable' is off to avoid making changes. If you delete or insert 454lines anyway, the relation between the text and the error number is messed up. 455If you really want to do this, you could write the contents of the quickfix 456window to a file and use ":cfile" to have it parsed and used as the new error 457list. 458 459 *location-list-window* 460The location list window displays the entries in a location list. When you 461open a location list window, it is created below the current window and 462displays the location list for the current window. The location list window 463is similar to the quickfix window, except that you can have more than one 464location list window open at a time. When you use a location list command in 465this window, the displayed location list is used. 466 467When you select a file from the location list window, the following steps are 468used to find a window to edit the file: 469 4701. If a window with the location list displayed in the location list window is 471 present, then the file is opened in that window. 4722. If the above step fails and if the file is already opened in another 473 window, then that window is used. 4743. If the above step fails then an existing window showing a buffer with 475 'buftype' not set is used. 4764. If the above step fails, then the file is edited in a new window. 477 478In all of the above cases, if the location list for the selected window is not 479yet set, then it is set to the location list displayed in the location list 480window. 481 482============================================================================= 4833. Using more than one list of errors *quickfix-error-lists* 484 485So far has been assumed that there is only one list of errors. Actually the 486ten last used lists are remembered. When starting a new list, the previous 487ones are automatically kept. Two commands can be used to access older error 488lists. They set one of the existing error lists as the current one. 489 490 *:colder* *:col* *E380* 491:col[der] [count] Go to older error list. When [count] is given, do 492 this [count] times. When already at the oldest error 493 list, an error message is given. 494 495 *:lolder* *:lol* 496:lol[der] [count] Same as ":colder", except use the location list for 497 the current window instead of the quickfix list. 498 499 *:cnewer* *:cnew* *E381* 500:cnew[er] [count] Go to newer error list. When [count] is given, do 501 this [count] times. When already at the newest error 502 list, an error message is given. 503 504 *:lnewer* *:lnew* 505:lnew[er] [count] Same as ":cnewer", except use the location list for 506 the current window instead of the quickfix list. 507 508When adding a new error list, it becomes the current list. 509 510When ":colder" has been used and ":make" or ":grep" is used to add a new error 511list, one newer list is overwritten. This is especially useful if you are 512browsing with ":grep" |grep|. If you want to keep the more recent error 513lists, use ":cnewer 99" first. 514 515============================================================================= 5164. Using :make *:make_makeprg* 517 518 *:mak* *:make* 519:mak[e][!] [arguments] 1. If vim was built with |+autocmd|, all relevant 520 |QuickFixCmdPre| autocommands are executed. 521 2. If the 'autowrite' option is on, write any changed 522 buffers 523 3. An errorfile name is made from 'makeef'. If 524 'makeef' doesn't contain "##", and a file with this 525 name already exists, it is deleted. 526 4. The program given with the 'makeprg' option is 527 started (default "make") with the optional 528 [arguments] and the output is saved in the 529 errorfile (for Unix it is also echoed on the 530 screen). 531 5. The errorfile is read using 'errorformat'. 532 6. If vim was built with |+autocmd|, all relevant 533 |QuickFixCmdPost| autocommands are executed. 534 See example below. 535 7. If [!] is not given the first error is jumped to. 536 8. The errorfile is deleted. 537 9. You can now move through the errors with commands 538 like |:cnext| and |:cprevious|, see above. 539 This command does not accept a comment, any " 540 characters are considered part of the arguments. 541 542 *:lmak* *:lmake* 543:lmak[e][!] [arguments] 544 Same as ":make", except the location list for the 545 current window is used instead of the quickfix list. 546 547The ":make" command executes the command given with the 'makeprg' option. 548This is done by passing the command to the shell given with the 'shell' 549option. This works almost like typing 550 551 ":!{makeprg} [arguments] {shellpipe} {errorfile}". 552 553{makeprg} is the string given with the 'makeprg' option. Any command can be 554used, not just "make". Characters '%' and '#' are expanded as usual on a 555command-line. You can use "%<" to insert the current file name without 556extension, or "#<" to insert the alternate file name without extension, for 557example: > 558 :set makeprg=make\ #<.o 559 560[arguments] is anything that is typed after ":make". 561{shellpipe} is the 'shellpipe' option. 562{errorfile} is the 'makeef' option, with ## replaced to make it unique. 563 564The placeholder "$*" can be used for the argument list in {makeprg} if the 565command needs some additional characters after its arguments. The $* is 566replaced then by all arguments. Example: > 567 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} 568or simpler > 569 :let &mp = 'latex \\nonstopmode \\input\{$*}' 570"$*" can be given multiple times, for example: > 571 :set makeprg=gcc\ -o\ $*\ $* 572 573The 'shellpipe' option defaults to ">" for the Amiga, MS-DOS and Win32. This 574means that the output of the compiler is saved in a file and not shown on the 575screen directly. For Unix "| tee" is used. The compiler output is shown on 576the screen and saved in a file the same time. Depending on the shell used 577"|& tee" or "2>&1| tee" is the default, so stderr output will be included. 578 579If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful 580for compilers that write to an errorfile themselves (e.g., Manx's Amiga C). 581 582 583Using QuickFixCmdPost to fix the encoding ~ 584 585It may be that 'encoding' is set to an encoding that differs from the messages 586your build program produces. This example shows how to fix this after Vim has 587read the error messages: > 588 589 function QfMakeConv() 590 let qflist = getqflist() 591 for i in qflist 592 let i.text = iconv(i.text, "cp936", "utf-8") 593 endfor 594 call setqflist(qflist) 595 endfunction 596 597 au QuickfixCmdPost make call QfMakeConv() 598 599(Example by Faque Cheng) 600 601============================================================================== 6025. Using :vimgrep and :grep *grep* *lid* 603 604Vim has two ways to find matches for a pattern: Internal and external. The 605advantage of the internal grep is that it works on all systems and uses the 606powerful Vim search patterns. An external grep program can be used when the 607Vim grep does not do what you want. 608 609The internal method will be slower, because files are read into memory. The 610advantages are: 611- Line separators and encoding are automatically recognized, as if a file is 612 being edited. 613- Uses Vim search patterns. Multi-line patterns can be used. 614- When plugins are enabled: compressed and remote files can be searched. 615 |gzip| |netrw| 616 617To be able to do this Vim loads each file as if it is being edited. When 618there is no match in the file the associated buffer is wiped out again. The 619'hidden' option is ignored here to avoid running out of memory or file 620descriptors when searching many files. However, when the |:hide| command 621modifier is used the buffers are kept loaded. This makes following searches 622in the same files a lot faster. 623 624Note that |:copen| (or |:lopen| for |:lgrep|) may be used to open a buffer 625containing the search results in linked form. The |:silent| command may be 626used to suppress the default full screen grep output. The ":grep!" form of 627the |:grep| command doesn't jump to the first match automatically. These 628commands can be combined to create a NewGrep command: > 629 630 command! -nargs=+ NewGrep execute 'silent grep! <args>' | copen 42 631 632 6335.1 using Vim's internal grep 634 635 *:vim* *:vimgrep* *E682* *E683* 636:vim[grep][!] /{pattern}/[g][j] {file} ... 637 Search for {pattern} in the files {file} ... and set 638 the error list to the matches. Files matching 639 'wildignore' are ignored; files in 'suffixes' are 640 searched last. 641 Without the 'g' flag each line is added only once. 642 With 'g' every match is added. 643 644 {pattern} is a Vim search pattern. Instead of 645 enclosing it in / any non-ID character (see 646 |'isident'|) can be used, so long as it does not 647 appear in {pattern}. 648 'ignorecase' applies. To overrule it put |/\c| in the 649 pattern to ignore case or |/\C| to match case. 650 'smartcase' is not used. 651 If {pattern} is empty (e.g. // is specified), the last 652 used search pattern is used. |last-pattern| 653 654 When a number is put before the command this is used 655 as the maximum number of matches to find. Use 656 ":1vimgrep pattern file" to find only the first. 657 Useful if you only want to check if there is a match 658 and quit quickly when it's found. 659 660 Without the 'j' flag Vim jumps to the first match. 661 With 'j' only the quickfix list is updated. 662 With the [!] any changes in the current buffer are 663 abandoned. 664 665 Every second or so the searched file name is displayed 666 to give you an idea of the progress made. 667 Examples: > 668 :vimgrep /an error/ *.c 669 :vimgrep /\<FileName\>/ *.h include/* 670 :vimgrep /myfunc/ **/*.c 671< For the use of "**" see |starstar-wildcard|. 672 673:vim[grep][!] {pattern} {file} ... 674 Like above, but instead of enclosing the pattern in a 675 non-ID character use a white-separated pattern. The 676 pattern must start with an ID character. 677 Example: > 678 :vimgrep Error *.c 679< 680 *:lv* *:lvimgrep* 681:lv[imgrep][!] /{pattern}/[g][j] {file} ... 682:lv[imgrep][!] {pattern} {file} ... 683 Same as ":vimgrep", except the location list for the 684 current window is used instead of the quickfix list. 685 686 *:vimgrepa* *:vimgrepadd* 687:vimgrepa[dd][!] /{pattern}/[g][j] {file} ... 688:vimgrepa[dd][!] {pattern} {file} ... 689 Just like ":vimgrep", but instead of making a new list 690 of errors the matches are appended to the current 691 list. 692 693 *:lvimgrepa* *:lvimgrepadd* 694:lvimgrepa[dd][!] /{pattern}/[g][j] {file} ... 695:lvimgrepa[dd][!] {pattern} {file} ... 696 Same as ":vimgrepadd", except the location list for 697 the current window is used instead of the quickfix 698 list. 699 7005.2 External grep 701 702Vim can interface with "grep" and grep-like programs (such as the GNU 703id-utils) in a similar way to its compiler integration (see |:make| above). 704 705[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where 706"re" stands for Regular Expression.] 707 708 *:gr* *:grep* 709:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of 710 'makeprg' and 'grepformat' instead of 'errorformat'. 711 When 'grepprg' is "internal" this works like 712 |:vimgrep|. Note that the pattern needs to be 713 enclosed in separator characters then. 714 715 *:lgr* *:lgrep* 716:lgr[ep][!] [arguments] Same as ":grep", except the location list for the 717 current window is used instead of the quickfix list. 718 719 *:grepa* *:grepadd* 720:grepa[dd][!] [arguments] 721 Just like ":grep", but instead of making a new list of 722 errors the matches are appended to the current list. 723 Example: > 724 :call setqflist([]) 725 :bufdo grepadd! something % 726< The first command makes a new error list which is 727 empty. The second command executes "grepadd" for each 728 listed buffer. Note the use of ! to avoid that 729 ":grepadd" jumps to the first error, which is not 730 allowed with |:bufdo|. 731 An example that uses the argument list and avoids 732 errors for files without matches: > 733 :silent argdo try 734 \ | grepadd! something % 735 \ | catch /E480:/ 736 \ | endtry" 737< 738 *:lgrepa* *:lgrepadd* 739:lgrepa[dd][!] [arguments] 740 Same as ":grepadd", except the location list for the 741 current window is used instead of the quickfix list. 742 7435.3 Setting up external grep 744 745If you have a standard "grep" program installed, the :grep command may work 746well with the defaults. The syntax is very similar to the standard command: > 747 748 :grep foo *.c 749 750Will search all files with the .c extension for the substring "foo". The 751arguments to :grep are passed straight to the "grep" program, so you can use 752whatever options your "grep" supports. 753 754By default, :grep invokes grep with the -n option (show file and line 755numbers). You can change this with the 'grepprg' option. You will need to set 756'grepprg' if: 757 758a) You are using a program that isn't called "grep" 759b) You have to call grep with a full path 760c) You want to pass other options automatically (e.g. case insensitive 761 search.) 762 763Once "grep" has executed, Vim parses the results using the 'grepformat' 764option. This option works in the same way as the 'errorformat' option - see 765that for details. You may need to change 'grepformat' from the default if 766your grep outputs in a non-standard format, or you are using some other 767program with a special format. 768 769Once the results are parsed, Vim loads the first file containing a match and 770jumps to the appropriate line, in the same way that it jumps to a compiler 771error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc. 772commands to see the other matches. 773 774 7755.4 Using :grep with id-utils 776 777You can set up :grep to work with the GNU id-utils like this: > 778 779 :set grepprg=lid\ -Rgrep\ -s 780 :set grepformat=%f:%l:%m 781 782then > 783 :grep (regexp) 784 785works just as you'd expect. 786(provided you remembered to mkid first :) 787 788 7895.5 Browsing source code with :vimgrep or :grep 790 791Using the stack of error lists that Vim keeps, you can browse your files to 792look for functions and the functions they call. For example, suppose that you 793have to add an argument to the read_file() function. You enter this command: > 794 795 :vimgrep /\<read_file\>/ *.c 796 797You use ":cn" to go along the list of matches and add the argument. At one 798place you have to get the new argument from a higher level function msg(), and 799need to change that one too. Thus you use: > 800 801 :vimgrep /\<msg\>/ *.c 802 803While changing the msg() functions, you find another function that needs to 804get the argument from a higher level. You can again use ":vimgrep" to find 805these functions. Once you are finished with one function, you can use > 806 807 :colder 808 809to go back to the previous one. 810 811This works like browsing a tree: ":vimgrep" goes one level deeper, creating a 812list of branches. ":colder" goes back to the previous level. You can mix 813this use of ":vimgrep" and "colder" to browse all the locations in a tree-like 814way. If you do this consistently, you will find all locations without the 815need to write down a "todo" list. 816 817============================================================================= 8186. Selecting a compiler *compiler-select* 819 820 *:comp* *:compiler* *E666* 821:comp[iler][!] {name} Set options to work with compiler {name}. 822 Without the "!" options are set for the 823 current buffer. With "!" global options are 824 set. 825 If you use ":compiler foo" in "file.foo" and 826 then ":compiler! bar" in another buffer, Vim 827 will keep on using "foo" in "file.foo". 828 {not available when compiled without the 829 |+eval| feature} 830 831 832The Vim plugins in the "compiler" directory will set options to use the 833selected compiler. For ":compiler" local options are set, for ":compiler!" 834global options. 835 *current_compiler* 836To support older Vim versions, the plugins always use "current_compiler" and 837not "b:current_compiler". What the command actually does is the following: 838 839- Delete the "current_compiler" and "b:current_compiler" variables. 840- Define the "CompilerSet" user command. With "!" it does ":set", without "!" 841 it does ":setlocal". 842- Execute ":runtime! compiler/{name}.vim". The plugins are expected to set 843 options with "CompilerSet" and set the "current_compiler" variable to the 844 name of the compiler. 845- Delete the "CompilerSet" user command. 846- Set "b:current_compiler" to the value of "current_compiler". 847- Without "!" the old value of "current_compiler" is restored. 848 849 850For writing a compiler plugin, see |write-compiler-plugin|. 851 852 853GCC *quickfix-gcc* *compiler-gcc* 854 855There's one variable you can set for the GCC compiler: 856 857g:compiler_gcc_ignore_unmatched_lines 858 Ignore lines that don't match any patterns 859 defined for GCC. Useful if output from 860 commands run from make are generating false 861 positives. 862 863 864MANX AZTEC C *quickfix-manx* *compiler-manx* 865 866To use Vim with Manx's Aztec C compiler on the Amiga you should do the 867following: 868- Set the CCEDIT environment variable with the command: > 869 mset "CCEDIT=vim -q" 870- Compile with the -qf option. If the compiler finds any errors, Vim is 871 started and the cursor is positioned on the first error. The error message 872 will be displayed on the last line. You can go to other errors with the 873 commands mentioned above. You can fix the errors and write the file(s). 874- If you exit Vim normally the compiler will re-compile the same file. If you 875 exit with the :cq command, the compiler will terminate. Do this if you 876 cannot fix the error, or if another file needs to be compiled first. 877 878There are some restrictions to the Quickfix mode on the Amiga. The 879compiler only writes the first 25 errors to the errorfile (Manx's 880documentation does not say how to get more). If you want to find the others, 881you will have to fix a few errors and exit the editor. After recompiling, 882up to 25 remaining errors will be found. 883 884If Vim was started from the compiler, the :sh and some :! commands will not 885work, because Vim is then running in the same process as the compiler and 886stdin (standard input) will not be interactive. 887 888 889PERL *quickfix-perl* *compiler-perl* 890 891The Perl compiler plugin doesn't actually compile, but invokes Perl's internal 892syntax checking feature and parses the output for possible errors so you can 893correct them in quick-fix mode. 894 895Warnings are forced regardless of "no warnings" or "$^W = 0" within the file 896being checked. To disable this set g:perl_compiler_force_warnings to a zero 897value. For example: > 898 let g:perl_compiler_force_warnings = 0 899 900 901PYUNIT COMPILER *compiler-pyunit* 902 903This is not actually a compiler, but a unit testing framework for the 904Python language. It is included into standard Python distribution 905starting from version 2.0. For older versions, you can get it from 906http://pyunit.sourceforge.net. 907 908When you run your tests with the help of the framework, possible errors 909are parsed by Vim and presented for you in quick-fix mode. 910 911Unfortunately, there is no standard way to run the tests. 912The alltests.py script seems to be used quite often, that's all. 913Useful values for the 'makeprg' options therefore are: 914 setlocal makeprg=./alltests.py " Run a testsuite 915 setlocal makeprg=python\ %:S " Run a single testcase 916 917Also see http://vim.sourceforge.net/tip_view.php?tip_id=280. 918 919 920TEX COMPILER *compiler-tex* 921 922Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim) 923uses make command if possible. If the compiler finds a file named "Makefile" 924or "makefile" in the current directory, it supposes that you want to process 925your *TeX files with make, and the makefile does the right work. In this case 926compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched. If 927neither "Makefile" nor "makefile" is found, the compiler will not use make. 928You can force the compiler to ignore makefiles by defining 929b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for 930existence only). 931 932If the compiler chose not to use make, it need to choose a right program for 933processing your input. If b:tex_flavor or g:tex_flavor (in this precedence) 934variable exists, it defines TeX flavor for :make (actually, this is the name 935of executed command), and if both variables do not exist, it defaults to 936"latex". For example, while editing chapter2.tex \input-ed from mypaper.tex 937written in AMS-TeX: > 938 939 :let b:tex_flavor = 'amstex' 940 :compiler tex 941< [editing...] > 942 :make mypaper 943 944Note that you must specify a name of the file to process as an argument (to 945process the right file when editing \input-ed or \include-ed file; portable 946solution for substituting % for no arguments is welcome). This is not in the 947semantics of make, where you specify a target, not source, but you may specify 948filename without extension ".tex" and mean this as "make filename.dvi or 949filename.pdf or filename.some_result_extension according to compiler". 950 951Note: tex command line syntax is set to usable both for MikTeX (suggestion 952by Srinath Avadhanula) and teTeX (checked by Artem Chuprina). Suggestion 953from |errorformat-LaTeX| is too complex to keep it working for different 954shells and OSes and also does not allow to use other available TeX options, 955if any. If your TeX doesn't support "-interaction=nonstopmode", please 956report it with different means to express \nonstopmode from the command line. 957 958============================================================================= 9597. The error format *error-file-format* 960 961 *errorformat* *E372* *E373* *E374* 962 *E375* *E376* *E377* *E378* 963The 'errorformat' option specifies a list of formats that are recognized. The 964first format that matches with an error message is used. You can add several 965formats for different messages your compiler produces, or even entries for 966multiple compilers. See |efm-entries|. 967 968Each entry in 'errorformat' is a scanf-like string that describes the format. 969First, you need to know how scanf works. Look in the documentation of your 970C compiler. Below you find the % items that Vim understands. Others are 971invalid. 972 973Special characters in 'errorformat' are comma and backslash. See 974|efm-entries| for how to deal with them. Note that a literal "%" is matched 975by "%%", thus it is not escaped with a backslash. 976Keep in mind that in the `:make` and `:grep` output all NUL characters are 977replaced with SOH (0x01). 978 979Note: By default the difference between upper and lowercase is ignored. If 980you want to match case, add "\C" to the pattern |/\C|. 981 982 983Basic items 984 985 %f file name (finds a string) 986 %l line number (finds a number) 987 %c column number (finds a number representing character 988 column of the error, (1 <tab> == 1 character column)) 989 %v virtual column number (finds a number representing 990 screen column of the error (1 <tab> == 8 screen 991 columns)) 992 %t error type (finds a single character) 993 %n error number (finds a number) 994 %m error message (finds a string) 995 %r matches the "rest" of a single-line file message %O/P/Q 996 %p pointer line (finds a sequence of '-', '.', ' ' or 997 tabs and uses the length for the column number) 998 %*{conv} any scanf non-assignable conversion 999 %% the single '%' character 1000 %s search text (finds a string) 1001 1002The "%f" conversion may depend on the current 'isfname' setting. "~/" is 1003expanded to the home directory and environment variables are expanded. 1004 1005The "%f" and "%m" conversions have to detect the end of the string. This 1006normally happens by matching following characters and items. When nothing is 1007following the rest of the line is matched. If "%f" is followed by a '%' or a 1008backslash, it will look for a sequence of 'isfname' characters. 1009 1010On MS-DOS, MS-Windows and OS/2 a leading "C:" will be included in "%f", even 1011when using "%f:". This means that a file name which is a single alphabetical 1012letter will not be detected. 1013 1014The "%p" conversion is normally followed by a "^". It's used for compilers 1015that output a line like: > 1016 ^ 1017or > 1018 ---------^ 1019to indicate the column of the error. This is to be used in a multi-line error 1020message. See |errorformat-javac| for a useful example. 1021 1022The "%s" conversion specifies the text to search for to locate the error line. 1023The text is used as a literal string. The anchors "^" and "$" are added to 1024the text to locate the error line exactly matching the search text and the 1025text is prefixed with the "\V" atom to make it "very nomagic". The "%s" 1026conversion can be used to locate lines without a line number in the error 1027output. Like the output of the "grep" shell command. 1028When the pattern is present the line number will not be used. 1029 1030Changing directory 1031 1032The following uppercase conversion characters specify the type of special 1033format strings. At most one of them may be given as a prefix at the begin 1034of a single comma-separated format pattern. 1035Some compilers produce messages that consist of directory names that have to 1036be prepended to each file name read by %f (example: GNU make). The following 1037codes can be used to scan these directory names; they will be stored in an 1038internal directory stack. *E379* 1039 %D "enter directory" format string; expects a following 1040 %f that finds the directory name 1041 %X "leave directory" format string; expects following %f 1042 1043When defining an "enter directory" or "leave directory" format, the "%D" or 1044"%X" has to be given at the start of that substring. Vim tracks the directory 1045changes and prepends the current directory to each erroneous file found with a 1046relative path. See |quickfix-directory-stack| for details, tips and 1047limitations. 1048 1049 1050Multi-line messages *errorformat-multi-line* 1051 1052It is possible to read the output of programs that produce multi-line 1053messages, i.e. error strings that consume more than one line. Possible 1054prefixes are: 1055 %E start of a multi-line error message 1056 %W start of a multi-line warning message 1057 %I start of a multi-line informational message 1058 %A start of a multi-line message (unspecified type) 1059 %> for next line start with current pattern again |efm-%>| 1060 %C continuation of a multi-line message 1061 %Z end of a multi-line message 1062These can be used with '+' and '-', see |efm-ignore| below. 1063 1064Using "\n" in the pattern won't work to match multi-line messages. 1065 1066Example: Your compiler happens to write out errors in the following format 1067(leading line numbers not being part of the actual output): 1068 1069 1 Error 275 ~ 1070 2 line 42 ~ 1071 3 column 3 ~ 1072 4 ' ' expected after '--' ~ 1073 1074The appropriate error format string has to look like this: > 1075 :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%m 1076 1077And the |:clist| error message generated for this error is: 1078 1079 1:42 col 3 error 275: ' ' expected after '--' 1080 1081Another example: Think of a Python interpreter that produces the following 1082error message (line numbers are not part of the actual output): 1083 1084 1 ============================================================== 1085 2 FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest) 1086 3 -------------------------------------------------------------- 1087 4 Traceback (most recent call last): 1088 5 File "unittests/dbfacadeTest.py", line 89, in testFoo 1089 6 self.assertEquals(34, dtid) 1090 7 File "/usr/lib/python2.2/unittest.py", line 286, in 1091 8 failUnlessEqual 1092 9 raise self.failureException, \ 1093 10 AssertionError: 34 != 33 1094 11 1095 12 -------------------------------------------------------------- 1096 13 Ran 27 tests in 0.063s 1097 1098Say you want |:clist| write the relevant information of this message only, 1099namely: 1100 5 unittests/dbfacadeTest.py:89: AssertionError: 34 != 33 1101 1102Then the error format string could be defined as follows: > 1103 :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%m 1104 1105Note that the %C string is given before the %A here: since the expression 1106' %.%#' (which stands for the regular expression ' .*') matches every line 1107starting with a space, followed by any characters to the end of the line, 1108it also hides line 7 which would trigger a separate error message otherwise. 1109Error format strings are always parsed pattern by pattern until the first 1110match occurs. 1111 *efm-%>* 1112The %> item can be used to avoid trying patterns that appear earlier in 1113'errorformat'. This is useful for patterns that match just about anything. 1114For example, if the error looks like this: 1115 1116 Error in line 123 of foo.c: ~ 1117 unknown variable "i" ~ 1118 1119This can be found with: > 1120 :set efm=xxx,%E%>Error in line %l of %f:,%Z%m 1121Where "xxx" has a pattern that would also match the second line. 1122 1123Important: There is no memory of what part of the errorformat matched before; 1124every line in the error file gets a complete new run through the error format 1125lines. For example, if one has: > 1126 setlocal efm=aa,bb,cc,dd,ee 1127Where aa, bb, etc. are error format strings. Each line of the error file will 1128be matched to the pattern aa, then bb, then cc, etc. Just because cc matched 1129the previous error line does _not_ mean that dd will be tried first on the 1130current line, even if cc and dd are multi-line errorformat strings. 1131 1132 1133 1134Separate file name *errorformat-separate-filename* 1135 1136These prefixes are useful if the file name is given once and multiple messages 1137follow that refer to this file name. 1138 %O single-line file message: overread the matched part 1139 %P single-line file message: push file %f onto the stack 1140 %Q single-line file message: pop the last file from stack 1141 1142Example: Given a compiler that produces the following error logfile (without 1143leading line numbers): 1144 1145 1 [a1.tt] 1146 2 (1,17) error: ';' missing 1147 3 (21,2) warning: variable 'z' not defined 1148 4 (67,3) error: end of file found before string ended 1149 5 1150 6 [a2.tt] 1151 7 1152 8 [a3.tt] 1153 9 NEW compiler v1.1 1154 10 (2,2) warning: variable 'x' not defined 1155 11 (67,3) warning: 's' already defined 1156 1157This logfile lists several messages for each file enclosed in [...] which are 1158properly parsed by an error format like this: > 1159 :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-Q 1160 1161A call of |:clist| writes them accordingly with their correct filenames: 1162 1163 2 a1.tt:1 col 17 error: ';' missing 1164 3 a1.tt:21 col 2 warning: variable 'z' not defined 1165 4 a1.tt:67 col 3 error: end of file found before string ended 1166 8 a3.tt:2 col 2 warning: variable 'x' not defined 1167 9 a3.tt:67 col 3 warning: 's' already defined 1168 1169Unlike the other prefixes that all match against whole lines, %P, %Q and %O 1170can be used to match several patterns in the same line. Thus it is possible 1171to parse even nested files like in the following line: 1172 {"file1" {"file2" error1} error2 {"file3" error3 {"file4" error4 error5}}} 1173The %O then parses over strings that do not contain any push/pop file name 1174information. See |errorformat-LaTeX| for an extended example. 1175 1176 1177Ignoring and using whole messages *efm-ignore* 1178 1179The codes '+' or '-' can be combined with the uppercase codes above; in that 1180case they have to precede the letter, e.g. '%+A' or '%-G': 1181 %- do not include the matching multi-line in any output 1182 %+ include the whole matching line in the %m error string 1183 1184One prefix is only useful in combination with '+' or '-', namely %G. It parses 1185over lines containing general information like compiler version strings or 1186other headers that can be skipped. 1187 %-G ignore this message 1188 %+G general message 1189 1190 1191Pattern matching 1192 1193The scanf()-like "%*[]" notation is supported for backward-compatibility 1194with previous versions of Vim. However, it is also possible to specify 1195(nearly) any Vim supported regular expression in format strings. 1196Since meta characters of the regular expression language can be part of 1197ordinary matching strings or file names (and therefore internally have to 1198be escaped), meta symbols have to be written with leading '%': 1199 %\ The single '\' character. Note that this has to be 1200 escaped ("%\\") in ":set errorformat=" definitions. 1201 %. The single '.' character. 1202 %# The single '*'(!) character. 1203 %^ The single '^' character. Note that this is not 1204 useful, the pattern already matches start of line. 1205 %$ The single '$' character. Note that this is not 1206 useful, the pattern already matches end of line. 1207 %[ The single '[' character for a [] character range. 1208 %~ The single '~' character. 1209When using character classes in expressions (see |/\i| for an overview), 1210terms containing the "\+" quantifier can be written in the scanf() "%*" 1211notation. Example: "%\\d%\\+" ("\d\+", "any number") is equivalent to "%*\\d". 1212Important note: The \(...\) grouping of sub-matches can not be used in format 1213specifications because it is reserved for internal conversions. 1214 1215 1216Multiple entries in 'errorformat' *efm-entries* 1217 1218To be able to detect output from several compilers, several format patterns 1219may be put in 'errorformat', separated by commas (note: blanks after the comma 1220are ignored). The first pattern that has a complete match is used. If no 1221match is found, matching parts from the last one will be used, although the 1222file name is removed and the error message is set to the whole message. If 1223there is a pattern that may match output from several compilers (but not in a 1224right way), put it after one that is more restrictive. 1225 1226To include a comma in a pattern precede it with a backslash (you have to type 1227two in a ":set" command). To include a backslash itself give two backslashes 1228(you have to type four in a ":set" command). You also need to put a backslash 1229before a space for ":set". 1230 1231 1232Valid matches *quickfix-valid* 1233 1234If a line does not completely match one of the entries in 'errorformat', the 1235whole line is put in the error message and the entry is marked "not valid" 1236These lines are skipped with the ":cn" and ":cp" commands (unless there is 1237no valid line at all). You can use ":cl!" to display all the error messages. 1238 1239If the error format does not contain a file name Vim cannot switch to the 1240correct file. You will have to do this by hand. 1241 1242 1243Examples 1244 1245The format of the file from the Amiga Aztec compiler is: 1246 1247 filename>linenumber:columnnumber:errortype:errornumber:errormessage 1248 1249 filename name of the file in which the error was detected 1250 linenumber line number where the error was detected 1251 columnnumber column number where the error was detected 1252 errortype type of the error, normally a single 'E' or 'W' 1253 errornumber number of the error (for lookup in the manual) 1254 errormessage description of the error 1255 1256This can be matched with this 'errorformat' entry: 1257 %f>%l:%c:%t:%n:%m 1258 1259Some examples for C compilers that produce single-line error outputs: 1260%f:%l:\ %t%*[^0123456789]%n:\ %m for Manx/Aztec C error messages 1261 (scanf() doesn't understand [0-9]) 1262%f\ %l\ %t%*[^0-9]%n:\ %m for SAS C 1263\"%f\"\\,%*[^0-9]%l:\ %m for generic C compilers 1264%f:%l:\ %m for GCC 1265%f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f', 1266%Dgmake[%*\\d]:\ Leaving\ directory\ `%f' 1267 for GCC with gmake (concat the lines!) 1268%f(%l)\ :\ %*[^:]:\ %m old SCO C compiler (pre-OS5) 1269%f(%l)\ :\ %t%*[^0-9]%n:\ %m idem, with error type and number 1270%f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m 1271 for GCC, with some extras 1272 1273Extended examples for the handling of multi-line messages are given below, 1274see |errorformat-Jikes| and |errorformat-LaTeX|. 1275 1276Note the backslash in front of a space and double quote. It is required for 1277the :set command. There are two backslashes in front of a comma, one for the 1278:set command and one to avoid recognizing the comma as a separator of error 1279formats. 1280 1281 1282Filtering messages 1283 1284If you have a compiler that produces error messages that do not fit in the 1285format string, you could write a program that translates the error messages 1286into this format. You can use this program with the ":make" command by 1287changing the 'makeprg' option. For example: > 1288 :set mp=make\ \\\|&\ error_filter 1289The backslashes before the pipe character are required to avoid it to be 1290recognized as a command separator. The backslash before each space is 1291required for the set command. 1292 1293============================================================================= 12948. The directory stack *quickfix-directory-stack* 1295 1296Quickfix maintains a stack for saving all used directories parsed from the 1297make output. For GNU-make this is rather simple, as it always prints the 1298absolute path of all directories it enters and leaves. Regardless if this is 1299done via a 'cd' command in the makefile or with the parameter "-C dir" (change 1300to directory before reading the makefile). It may be useful to use the switch 1301"-w" to force GNU-make to print out the working directory before and after 1302processing. 1303 1304Maintaining the correct directory is more complicated if you don't use 1305GNU-make. AIX-make for example doesn't print any information about its 1306working directory. Then you need to enhance the makefile. In the makefile of 1307LessTif there is a command which echoes "Making {target} in {dir}". The 1308special problem here is that it doesn't print information on leaving the 1309directory and that it doesn't print the absolute path. 1310 1311To solve the problem with relative paths and missing "leave directory" 1312messages Vim uses following algorithm: 1313 13141) Check if the given directory is a subdirectory of the current directory. 1315 If this is true, store it as the current directory. 13162) If it is not a subdir of the current directory, try if this is a 1317 subdirectory of one of the upper directories. 13183) If the directory still isn't found, it is assumed to be a subdirectory 1319 of Vim's current directory. 1320 1321Additionally it is checked for every file, if it really exists in the 1322identified directory. If not, it is searched in all other directories of the 1323directory stack (NOT the directory subtree!). If it is still not found, it is 1324assumed that it is in Vim's current directory. 1325 1326There are limitations in this algorithm. These examples assume that make just 1327prints information about entering a directory in the form "Making all in dir". 1328 13291) Assume you have following directories and files: 1330 ./dir1 1331 ./dir1/file1.c 1332 ./file1.c 1333 1334 If make processes the directory "./dir1" before the current directory and 1335 there is an error in the file "./file1.c", you will end up with the file 1336 "./dir1/file.c" loaded by Vim. 1337 1338 This can only be solved with a "leave directory" message. 1339 13402) Assume you have following directories and files: 1341 ./dir1 1342 ./dir1/dir2 1343 ./dir2 1344 1345 You get the following: 1346 1347 Make output Directory interpreted by Vim 1348 ------------------------ ---------------------------- 1349 Making all in dir1 ./dir1 1350 Making all in dir2 ./dir1/dir2 1351 Making all in dir2 ./dir1/dir2 1352 1353 This can be solved by printing absolute directories in the "enter directory" 1354 message or by printing "leave directory" messages.. 1355 1356To avoid this problem, ensure to print absolute directory names and "leave 1357directory" messages. 1358 1359Examples for Makefiles: 1360 1361Unix: 1362 libs: 1363 for dn in $(LIBDIRS); do \ 1364 (cd $$dn; echo "Entering dir '$$(pwd)'"; make); \ 1365 echo "Leaving dir"; \ 1366 done 1367 1368Add 1369 %DEntering\ dir\ '%f',%XLeaving\ dir 1370to your 'errorformat' to handle the above output. 1371 1372Note that Vim doesn't check if the directory name in a "leave directory" 1373messages is the current directory. This is why you could just use the message 1374"Leaving dir". 1375 1376============================================================================= 13779. Specific error file formats *errorformats* 1378 1379 *errorformat-Jikes* 1380Jikes(TM), a source-to-bytecode Java compiler published by IBM Research, 1381produces simple multi-line error messages. 1382 1383An 'errorformat' string matching the produced messages is shown below. 1384The following lines can be placed in the user's |vimrc| to overwrite Vim's 1385recognized default formats, or see |:set+=| how to install this format 1386additionally to the default. > 1387 1388 :set efm=%A%f:%l:%c:%*\\d:%*\\d:, 1389 \%C%*\\s%trror:%m, 1390 \%+C%*[^:]%trror:%m, 1391 \%C%*\\s%tarning:%m, 1392 \%C%m 1393< 1394Jikes(TM) produces a single-line error message when invoked with the option 1395"+E", and can be matched with the following: > 1396 1397 :setl efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%m 1398< 1399 *errorformat-javac* 1400This 'errorformat' has been reported to work well for javac, which outputs a 1401line with "^" to indicate the column of the error: > 1402 :setl efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%# 1403or: > 1404 :setl efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%# 1405< 1406Here is an alternative from Michael F. Lamb for Unix that filters the errors 1407first: > 1408 :setl errorformat=%Z%f:%l:\ %m,%A%p^,%-G%*[^sl]%.%# 1409 :setl makeprg=javac\ %:S\ 2>&1\ \\\|\ vim-javac-filter 1410 1411You need to put the following in "vim-javac-filter" somewhere in your path 1412(e.g., in ~/bin) and make it executable: > 1413 #!/bin/sed -f 1414 /\^$/s/\t/\ /g;/:[0-9]\+:/{h;d};/^[ \t]*\^/G; 1415 1416In English, that sed script: 1417- Changes single tabs to single spaces and 1418- Moves the line with the filename, line number, error message to just after 1419 the pointer line. That way, the unused error text between doesn't break 1420 vim's notion of a "multi-line message" and also doesn't force us to include 1421 it as a "continuation of a multi-line message." 1422 1423 *errorformat-ant* 1424For ant (http://jakarta.apache.org/) the above errorformat has to be modified 1425to honour the leading [javac] in front of each javac output line: > 1426 :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%# 1427 1428The 'errorformat' can also be configured to handle ant together with either 1429javac or jikes. If you're using jikes, you should tell ant to use jikes' +E 1430command line switch which forces jikes to generate one-line error messages. 1431This is what the second line (of a build.xml file) below does: > 1432 <property name = "build.compiler" value = "jikes"/> 1433 <property name = "build.compiler.emacs" value = "true"/> 1434 1435The 'errorformat' which handles ant with both javac and jikes is: > 1436 :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m, 1437 \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%# 1438< 1439 *errorformat-jade* 1440parsing jade (see http://www.jclark.com/) errors is simple: > 1441 :set efm=jade:%f:%l:%c:%t:%m 1442< 1443 *errorformat-LaTeX* 1444The following is an example how an 'errorformat' string can be specified 1445for the (La)TeX typesetting system which displays error messages over 1446multiple lines. The output of ":clist" and ":cc" etc. commands displays 1447multi-lines in a single line, leading white space is removed. 1448It should be easy to adopt the above LaTeX errorformat to any compiler output 1449consisting of multi-line errors. 1450 1451The commands can be placed in a |vimrc| file or some other Vim script file, 1452e.g. a script containing LaTeX related stuff which is loaded only when editing 1453LaTeX sources. 1454Make sure to copy all lines of the example (in the given order), afterwards 1455remove the comment lines. For the '\' notation at the start of some lines see 1456|line-continuation|. 1457 1458 First prepare 'makeprg' such that LaTeX will report multiple 1459 errors; do not stop when the first error has occurred: > 1460 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} 1461< 1462 Start of multi-line error messages: > 1463 :set efm=%E!\ LaTeX\ %trror:\ %m, 1464 \%E!\ %m, 1465< Start of multi-line warning messages; the first two also 1466 include the line number. Meaning of some regular expressions: 1467 - "%.%#" (".*") matches a (possibly empty) string 1468 - "%*\\d" ("\d\+") matches a number > 1469 \%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#, 1470 \%+W%.%#\ at\ lines\ %l--%*\\d, 1471 \%WLaTeX\ %.%#Warning:\ %m, 1472< Possible continuations of error/warning messages; the first 1473 one also includes the line number: > 1474 \%Cl.%l\ %m, 1475 \%+C\ \ %m., 1476 \%+C%.%#-%.%#, 1477 \%+C%.%#[]%.%#, 1478 \%+C[]%.%#, 1479 \%+C%.%#%[{}\\]%.%#, 1480 \%+C<%.%#>%.%#, 1481 \%C\ \ %m, 1482< Lines that match the following patterns do not contain any 1483 important information; do not include them in messages: > 1484 \%-GSee\ the\ LaTeX%m, 1485 \%-GType\ \ H\ <return>%m, 1486 \%-G\ ...%.%#, 1487 \%-G%.%#\ (C)\ %.%#, 1488 \%-G(see\ the\ transcript%.%#), 1489< Generally exclude any empty or whitespace-only line from 1490 being displayed: > 1491 \%-G\\s%#, 1492< The LaTeX output log does not specify the names of erroneous 1493 source files per line; rather they are given globally, 1494 enclosed in parentheses. 1495 The following patterns try to match these names and store 1496 them in an internal stack. The patterns possibly scan over 1497 the same input line (one after another), the trailing "%r" 1498 conversion indicates the "rest" of the line that will be 1499 parsed in the next go until the end of line is reached. 1500 1501 Overread a file name enclosed in '('...')'; do not push it 1502 on a stack since the file apparently does not contain any 1503 error: > 1504 \%+O(%f)%r, 1505< Push a file name onto the stack. The name is given after '(': > 1506 \%+P(%f%r, 1507 \%+P\ %\\=(%f%r, 1508 \%+P%*[^()](%f%r, 1509 \%+P[%\\d%[^()]%#(%f%r, 1510< Pop the last stored file name when a ')' is scanned: > 1511 \%+Q)%r, 1512 \%+Q%*[^()])%r, 1513 \%+Q[%\\d%*[^()])%r 1514 1515Note that in some cases file names in the LaTeX output log cannot be parsed 1516properly. The parser might have been messed up by unbalanced parentheses 1517then. The above example tries to catch the most relevant cases only. 1518You can customize the given setting to suit your own purposes, for example, 1519all the annoying "Overfull ..." warnings could be excluded from being 1520recognized as an error. 1521Alternatively to filtering the LaTeX compiler output, it is also possible 1522to directly read the *.log file that is produced by the [La]TeX compiler. 1523This contains even more useful information about possible error causes. 1524However, to properly parse such a complex file, an external filter should 1525be used. See the description further above how to make such a filter known 1526by Vim. 1527 1528 *errorformat-Perl* 1529In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl 1530error messages into a format that quickfix mode will understand. See the 1531start of the file about how to use it. (This script is deprecated, see 1532|compiler-perl|.) 1533 1534 1535 1536 vim:tw=78:ts=8:ft=help:norl: 1537