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