blob: f380dc68dd595eb6ec0e2e707da14508a852bfc8 [file] [log] [blame]
Bram Moolenaar85850f32019-07-19 22:05:51 +02001*quickfix.txt* For Vim version 8.1. Last change: 2019 Jul 15
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
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
Bram Moolenaar071d4272004-06-13 20:20:40 +000019The quickfix commands are not available when the |+quickfix| feature was
20disabled at compile time.
21
22=============================================================================
231. Using QuickFix commands *quickfix* *Quickfix* *E42*
24
25Vim has a special mode to speedup the edit-compile-edit cycle. This is
26inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga.
27The idea is to save the error messages from the compiler in a file and use Vim
28to jump to the errors one by one. You can examine each problem and fix it,
29without having to remember all the error messages.
30
Bram Moolenaar05159a02005-02-26 23:04:13 +000031In Vim the quickfix commands are used more generally to find a list of
32positions in files. For example, |:vimgrep| finds pattern matches. You can
Bram Moolenaar2641f772005-03-25 21:58:17 +000033use the positions in a script with the |getqflist()| function. Thus you can
Bram Moolenaar05159a02005-02-26 23:04:13 +000034do a lot more than the edit/compile/fix cycle!
35
Bram Moolenaare18dbe82016-07-02 21:42:23 +020036If you have the error messages in a file you can start Vim with: >
37 vim -q filename
38
39From inside Vim an easy way to run a command and handle the output is with the
40|:make| command (see below).
41
42The 'errorformat' option should be set to match the error messages from your
Bram Moolenaar071d4272004-06-13 20:20:40 +000043compiler (see |errorformat| below).
44
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +020045 *quickfix-ID*
46Each quickfix list has a unique identifier called the quickfix ID and this
Bram Moolenaard473c8c2018-08-11 18:00:22 +020047number will not change within a Vim session. The |getqflist()| function can be
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +020048used to get the identifier assigned to a list. There is also a quickfix list
49number which may change whenever more than ten lists are added to a quickfix
50stack.
51
Bram Moolenaard12f5c12006-01-25 22:10:52 +000052 *location-list* *E776*
Bram Moolenaar036986f2017-03-16 17:41:02 +010053A location list is a window-local quickfix list. You get one after commands
54like `:lvimgrep`, `:lgrep`, `:lhelpgrep`, `:lmake`, etc., which create a
55location list instead of a quickfix list as the corresponding `:vimgrep`,
56`:grep`, `:helpgrep`, `:make` do.
Bram Moolenaar5b69c222019-01-11 14:50:06 +010057 *location-list-file-window*
Bram Moolenaar036986f2017-03-16 17:41:02 +010058A location list is associated with a window and each window can have a
59separate location list. A location list can be associated with only one
60window. The location list is independent of the quickfix list.
Bram Moolenaard12f5c12006-01-25 22:10:52 +000061
Bram Moolenaar280f1262006-01-30 00:14:18 +000062When a window with a location list is split, the new window gets a copy of the
Bram Moolenaare18dbe82016-07-02 21:42:23 +020063location list. When there are no longer any references to a location list,
64the location list is destroyed.
Bram Moolenaar280f1262006-01-30 00:14:18 +000065
Bram Moolenaarb254af32017-12-18 19:48:58 +010066 *quickfix-changedtick*
67Every quickfix and location list has a read-only changedtick variable that
68tracks the total number of changes made to the list. Every time the quickfix
69list is modified, this count is incremented. This can be used to perform an
Bram Moolenaard473c8c2018-08-11 18:00:22 +020070action only when the list has changed. The |getqflist()| and |getloclist()|
Bram Moolenaarb254af32017-12-18 19:48:58 +010071functions can be used to query the current value of changedtick. You cannot
72change the changedtick variable.
73
Bram Moolenaar280f1262006-01-30 00:14:18 +000074The following quickfix commands can be used. The location list commands are
75similar to the quickfix commands, replacing the 'c' prefix in the quickfix
76command with 'l'.
Bram Moolenaar071d4272004-06-13 20:20:40 +000077
Bram Moolenaare18c0b32016-03-20 21:08:34 +010078 *E924*
79If the current window was closed by an |autocommand| while processing a
80location list command, it will be aborted.
81
Bram Moolenaarffec3c52016-03-23 20:55:42 +010082 *E925* *E926*
83If the current quickfix or location list was changed by an |autocommand| while
84processing a quickfix or location list command, it will be aborted.
85
Bram Moolenaar071d4272004-06-13 20:20:40 +000086 *:cc*
87:cc[!] [nr] Display error [nr]. If [nr] is omitted, the same
Bram Moolenaar25190db2019-05-04 15:05:28 +020088:[nr]cc[!] error is displayed again. Without [!] this doesn't
Bram Moolenaar071d4272004-06-13 20:20:40 +000089 work when jumping to another buffer, the current buffer
90 has been changed, there is the only window for the
91 buffer and both 'hidden' and 'autowrite' are off.
92 When jumping to another buffer with [!] any changes to
93 the current buffer are lost, unless 'hidden' is set or
94 there is another window for this buffer.
95 The 'switchbuf' settings are respected when jumping
96 to a buffer.
Bram Moolenaar25190db2019-05-04 15:05:28 +020097 When used in the quickfix window the line number can
98 be used, including "." for the current line and "$"
99 for the last line.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000100
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000101 *:ll*
102:ll[!] [nr] Same as ":cc", except the location list for the
Bram Moolenaar25190db2019-05-04 15:05:28 +0200103:[nr]ll[!] current window is used instead of the quickfix list.
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000104
Bram Moolenaar61da1bf2019-06-06 12:14:49 +0200105 *:cn* *:cne* *:cnext* *E553*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000106:[count]cn[ext][!] Display the [count] next error in the list that
107 includes a file name. If there are no file names at
108 all, go to the [count] next error. See |:cc| for
109 [!] and 'switchbuf'.
110
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000111 *:lne* *:lnext*
112:[count]lne[xt][!] Same as ":cnext", except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000113 current window is used instead of the quickfix list.
114
Bram Moolenaard09091d2019-01-17 16:07:22 +0100115:[count]cN[ext][!] *:cp* *:cprevious* *:cprev* *:cN* *:cNext*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000116:[count]cp[revious][!] Display the [count] previous error in the list that
117 includes a file name. If there are no file names at
118 all, go to the [count] previous error. See |:cc| for
119 [!] and 'switchbuf'.
120
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000121
Bram Moolenaard09091d2019-01-17 16:07:22 +0100122:[count]lN[ext][!] *:lp* *:lprevious* *:lprev* *:lN* *:lNext*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000123:[count]lp[revious][!] Same as ":cNext" and ":cprevious", except the location
124 list for the current window is used instead of the
125 quickfix list.
126
Bram Moolenaar3ff33112019-05-03 21:56:35 +0200127 *:cabo* *:cabove*
128:[count]cabo[ve] Go to the [count] error above the current line in the
129 current buffer. If [count] is omitted, then 1 is
130 used. If there are no errors, then an error message
131 is displayed. Assumes that the entries in a quickfix
132 list are sorted by their buffer number and line
133 number. If there are multiple errors on the same line,
134 then only the first entry is used. If [count] exceeds
135 the number of entries above the current line, then the
136 first error in the file is selected.
137
138 *:lab* *:labove*
139:[count]lab[ove] Same as ":cabove", except the location list for the
140 current window is used instead of the quickfix list.
141
Bram Moolenaar8ffc7c82019-05-05 21:00:26 +0200142 *:cbel* *:cbelow*
143:[count]cbel[ow] Go to the [count] error below the current line in the
Bram Moolenaar3ff33112019-05-03 21:56:35 +0200144 current buffer. If [count] is omitted, then 1 is
145 used. If there are no errors, then an error message
146 is displayed. Assumes that the entries in a quickfix
147 list are sorted by their buffer number and line
148 number. If there are multiple errors on the same
149 line, then only the first entry is used. If [count]
150 exceeds the number of entries below the current line,
151 then the last error in the file is selected.
152
Bram Moolenaarcf6a55c2019-05-05 15:02:30 +0200153 *:lbel* *:lbelow*
154:[count]lbel[ow] Same as ":cbelow", except the location list for the
155 current window is used instead of the quickfix list.
156
157 *:cbe* *:cbefore*
158:[count]cbe[fore] Go to the [count] error before the current cursor
159 position in the current buffer. If [count] is
160 omitted, then 1 is used. If there are no errors, then
161 an error message is displayed. Assumes that the
162 entries in a quickfix list are sorted by their buffer,
163 line and column numbers. If [count] exceeds the
164 number of entries before the current position, then
165 the first error in the file is selected.
166
Bram Moolenaar8ffc7c82019-05-05 21:00:26 +0200167 *:lbe* *:lbefore*
168:[count]lbe[fore] Same as ":cbefore", except the location list for the
Bram Moolenaarcf6a55c2019-05-05 15:02:30 +0200169 current window is used instead of the quickfix list.
170
171 *:caf* *:cafter*
172:[count]caf[ter] Go to the [count] error after the current cursor
173 position in the current buffer. If [count] is
174 omitted, then 1 is used. If there are no errors, then
175 an error message is displayed. Assumes that the
176 entries in a quickfix list are sorted by their buffer,
177 line and column numbers. If [count] exceeds the
178 number of entries after the current position, then
179 the last error in the file is selected.
180
181 *:laf* *:lafter*
182:[count]laf[ter] Same as ":cafter", except the location list for the
Bram Moolenaar3ff33112019-05-03 21:56:35 +0200183 current window is used instead of the quickfix list.
184
Bram Moolenaar071d4272004-06-13 20:20:40 +0000185 *:cnf* *:cnfile*
186:[count]cnf[ile][!] Display the first error in the [count] next file in
187 the list that includes a file name. If there are no
188 file names at all or if there is no next file, go to
189 the [count] next error. See |:cc| for [!] and
190 'switchbuf'.
191
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000192 *:lnf* *:lnfile*
193:[count]lnf[ile][!] Same as ":cnfile", except the location list for the
194 current window is used instead of the quickfix list.
195
Bram Moolenaar071d4272004-06-13 20:20:40 +0000196:[count]cNf[ile][!] *:cpf* *:cpfile* *:cNf* *:cNfile*
197:[count]cpf[ile][!] Display the last error in the [count] previous file in
198 the list that includes a file name. If there are no
199 file names at all or if there is no next file, go to
200 the [count] previous error. See |:cc| for [!] and
201 'switchbuf'.
202
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000203
204:[count]lNf[ile][!] *:lpf* *:lpfile* *:lNf* *:lNfile*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000205:[count]lpf[ile][!] Same as ":cNfile" and ":cpfile", except the location
206 list for the current window is used instead of the
207 quickfix list.
208
Bram Moolenaar071d4272004-06-13 20:20:40 +0000209 *:crewind* *:cr*
210:cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST
211 error is displayed. See |:cc|.
212
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000213 *:lrewind* *:lr*
214:lr[ewind][!] [nr] Same as ":crewind", except the location list for the
215 current window is used instead of the quickfix list.
216
Bram Moolenaar071d4272004-06-13 20:20:40 +0000217 *:cfirst* *:cfir*
218:cfir[st][!] [nr] Same as ":crewind".
219
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000220 *:lfirst* *:lfir*
221:lfir[st][!] [nr] Same as ":lrewind".
222
Bram Moolenaar071d4272004-06-13 20:20:40 +0000223 *:clast* *:cla*
224:cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST
225 error is displayed. See |:cc|.
226
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000227 *:llast* *:lla*
228:lla[st][!] [nr] Same as ":clast", except the location list for the
229 current window is used instead of the quickfix list.
230
Bram Moolenaar071d4272004-06-13 20:20:40 +0000231 *:cq* *:cquit*
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000232:cq[uit][!] Quit Vim with an error code, so that the compiler
Bram Moolenaar071d4272004-06-13 20:20:40 +0000233 will not compile the same file again.
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000234 WARNING: All changes in files are lost! Also when the
235 [!] is not used. It works like ":qall!" |:qall|,
236 except that Vim returns a non-zero exit code.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000237
238 *:cf* *:cfile*
239:cf[ile][!] [errorfile] Read the error file and jump to the first error.
240 This is done automatically when Vim is started with
241 the -q option. You can use this command when you
242 keep Vim running while compiling. If you give the
243 name of the errorfile, the 'errorfile' option will
244 be set to [errorfile]. See |:cc| for [!].
Bram Moolenaar2c7292d2017-03-05 17:43:31 +0100245 If the encoding of the error file differs from the
246 'encoding' option, you can use the 'makeencoding'
247 option to specify the encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000248
Bram Moolenaar61da1bf2019-06-06 12:14:49 +0200249 *:lf* *:lfi* *:lfile*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000250:lf[ile][!] [errorfile] Same as ":cfile", except the location list for the
251 current window is used instead of the quickfix list.
252 You can not use the -q command-line option to set
253 the location list.
254
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000255
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000256:cg[etfile] [errorfile] *:cg* *:cgetfile*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000257 Read the error file. Just like ":cfile" but don't
258 jump to the first error.
Bram Moolenaar2c7292d2017-03-05 17:43:31 +0100259 If the encoding of the error file differs from the
260 'encoding' option, you can use the 'makeencoding'
261 option to specify the encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000262
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000263
Bram Moolenaar61da1bf2019-06-06 12:14:49 +0200264:lg[etfile] [errorfile] *:lg* *:lge* *:lgetfile*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000265 Same as ":cgetfile", except the location list for the
266 current window is used instead of the quickfix list.
267
Bram Moolenaar4770d092006-01-12 23:22:24 +0000268 *:caddf* *:caddfile*
269:caddf[ile] [errorfile] Read the error file and add the errors from the
Bram Moolenaar87e25fd2005-07-27 21:13:01 +0000270 errorfile to the current quickfix list. If a quickfix
271 list is not present, then a new list is created.
Bram Moolenaar2c7292d2017-03-05 17:43:31 +0100272 If the encoding of the error file differs from the
273 'encoding' option, you can use the 'makeencoding'
274 option to specify the encoding.
Bram Moolenaar87e25fd2005-07-27 21:13:01 +0000275
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000276 *:laddf* *:laddfile*
277:laddf[ile] [errorfile] Same as ":caddfile", except the location list for the
278 current window is used instead of the quickfix list.
279
Bram Moolenaar86b68352004-12-27 21:59:20 +0000280 *:cb* *:cbuffer* *E681*
Bram Moolenaar6cbce9d2007-03-08 10:01:03 +0000281:cb[uffer][!] [bufnr] Read the error list from the current buffer.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000282 When [bufnr] is given it must be the number of a
283 loaded buffer. That buffer will then be used instead
284 of the current buffer.
285 A range can be specified for the lines to be used.
286 Otherwise all lines in the buffer are used.
Bram Moolenaar6cbce9d2007-03-08 10:01:03 +0000287 See |:cc| for [!].
Bram Moolenaar86b68352004-12-27 21:59:20 +0000288
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000289 *:lb* *:lbuffer*
Bram Moolenaar6cbce9d2007-03-08 10:01:03 +0000290:lb[uffer][!] [bufnr] Same as ":cbuffer", except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000291 current window is used instead of the quickfix list.
292
Bram Moolenaardb552d602006-03-23 22:59:57 +0000293 *:cgetb* *:cgetbuffer*
294:cgetb[uffer] [bufnr] Read the error list from the current buffer. Just
295 like ":cbuffer" but don't jump to the first error.
296
297 *:lgetb* *:lgetbuffer*
298:lgetb[uffer] [bufnr] Same as ":cgetbuffer", except the location list for
299 the current window is used instead of the quickfix
300 list.
301
Bram Moolenaar61da1bf2019-06-06 12:14:49 +0200302 *:cad* *:cadd* *:caddbuffer*
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100303:cad[dbuffer] [bufnr] Read the error list from the current buffer and add
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000304 the errors to the current quickfix list. If a
305 quickfix list is not present, then a new list is
306 created. Otherwise, same as ":cbuffer".
307
308 *:laddb* *:laddbuffer*
309:laddb[uffer] [bufnr] Same as ":caddbuffer", except the location list for
310 the current window is used instead of the quickfix
311 list.
312
Bram Moolenaara40ceaf2006-01-13 22:35:40 +0000313 *:cex* *:cexpr* *E777*
Bram Moolenaar4770d092006-01-12 23:22:24 +0000314:cex[pr][!] {expr} Create a quickfix list using the result of {expr} and
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200315 jump to the first error.
316 If {expr} is a String, then each new-line terminated
Bram Moolenaard6357e82016-01-21 21:48:09 +0100317 line in the String is processed using the global value
318 of 'errorformat' and the result is added to the
319 quickfix list.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200320 If {expr} is a List, then each String item in the list
321 is processed and added to the quickfix list. Non
322 String items in the List are ignored.
323 See |:cc| for [!].
Bram Moolenaar87e25fd2005-07-27 21:13:01 +0000324 Examples: >
325 :cexpr system('grep -n xyz *')
326 :cexpr getline(1, '$')
327<
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000328 *:lex* *:lexpr*
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200329:lex[pr][!] {expr} Same as |:cexpr|, except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000330 current window is used instead of the quickfix list.
331
Bram Moolenaar76b92b22006-03-24 22:46:53 +0000332 *:cgete* *:cgetexpr*
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000333:cgete[xpr] {expr} Create a quickfix list using the result of {expr}.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200334 Just like |:cexpr|, but don't jump to the first error.
Bram Moolenaar76b92b22006-03-24 22:46:53 +0000335
336 *:lgete* *:lgetexpr*
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200337:lgete[xpr] {expr} Same as |:cgetexpr|, except the location list for the
Bram Moolenaar76b92b22006-03-24 22:46:53 +0000338 current window is used instead of the quickfix list.
339
Bram Moolenaara6878372014-03-22 21:02:50 +0100340 *:cadde* *:caddexpr*
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100341:cadde[xpr] {expr} Evaluate {expr} and add the resulting lines to the
Bram Moolenaar4770d092006-01-12 23:22:24 +0000342 current quickfix list. If a quickfix list is not
343 present, then a new list is created. The current
344 cursor position will not be changed. See |:cexpr| for
345 more information.
346 Example: >
347 :g/mypattern/caddexpr expand("%") . ":" . line(".") . ":" . getline(".")
348<
Bram Moolenaar61da1bf2019-06-06 12:14:49 +0200349 *:lad* *:addd* *:laddexpr*
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000350:lad[dexpr] {expr} Same as ":caddexpr", except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000351 current window is used instead of the quickfix list.
352
Bram Moolenaar071d4272004-06-13 20:20:40 +0000353 *:cl* *:clist*
354:cl[ist] [from] [, [to]]
355 List all errors that are valid |quickfix-valid|.
356 If numbers [from] and/or [to] are given, the respective
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000357 range of errors is listed. A negative number counts
Bram Moolenaar071d4272004-06-13 20:20:40 +0000358 from the last error backwards, -1 being the last error.
359 The 'switchbuf' settings are respected when jumping
360 to a buffer.
Bram Moolenaara9defad2018-07-08 18:20:24 +0200361 The |:filter| command can be used to display only the
362 quickfix entries matching a supplied pattern. The
363 pattern is matched against the filename, module name,
364 pattern and text of the entry.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000365
Bram Moolenaare8fea072016-07-01 14:48:27 +0200366:cl[ist] +{count} List the current and next {count} valid errors. This
367 is similar to ":clist from from+count", where "from"
368 is the current error position.
369
Bram Moolenaar071d4272004-06-13 20:20:40 +0000370:cl[ist]! [from] [, [to]]
371 List all errors.
372
Bram Moolenaare8fea072016-07-01 14:48:27 +0200373:cl[ist]! +{count} List the current and next {count} error lines. This
374 is useful to see unrecognized lines after the current
375 one. For example, if ":clist" shows:
376 8384 testje.java:252: error: cannot find symbol ~
377 Then using ":cl! +3" shows the reason:
378 8384 testje.java:252: error: cannot find symbol ~
379 8385: ZexitCode = Fmainx(); ~
380 8386: ^ ~
381 8387: symbol: method Fmainx() ~
382
383:lli[st] [from] [, [to]] *:lli* *:llist*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000384 Same as ":clist", except the location list for the
385 current window is used instead of the quickfix list.
386
387:lli[st]! [from] [, [to]]
388 List all the entries in the location list for the
389 current window.
390
Bram Moolenaar071d4272004-06-13 20:20:40 +0000391If you insert or delete lines, mostly the correct error location is still
392found because hidden marks are used. Sometimes, when the mark has been
393deleted for some reason, the message "line changed" is shown to warn you that
394the error location may not be correct. If you quit Vim and start again the
395marks are lost and the error locations may not be correct anymore.
396
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100397Two autocommands are available for running commands before and after a
398quickfix command (':make', ':grep' and so on) is executed. See
399|QuickFixCmdPre| and |QuickFixCmdPost| for details.
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000400
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000401 *QuickFixCmdPost-example*
402When 'encoding' differs from the locale, the error messages may have a
403different encoding from what Vim is using. To convert the messages you can
404use this code: >
405 function QfMakeConv()
406 let qflist = getqflist()
407 for i in qflist
408 let i.text = iconv(i.text, "cp936", "utf-8")
409 endfor
410 call setqflist(qflist)
411 endfunction
412
413 au QuickfixCmdPost make call QfMakeConv()
Bram Moolenaar2c7292d2017-03-05 17:43:31 +0100414Another option is using 'makeencoding'.
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000415
Bram Moolenaar74240d32017-12-10 15:26:15 +0100416 *quickfix-title*
417Every quickfix and location list has a title. By default the title is set to
418the command that created the list. The |getqflist()| and |getloclist()|
419functions can be used to get the title of a quickfix and a location list
420respectively. The |setqflist()| and |setloclist()| functions can be used to
421modify the title of a quickfix and location list respectively. Examples: >
422 call setqflist([], 'a', {'title' : 'Cmd output'})
423 echo getqflist({'title' : 1})
424 call setloclist(3, [], 'a', {'title' : 'Cmd output'})
425 echo getloclist(3, {'title' : 1})
426<
Bram Moolenaar5b69c222019-01-11 14:50:06 +0100427 *quickfix-index*
428When you jump to a quickfix/location list entry using any of the quickfix
Bram Moolenaard09091d2019-01-17 16:07:22 +0100429commands (e.g. |:cc|, |:cnext|, |:cprev|, etc.), that entry becomes the
430currently selected entry. The index of the currently selected entry in a
Bram Moolenaar5b69c222019-01-11 14:50:06 +0100431quickfix/location list can be obtained using the getqflist()/getloclist()
432functions. Examples: >
433 echo getqflist({'idx' : 0}).idx
434 echo getqflist({'id' : qfid, 'idx' : 0}).idx
435 echo getloclist(2, {'idx' : 0}).idx
436<
437For a new quickfix list, the first entry is selected and the index is 1. Any
438entry in any quickfix/location list can be set as the currently selected entry
439using the setqflist() function. Examples: >
440 call setqflist([], 'a', {'idx' : 12})
441 call setqflist([], 'a', {'id' : qfid, 'idx' : 7})
442 call setloclist(1, [], 'a', {'idx' : 7})
443<
Bram Moolenaar74240d32017-12-10 15:26:15 +0100444 *quickfix-size*
445You can get the number of entries (size) in a quickfix and a location list
446using the |getqflist()| and |getloclist()| functions respectively. Examples: >
447 echo getqflist({'size' : 1})
448 echo getloclist(5, {'size' : 1})
449<
450 *quickfix-context*
451Any Vim type can be associated as a context with a quickfix or location list.
452The |setqflist()| and the |setloclist()| functions can be used to associate a
453context with a quickfix and a location list respectively. The |getqflist()|
454and the |getloclist()| functions can be used to retrieve the context of a
Bram Moolenaarf0b03c42017-12-17 17:17:07 +0100455quickfix and a location list respectively. This is useful for a Vim plugin
Bram Moolenaar74240d32017-12-10 15:26:15 +0100456dealing with multiple quickfix/location lists.
457Examples: >
458
459 let somectx = {'name' : 'Vim', 'type' : 'Editor'}
460 call setqflist([], 'a', {'context' : somectx})
461 echo getqflist({'context' : 1})
462
463 let newctx = ['red', 'green', 'blue']
464 call setloclist(2, [], 'a', {'id' : qfid, 'context' : newctx})
465 echo getloclist(2, {'id' : qfid, 'context' : 1})
466<
467 *quickfix-parse*
Bram Moolenaarf0b03c42017-12-17 17:17:07 +0100468You can parse a list of lines using 'errorformat' without creating or
469modifying a quickfix list using the |getqflist()| function. Examples: >
Bram Moolenaar74240d32017-12-10 15:26:15 +0100470 echo getqflist({'lines' : ["F1:10:Line10", "F2:20:Line20"]})
471 echo getqflist({'lines' : systemlist('grep -Hn quickfix *')})
472This returns a dictionary where the 'items' key contains the list of quickfix
473entries parsed from lines. The following shows how to use a custom
Bram Moolenaarf0b03c42017-12-17 17:17:07 +0100474'errorformat' to parse the lines without modifying the 'errorformat' option: >
Bram Moolenaar74240d32017-12-10 15:26:15 +0100475 echo getqflist({'efm' : '%f#%l#%m', 'lines' : ['F1#10#Line']})
476<
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000477
Bram Moolenaar12969c02015-09-08 23:36:10 +0200478EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST:
479 *:cdo*
480:cdo[!] {cmd} Execute {cmd} in each valid entry in the quickfix list.
481 It works like doing this: >
482 :cfirst
483 :{cmd}
484 :cnext
485 :{cmd}
486 etc.
487< When the current file can't be |abandon|ed and the [!]
488 is not present, the command fails.
Bram Moolenaare8fea072016-07-01 14:48:27 +0200489 When an error is detected execution stops.
Bram Moolenaar12969c02015-09-08 23:36:10 +0200490 The last buffer (or where an error occurred) becomes
491 the current buffer.
492 {cmd} can contain '|' to concatenate several commands.
493
494 Only valid entries in the quickfix list are used.
495 A range can be used to select entries, e.g.: >
496 :10,$cdo cmd
497< To skip entries 1 to 9.
498
499 Note: While this command is executing, the Syntax
500 autocommand event is disabled by adding it to
501 'eventignore'. This considerably speeds up editing
502 each buffer.
Bram Moolenaar12969c02015-09-08 23:36:10 +0200503 Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|,
504 |:ldo|, |:cfdo| and |:lfdo|.
505
506 *:cfdo*
507:cfdo[!] {cmd} Execute {cmd} in each file in the quickfix list.
508 It works like doing this: >
509 :cfirst
510 :{cmd}
511 :cnfile
512 :{cmd}
513 etc.
514< Otherwise it works the same as `:cdo`.
Bram Moolenaar12969c02015-09-08 23:36:10 +0200515
516 *:ldo*
517:ld[o][!] {cmd} Execute {cmd} in each valid entry in the location list
518 for the current window.
519 It works like doing this: >
520 :lfirst
521 :{cmd}
522 :lnext
523 :{cmd}
524 etc.
525< Only valid entries in the location list are used.
526 Otherwise it works the same as `:cdo`.
Bram Moolenaar12969c02015-09-08 23:36:10 +0200527
528 *:lfdo*
529:lfdo[!] {cmd} Execute {cmd} in each file in the location list for
530 the current window.
531 It works like doing this: >
532 :lfirst
533 :{cmd}
534 :lnfile
535 :{cmd}
536 etc.
537< Otherwise it works the same as `:ldo`.
Bram Moolenaar12969c02015-09-08 23:36:10 +0200538
Bram Moolenaar8ffc7c82019-05-05 21:00:26 +0200539FILTERING A QUICKFIX OR LOCATION LIST:
540 *cfilter-plugin* *:Cfilter* *:Lfilter*
541If you have too many entries in a quickfix list, you can use the cfilter
542plugin to reduce the number of entries. Load the plugin with: >
543
544 packadd cfilter
545
546Then you can use the following commands to filter a quickfix/location list: >
547
548 :Cfilter[!] /{pat}/
549 :Lfilter[!] /{pat}/
550
551The |:Cfilter| command creates a new quickfix list from the entries matching
552{pat} in the current quickfix list. {pat} is a Vim |regular-expression|
553pattern. Both the file name and the text of the entries are matched against
554{pat}. If the optional ! is supplied, then the entries not matching {pat} are
555used. The pattern can be optionally enclosed using one of the following
556characters: ', ", /. If the pattern is empty, then the last used search
557pattern is used.
558
559The |:Lfilter| command does the same as |:Cfilter| but operates on the current
560location list.
561
Bram Moolenaar071d4272004-06-13 20:20:40 +0000562=============================================================================
5632. The error window *quickfix-window*
564
Bram Moolenaar7fd73202010-07-25 16:58:46 +0200565 *:cope* *:copen* *w:quickfix_title*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000566:cope[n] [height] Open a window to show the current list of errors.
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100567
Bram Moolenaar071d4272004-06-13 20:20:40 +0000568 When [height] is given, the window becomes that high
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100569 (if there is room). When [height] is omitted the
570 window is made ten lines high.
571
Bram Moolenaar071d4272004-06-13 20:20:40 +0000572 If there already is a quickfix window, it will be made
573 the current window. It is not possible to open a
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100574 second quickfix window. If [height] is given the
575 existing window will be resized to it.
576
Bram Moolenaar647e24b2019-03-17 16:39:46 +0100577 *quickfix-buffer*
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100578 The window will contain a special buffer, with
579 'buftype' equal to "quickfix". Don't change this!
580 The window will have the w:quickfix_title variable set
581 which will indicate the command that produced the
582 quickfix list. This can be used to compose a custom
583 status line if the value of 'statusline' is adjusted
Bram Moolenaara8788f42017-07-19 17:06:20 +0200584 properly. Whenever this buffer is modified by a
585 quickfix command or function, the |b:changedtick|
Bram Moolenaar647e24b2019-03-17 16:39:46 +0100586 variable is incremented. You can get the number of
587 this buffer using the getqflist() and getloclist()
588 functions by passing the 'qfbufnr' item. For a
589 location list, this buffer is wiped out when the
590 location list is removed.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000591
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000592 *:lop* *:lopen*
593:lop[en] [height] Open a window to show the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000594 current window. Works only when the location list for
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000595 the current window is present. You can have more than
596 one location window opened at a time. Otherwise, it
Bram Moolenaar280f1262006-01-30 00:14:18 +0000597 acts the same as ":copen".
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000598
Bram Moolenaar071d4272004-06-13 20:20:40 +0000599 *:ccl* *:cclose*
600:ccl[ose] Close the quickfix window.
601
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000602 *:lcl* *:lclose*
603:lcl[ose] Close the window showing the location list for the
604 current window.
605
Bram Moolenaar071d4272004-06-13 20:20:40 +0000606 *:cw* *:cwindow*
607:cw[indow] [height] Open the quickfix window when there are recognized
608 errors. If the window is already open and there are
609 no recognized errors, close the window.
610
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000611 *:lw* *:lwindow*
612:lw[indow] [height] Same as ":cwindow", except use the window showing the
613 location list for the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000614
Bram Moolenaar537ef082016-07-09 17:56:19 +0200615 *:cbo* *:cbottom*
Bram Moolenaardcb17002016-07-07 18:58:59 +0200616:cbo[ttom] Put the cursor in the last line of the quickfix window
617 and scroll to make it visible. This is useful for
618 when errors are added by an asynchronous callback.
619 Only call it once in a while if there are many
620 updates to avoid a lot of redrawing.
621
Bram Moolenaar537ef082016-07-09 17:56:19 +0200622 *:lbo* *:lbottom*
623:lbo[ttom] Same as ":cbottom", except use the window showing the
624 location list for the current window.
625
Bram Moolenaar071d4272004-06-13 20:20:40 +0000626Normally the quickfix window is at the bottom of the screen. If there are
627vertical splits, it's at the bottom of the rightmost column of windows. To
628make it always occupy the full width: >
629 :botright cwindow
630You can move the window around with |window-moving| commands.
631For example, to move it to the top: CTRL-W K
632The 'winfixheight' option will be set, which means that the window will mostly
633keep its height, ignoring 'winheight' and 'equalalways'. You can change the
634height manually (e.g., by dragging the status line above it with the mouse).
635
636In the quickfix window, each line is one error. The line number is equal to
Bram Moolenaar21020352017-06-13 17:21:04 +0200637the error number. The current entry is highlighted with the QuickFixLine
638highlighting. You can change it to your liking, e.g.: >
639 :hi QuickFixLine ctermbg=Yellow guibg=Yellow
640
641You can use ":.cc" to jump to the error under the cursor.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000642Hitting the <Enter> key or double-clicking the mouse on a line has the same
Bram Moolenaar071d4272004-06-13 20:20:40 +0000643effect. The file containing the error is opened in the window above the
644quickfix window. If there already is a window for that file, it is used
645instead. If the buffer in the used window has changed, and the error is in
646another file, jumping to the error will fail. You will first have to make
647sure the window contains a buffer which can be abandoned.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000648 *CTRL-W_<Enter>* *CTRL-W_<CR>*
649You can use CTRL-W <Enter> to open a new window and jump to the error there.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000650
651When the quickfix window has been filled, two autocommand events are
652triggered. First the 'filetype' option is set to "qf", which triggers the
Bram Moolenaar85850f32019-07-19 22:05:51 +0200653FileType event (also see |qf.vim|). Then the BufReadPost event is triggered,
654using "quickfix" for the buffer name. This can be used to perform some action
655on the listed errors. Example: >
Bram Moolenaar280f1262006-01-30 00:14:18 +0000656 au BufReadPost quickfix setlocal modifiable
657 \ | silent exe 'g/^/s//\=line(".")." "/'
658 \ | setlocal nomodifiable
Bram Moolenaar071d4272004-06-13 20:20:40 +0000659This prepends the line number to each line. Note the use of "\=" in the
660substitute string of the ":s" command, which is used to evaluate an
661expression.
Bram Moolenaar1ef15e32006-02-01 21:56:25 +0000662The BufWinEnter event is also triggered, again using "quickfix" for the buffer
663name.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000664
Bram Moolenaar82af8712016-06-04 20:20:29 +0200665Note: When adding to an existing quickfix list the autocommand are not
666triggered.
667
Bram Moolenaar071d4272004-06-13 20:20:40 +0000668Note: Making changes in the quickfix window has no effect on the list of
669errors. 'modifiable' is off to avoid making changes. If you delete or insert
670lines anyway, the relation between the text and the error number is messed up.
671If you really want to do this, you could write the contents of the quickfix
672window to a file and use ":cfile" to have it parsed and used as the new error
673list.
674
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000675 *location-list-window*
Bram Moolenaar280f1262006-01-30 00:14:18 +0000676The location list window displays the entries in a location list. When you
677open a location list window, it is created below the current window and
678displays the location list for the current window. The location list window
679is similar to the quickfix window, except that you can have more than one
Bram Moolenaar1ef15e32006-02-01 21:56:25 +0000680location list window open at a time. When you use a location list command in
681this window, the displayed location list is used.
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000682
Bram Moolenaar280f1262006-01-30 00:14:18 +0000683When you select a file from the location list window, the following steps are
684used to find a window to edit the file:
685
6861. If a window with the location list displayed in the location list window is
687 present, then the file is opened in that window.
6882. If the above step fails and if the file is already opened in another
689 window, then that window is used.
6903. If the above step fails then an existing window showing a buffer with
691 'buftype' not set is used.
6924. If the above step fails, then the file is edited in a new window.
693
694In all of the above cases, if the location list for the selected window is not
695yet set, then it is set to the location list displayed in the location list
696window.
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000697
Bram Moolenaar74240d32017-12-10 15:26:15 +0100698 *quickfix-window-ID*
699You can use the |getqflist()| and |getloclist()| functions to obtain the
700window ID of the quickfix window and location list window respectively (if
701present). Examples: >
702 echo getqflist({'winid' : 1}).winid
703 echo getloclist(2, {'winid' : 1}).winid
704<
Bram Moolenaar15142e22018-04-30 22:19:58 +0200705 *getqflist-examples*
Bram Moolenaard473c8c2018-08-11 18:00:22 +0200706The |getqflist()| and |getloclist()| functions can be used to get the various
Bram Moolenaar15142e22018-04-30 22:19:58 +0200707attributes of a quickfix and location list respectively. Some examples for
708using these functions are below:
709>
710 " get the title of the current quickfix list
711 :echo getqflist({'title' : 0}).title
712
713 " get the identifier of the current quickfix list
714 :let qfid = getqflist({'id' : 0}).id
715
Bram Moolenaar78ddc062018-05-15 21:56:34 +0200716 " get the identifier of the fourth quickfix list in the stack
717 :let qfid = getqflist({'nr' : 4, 'id' : 0}).id
718
719 " check whether a quickfix list with a specific identifier exists
720 :if getqflist({'id' : qfid}).id == qfid
721
Bram Moolenaar15142e22018-04-30 22:19:58 +0200722 " get the index of the current quickfix list in the stack
723 :let qfnum = getqflist({'nr' : 0}).nr
724
725 " get the items of a quickfix list specified by an identifier
726 :echo getqflist({'id' : qfid, 'items' : 0}).items
727
728 " get the number of entries in a quickfix list specified by an id
729 :echo getqflist({'id' : qfid, 'size' : 0}).size
730
731 " get the context of the third quickfix list in the stack
732 :echo getqflist({'nr' : 3, 'context' : 0}).context
733
734 " get the number of quickfix lists in the stack
735 :echo getqflist({'nr' : '$'}).nr
736
737 " get the number of times the current quickfix list is changed
738 :echo getqflist({'changedtick' : 0}).changedtick
739
740 " get the current entry in a quickfix list specified by an identifier
741 :echo getqflist({'id' : qfid, 'idx' : 0}).idx
742
743 " get all the quickfix list attributes using an identifier
744 :echo getqflist({'id' : qfid, 'all' : 0})
745
746 " parse text from a List of lines and return a quickfix list
747 :let myList = ["a.java:10:L10", "b.java:20:L20"]
748 :echo getqflist({'lines' : myList}).items
749
750 " parse text using a custom 'efm' and return a quickfix list
751 :echo getqflist({'lines' : ['a.c#10#Line 10'], 'efm':'%f#%l#%m'}).items
752
753 " get the quickfix list window id
754 :echo getqflist({'winid' : 0}).winid
755
Bram Moolenaar647e24b2019-03-17 16:39:46 +0100756 " get the quickfix list window buffer number
757 :echo getqflist({'qfbufnr' : 0}).qfbufnr
758
Bram Moolenaar15142e22018-04-30 22:19:58 +0200759 " get the context of the current location list
760 :echo getloclist(0, {'context' : 0}).context
761
762 " get the location list window id of the third window
763 :echo getloclist(3, {'winid' : 0}).winid
Bram Moolenaar5b69c222019-01-11 14:50:06 +0100764
Bram Moolenaar647e24b2019-03-17 16:39:46 +0100765 " get the location list window buffer number of the third window
766 :echo getloclist(3, {'qfbufnr' : 0}).qfbufnr
767
Bram Moolenaar5b69c222019-01-11 14:50:06 +0100768 " get the file window id of a location list window (winnr: 4)
769 :echo getloclist(4, {'filewinid' : 0}).filewinid
Bram Moolenaar15142e22018-04-30 22:19:58 +0200770<
771 *setqflist-examples*
Bram Moolenaard473c8c2018-08-11 18:00:22 +0200772The |setqflist()| and |setloclist()| functions can be used to set the various
Bram Moolenaar15142e22018-04-30 22:19:58 +0200773attributes of a quickfix and location list respectively. Some examples for
774using these functions are below:
775>
Bram Moolenaar78ddc062018-05-15 21:56:34 +0200776 " create an empty quickfix list with a title and a context
777 :let t = 'Search results'
778 :let c = {'cmd' : 'grep'}
779 :call setqflist([], ' ', {'title' : t, 'context' : c})
780
Bram Moolenaar15142e22018-04-30 22:19:58 +0200781 " set the title of the current quickfix list
782 :call setqflist([], 'a', {'title' : 'Mytitle'})
783
Bram Moolenaar5b69c222019-01-11 14:50:06 +0100784 " change the current entry in the list specified by an identifier
785 :call setqflist([], 'a', {'id' : qfid, 'idx' : 10})
786
Bram Moolenaar15142e22018-04-30 22:19:58 +0200787 " set the context of a quickfix list specified by an identifier
788 :call setqflist([], 'a', {'id' : qfid, 'context' : {'val' : 100}})
789
790 " create a new quickfix list from a command output
791 :call setqflist([], ' ', {'lines' : systemlist('grep -Hn main *.c')})
792
793 " parse text using a custom efm and add to a particular quickfix list
794 :call setqflist([], 'a', {'id' : qfid,
795 \ 'lines' : ["a.c#10#L10", "b.c#20#L20"], 'efm':'%f#%l#%m'})
796
797 " add items to the quickfix list specified by an identifier
798 :let newItems = [{'filename' : 'a.txt', 'lnum' : 10, 'text' : "Apple"},
799 \ {'filename' : 'b.txt', 'lnum' : 20, 'text' : "Orange"}]
800 :call setqflist([], 'a', {'id' : qfid, 'items' : newItems})
801
Bram Moolenaar78ddc062018-05-15 21:56:34 +0200802 " empty a quickfix list specified by an identifier
803 :call setqflist([], 'r', {'id' : qfid, 'items' : []})
804
Bram Moolenaar15142e22018-04-30 22:19:58 +0200805 " free all the quickfix lists in the stack
806 :call setqflist([], 'f')
807
808 " set the title of the fourth quickfix list
809 :call setqflist([], 'a', {'nr' : 4, 'title' : 'SomeTitle'})
810
811 " create a new quickfix list at the end of the stack
812 :call setqflist([], ' ', {'nr' : '$',
813 \ 'lines' : systemlist('grep -Hn class *.java')})
814
815 " create a new location list from a command output
816 :call setloclist(0, [], ' ', {'lines' : systemlist('grep -Hn main *.c')})
817
818 " replace the location list entries for the third window
819 :call setloclist(3, [], 'r', {'items' : newItems})
820<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000821=============================================================================
8223. Using more than one list of errors *quickfix-error-lists*
823
824So far has been assumed that there is only one list of errors. Actually the
825ten last used lists are remembered. When starting a new list, the previous
826ones are automatically kept. Two commands can be used to access older error
827lists. They set one of the existing error lists as the current one.
828
829 *:colder* *:col* *E380*
830:col[der] [count] Go to older error list. When [count] is given, do
831 this [count] times. When already at the oldest error
832 list, an error message is given.
833
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000834 *:lolder* *:lol*
Bram Moolenaar42ebd062016-07-17 13:35:14 +0200835:lol[der] [count] Same as `:colder`, except use the location list for
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000836 the current window instead of the quickfix list.
837
Bram Moolenaar071d4272004-06-13 20:20:40 +0000838 *:cnewer* *:cnew* *E381*
839:cnew[er] [count] Go to newer error list. When [count] is given, do
840 this [count] times. When already at the newest error
841 list, an error message is given.
842
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000843 *:lnewer* *:lnew*
Bram Moolenaar42ebd062016-07-17 13:35:14 +0200844:lnew[er] [count] Same as `:cnewer`, except use the location list for
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000845 the current window instead of the quickfix list.
846
Bram Moolenaar42ebd062016-07-17 13:35:14 +0200847 *:chistory* *:chi*
Bram Moolenaar8ffc7c82019-05-05 21:00:26 +0200848:[count]chi[story] Show the list of error lists. The current list is
Bram Moolenaar42ebd062016-07-17 13:35:14 +0200849 marked with ">". The output looks like:
850 error list 1 of 3; 43 errors ~
851 > error list 2 of 3; 0 errors ~
852 error list 3 of 3; 15 errors ~
853
Bram Moolenaar8ffc7c82019-05-05 21:00:26 +0200854 When [count] is given, then the count'th quickfix
855 list is made the current list. Example: >
856 " Make the 4th quickfix list current
857 :4chistory
858<
Bram Moolenaar42ebd062016-07-17 13:35:14 +0200859 *:lhistory* *:lhi*
Bram Moolenaar8ffc7c82019-05-05 21:00:26 +0200860:[count]lhi[story] Show the list of location lists, otherwise like
Bram Moolenaar42ebd062016-07-17 13:35:14 +0200861 `:chistory`.
862
Bram Moolenaar071d4272004-06-13 20:20:40 +0000863When adding a new error list, it becomes the current list.
864
865When ":colder" has been used and ":make" or ":grep" is used to add a new error
866list, one newer list is overwritten. This is especially useful if you are
867browsing with ":grep" |grep|. If you want to keep the more recent error
868lists, use ":cnewer 99" first.
869
Bram Moolenaar74240d32017-12-10 15:26:15 +0100870To get the number of lists in the quickfix and location list stack, you can
871use the |getqflist()| and |getloclist()| functions respectively with the list
872number set to the special value '$'. Examples: >
873 echo getqflist({'nr' : '$'}).nr
874 echo getloclist(3, {'nr' : '$'}).nr
875To get the number of the current list in the stack: >
876 echo getqflist({'nr' : 0}).nr
877<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000878=============================================================================
8794. Using :make *:make_makeprg*
880
881 *:mak* *:make*
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100882:mak[e][!] [arguments] 1. All relevant |QuickFixCmdPre| autocommands are
883 executed.
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000884 2. If the 'autowrite' option is on, write any changed
Bram Moolenaar071d4272004-06-13 20:20:40 +0000885 buffers
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000886 3. An errorfile name is made from 'makeef'. If
Bram Moolenaar071d4272004-06-13 20:20:40 +0000887 'makeef' doesn't contain "##", and a file with this
888 name already exists, it is deleted.
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000889 4. The program given with the 'makeprg' option is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000890 started (default "make") with the optional
891 [arguments] and the output is saved in the
892 errorfile (for Unix it is also echoed on the
893 screen).
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000894 5. The errorfile is read using 'errorformat'.
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100895 6. All relevant |QuickFixCmdPost| autocommands are
896 executed. See example below.
Bram Moolenaar6b803a72007-05-06 14:25:46 +0000897 7. If [!] is not given the first error is jumped to.
898 8. The errorfile is deleted.
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000899 9. You can now move through the errors with commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000900 like |:cnext| and |:cprevious|, see above.
901 This command does not accept a comment, any "
902 characters are considered part of the arguments.
Bram Moolenaar2c7292d2017-03-05 17:43:31 +0100903 If the encoding of the program output differs from the
904 'encoding' option, you can use the 'makeencoding'
905 option to specify the encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000906
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000907 *:lmak* *:lmake*
908:lmak[e][!] [arguments]
909 Same as ":make", except the location list for the
910 current window is used instead of the quickfix list.
911
Bram Moolenaar071d4272004-06-13 20:20:40 +0000912The ":make" command executes the command given with the 'makeprg' option.
913This is done by passing the command to the shell given with the 'shell'
914option. This works almost like typing
915
916 ":!{makeprg} [arguments] {shellpipe} {errorfile}".
917
918{makeprg} is the string given with the 'makeprg' option. Any command can be
919used, not just "make". Characters '%' and '#' are expanded as usual on a
920command-line. You can use "%<" to insert the current file name without
921extension, or "#<" to insert the alternate file name without extension, for
922example: >
923 :set makeprg=make\ #<.o
924
925[arguments] is anything that is typed after ":make".
926{shellpipe} is the 'shellpipe' option.
927{errorfile} is the 'makeef' option, with ## replaced to make it unique.
928
Bram Moolenaar6dfc28b2010-02-11 14:19:15 +0100929The placeholder "$*" can be used for the argument list in {makeprg} if the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000930command needs some additional characters after its arguments. The $* is
931replaced then by all arguments. Example: >
932 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
933or simpler >
934 :let &mp = 'latex \\nonstopmode \\input\{$*}'
935"$*" can be given multiple times, for example: >
936 :set makeprg=gcc\ -o\ $*\ $*
937
938The 'shellpipe' option defaults to ">" for the Amiga, MS-DOS and Win32. This
939means that the output of the compiler is saved in a file and not shown on the
940screen directly. For Unix "| tee" is used. The compiler output is shown on
941the screen and saved in a file the same time. Depending on the shell used
942"|& tee" or "2>&1| tee" is the default, so stderr output will be included.
943
944If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful
945for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).
946
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000947
948Using QuickFixCmdPost to fix the encoding ~
949
950It may be that 'encoding' is set to an encoding that differs from the messages
951your build program produces. This example shows how to fix this after Vim has
952read the error messages: >
953
954 function QfMakeConv()
955 let qflist = getqflist()
956 for i in qflist
957 let i.text = iconv(i.text, "cp936", "utf-8")
958 endfor
959 call setqflist(qflist)
960 endfunction
961
962 au QuickfixCmdPost make call QfMakeConv()
963
964(Example by Faque Cheng)
Bram Moolenaar2c7292d2017-03-05 17:43:31 +0100965Another option is using 'makeencoding'.
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000966
Bram Moolenaar071d4272004-06-13 20:20:40 +0000967==============================================================================
Bram Moolenaar86b68352004-12-27 21:59:20 +00009685. Using :vimgrep and :grep *grep* *lid*
969
970Vim has two ways to find matches for a pattern: Internal and external. The
971advantage of the internal grep is that it works on all systems and uses the
972powerful Vim search patterns. An external grep program can be used when the
973Vim grep does not do what you want.
974
Bram Moolenaar8fc061c2004-12-29 21:03:02 +0000975The internal method will be slower, because files are read into memory. The
976advantages are:
977- Line separators and encoding are automatically recognized, as if a file is
978 being edited.
979- Uses Vim search patterns. Multi-line patterns can be used.
980- When plugins are enabled: compressed and remote files can be searched.
981 |gzip| |netrw|
Bram Moolenaara3227e22006-03-08 21:32:40 +0000982
983To be able to do this Vim loads each file as if it is being edited. When
Bram Moolenaar1056d982006-03-09 22:37:52 +0000984there is no match in the file the associated buffer is wiped out again. The
Bram Moolenaara3227e22006-03-08 21:32:40 +0000985'hidden' option is ignored here to avoid running out of memory or file
986descriptors when searching many files. However, when the |:hide| command
987modifier is used the buffers are kept loaded. This makes following searches
988in the same files a lot faster.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000989
Bram Moolenaar483c5d82010-10-20 18:45:33 +0200990Note that |:copen| (or |:lopen| for |:lgrep|) may be used to open a buffer
991containing the search results in linked form. The |:silent| command may be
Bram Moolenaard58e9292011-02-09 17:07:58 +0100992used to suppress the default full screen grep output. The ":grep!" form of
Bram Moolenaar483c5d82010-10-20 18:45:33 +0200993the |:grep| command doesn't jump to the first match automatically. These
994commands can be combined to create a NewGrep command: >
995
996 command! -nargs=+ NewGrep execute 'silent grep! <args>' | copen 42
997
Bram Moolenaar86b68352004-12-27 21:59:20 +0000998
9995.1 using Vim's internal grep
1000
Bram Moolenaare49b69a2005-01-08 16:11:57 +00001001 *:vim* *:vimgrep* *E682* *E683*
Bram Moolenaar05159a02005-02-26 23:04:13 +00001002:vim[grep][!] /{pattern}/[g][j] {file} ...
Bram Moolenaar86b68352004-12-27 21:59:20 +00001003 Search for {pattern} in the files {file} ... and set
Bram Moolenaar30b65812012-07-12 22:01:11 +02001004 the error list to the matches. Files matching
1005 'wildignore' are ignored; files in 'suffixes' are
1006 searched last.
Bram Moolenaar05159a02005-02-26 23:04:13 +00001007 Without the 'g' flag each line is added only once.
1008 With 'g' every match is added.
1009
1010 {pattern} is a Vim search pattern. Instead of
1011 enclosing it in / any non-ID character (see
1012 |'isident'|) can be used, so long as it does not
1013 appear in {pattern}.
1014 'ignorecase' applies. To overrule it put |/\c| in the
1015 pattern to ignore case or |/\C| to match case.
1016 'smartcase' is not used.
Bram Moolenaar60abe752013-03-07 16:32:54 +01001017 If {pattern} is empty (e.g. // is specified), the last
1018 used search pattern is used. |last-pattern|
Bram Moolenaarba3ff532018-11-04 14:45:49 +01001019:{count}vim[grep] ...
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001020 When a number is put before the command this is used
1021 as the maximum number of matches to find. Use
1022 ":1vimgrep pattern file" to find only the first.
1023 Useful if you only want to check if there is a match
1024 and quit quickly when it's found.
1025
Bram Moolenaar05159a02005-02-26 23:04:13 +00001026 Without the 'j' flag Vim jumps to the first match.
1027 With 'j' only the quickfix list is updated.
1028 With the [!] any changes in the current buffer are
1029 abandoned.
1030
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00001031 Every second or so the searched file name is displayed
1032 to give you an idea of the progress made.
Bram Moolenaar8fc061c2004-12-29 21:03:02 +00001033 Examples: >
1034 :vimgrep /an error/ *.c
1035 :vimgrep /\<FileName\>/ *.h include/*
Bram Moolenaar231334e2005-07-25 20:46:57 +00001036 :vimgrep /myfunc/ **/*.c
1037< For the use of "**" see |starstar-wildcard|.
Bram Moolenaar86b68352004-12-27 21:59:20 +00001038
Bram Moolenaar8fc061c2004-12-29 21:03:02 +00001039:vim[grep][!] {pattern} {file} ...
1040 Like above, but instead of enclosing the pattern in a
1041 non-ID character use a white-separated pattern. The
1042 pattern must start with an ID character.
1043 Example: >
1044 :vimgrep Error *.c
1045<
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +00001046 *:lv* *:lvimgrep*
1047:lv[imgrep][!] /{pattern}/[g][j] {file} ...
1048:lv[imgrep][!] {pattern} {file} ...
1049 Same as ":vimgrep", except the location list for the
1050 current window is used instead of the quickfix list.
1051
Bram Moolenaar86b68352004-12-27 21:59:20 +00001052 *:vimgrepa* *:vimgrepadd*
Bram Moolenaar05159a02005-02-26 23:04:13 +00001053:vimgrepa[dd][!] /{pattern}/[g][j] {file} ...
1054:vimgrepa[dd][!] {pattern} {file} ...
Bram Moolenaar86b68352004-12-27 21:59:20 +00001055 Just like ":vimgrep", but instead of making a new list
1056 of errors the matches are appended to the current
1057 list.
1058
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +00001059 *:lvimgrepa* *:lvimgrepadd*
1060:lvimgrepa[dd][!] /{pattern}/[g][j] {file} ...
1061:lvimgrepa[dd][!] {pattern} {file} ...
1062 Same as ":vimgrepadd", except the location list for
1063 the current window is used instead of the quickfix
1064 list.
Bram Moolenaar86b68352004-12-27 21:59:20 +00001065
10665.2 External grep
Bram Moolenaar071d4272004-06-13 20:20:40 +00001067
1068Vim can interface with "grep" and grep-like programs (such as the GNU
1069id-utils) in a similar way to its compiler integration (see |:make| above).
1070
1071[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where
1072"re" stands for Regular Expression.]
1073
1074 *:gr* *:grep*
1075:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of
1076 'makeprg' and 'grepformat' instead of 'errorformat'.
Bram Moolenaar86b68352004-12-27 21:59:20 +00001077 When 'grepprg' is "internal" this works like
1078 |:vimgrep|. Note that the pattern needs to be
1079 enclosed in separator characters then.
Bram Moolenaar2c7292d2017-03-05 17:43:31 +01001080 If the encoding of the program output differs from the
1081 'encoding' option, you can use the 'makeencoding'
1082 option to specify the encoding.
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +00001083
1084 *:lgr* *:lgrep*
1085:lgr[ep][!] [arguments] Same as ":grep", except the location list for the
1086 current window is used instead of the quickfix list.
1087
Bram Moolenaar071d4272004-06-13 20:20:40 +00001088 *:grepa* *:grepadd*
1089:grepa[dd][!] [arguments]
1090 Just like ":grep", but instead of making a new list of
1091 errors the matches are appended to the current list.
1092 Example: >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001093 :call setqflist([])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001094 :bufdo grepadd! something %
1095< The first command makes a new error list which is
1096 empty. The second command executes "grepadd" for each
1097 listed buffer. Note the use of ! to avoid that
1098 ":grepadd" jumps to the first error, which is not
1099 allowed with |:bufdo|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001100 An example that uses the argument list and avoids
1101 errors for files without matches: >
1102 :silent argdo try
1103 \ | grepadd! something %
1104 \ | catch /E480:/
1105 \ | endtry"
1106<
Bram Moolenaar2c7292d2017-03-05 17:43:31 +01001107 If the encoding of the program output differs from the
1108 'encoding' option, you can use the 'makeencoding'
1109 option to specify the encoding.
1110
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +00001111 *:lgrepa* *:lgrepadd*
1112:lgrepa[dd][!] [arguments]
1113 Same as ":grepadd", except the location list for the
1114 current window is used instead of the quickfix list.
1115
Bram Moolenaar86b68352004-12-27 21:59:20 +000011165.3 Setting up external grep
Bram Moolenaar071d4272004-06-13 20:20:40 +00001117
1118If you have a standard "grep" program installed, the :grep command may work
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001119well with the defaults. The syntax is very similar to the standard command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001120
1121 :grep foo *.c
1122
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001123Will search all files with the .c extension for the substring "foo". The
Bram Moolenaar071d4272004-06-13 20:20:40 +00001124arguments to :grep are passed straight to the "grep" program, so you can use
1125whatever options your "grep" supports.
1126
1127By default, :grep invokes grep with the -n option (show file and line
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001128numbers). You can change this with the 'grepprg' option. You will need to set
Bram Moolenaar071d4272004-06-13 20:20:40 +00001129'grepprg' if:
1130
1131a) You are using a program that isn't called "grep"
1132b) You have to call grep with a full path
1133c) You want to pass other options automatically (e.g. case insensitive
1134 search.)
1135
1136Once "grep" has executed, Vim parses the results using the 'grepformat'
1137option. This option works in the same way as the 'errorformat' option - see
1138that for details. You may need to change 'grepformat' from the default if
1139your grep outputs in a non-standard format, or you are using some other
1140program with a special format.
1141
1142Once the results are parsed, Vim loads the first file containing a match and
1143jumps to the appropriate line, in the same way that it jumps to a compiler
1144error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc.
1145commands to see the other matches.
1146
1147
Bram Moolenaar86b68352004-12-27 21:59:20 +000011485.4 Using :grep with id-utils
Bram Moolenaar071d4272004-06-13 20:20:40 +00001149
1150You can set up :grep to work with the GNU id-utils like this: >
1151
1152 :set grepprg=lid\ -Rgrep\ -s
1153 :set grepformat=%f:%l:%m
1154
1155then >
1156 :grep (regexp)
1157
1158works just as you'd expect.
1159(provided you remembered to mkid first :)
1160
1161
Bram Moolenaar86b68352004-12-27 21:59:20 +000011625.5 Browsing source code with :vimgrep or :grep
Bram Moolenaar071d4272004-06-13 20:20:40 +00001163
1164Using the stack of error lists that Vim keeps, you can browse your files to
1165look for functions and the functions they call. For example, suppose that you
1166have to add an argument to the read_file() function. You enter this command: >
1167
Bram Moolenaar86b68352004-12-27 21:59:20 +00001168 :vimgrep /\<read_file\>/ *.c
Bram Moolenaar071d4272004-06-13 20:20:40 +00001169
1170You use ":cn" to go along the list of matches and add the argument. At one
1171place you have to get the new argument from a higher level function msg(), and
1172need to change that one too. Thus you use: >
1173
Bram Moolenaar86b68352004-12-27 21:59:20 +00001174 :vimgrep /\<msg\>/ *.c
Bram Moolenaar071d4272004-06-13 20:20:40 +00001175
1176While changing the msg() functions, you find another function that needs to
Bram Moolenaar86b68352004-12-27 21:59:20 +00001177get the argument from a higher level. You can again use ":vimgrep" to find
1178these functions. Once you are finished with one function, you can use >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001179
1180 :colder
1181
1182to go back to the previous one.
1183
Bram Moolenaar86b68352004-12-27 21:59:20 +00001184This works like browsing a tree: ":vimgrep" goes one level deeper, creating a
Bram Moolenaar071d4272004-06-13 20:20:40 +00001185list of branches. ":colder" goes back to the previous level. You can mix
Bram Moolenaar86b68352004-12-27 21:59:20 +00001186this use of ":vimgrep" and "colder" to browse all the locations in a tree-like
Bram Moolenaar071d4272004-06-13 20:20:40 +00001187way. If you do this consistently, you will find all locations without the
1188need to write down a "todo" list.
1189
1190=============================================================================
11916. Selecting a compiler *compiler-select*
1192
1193 *:comp* *:compiler* *E666*
1194:comp[iler][!] {name} Set options to work with compiler {name}.
1195 Without the "!" options are set for the
1196 current buffer. With "!" global options are
1197 set.
1198 If you use ":compiler foo" in "file.foo" and
1199 then ":compiler! bar" in another buffer, Vim
1200 will keep on using "foo" in "file.foo".
1201 {not available when compiled without the
1202 |+eval| feature}
1203
1204
1205The Vim plugins in the "compiler" directory will set options to use the
Bram Moolenaar25de4c22016-11-06 14:48:06 +01001206selected compiler. For `:compiler` local options are set, for `:compiler!`
Bram Moolenaar071d4272004-06-13 20:20:40 +00001207global options.
1208 *current_compiler*
1209To support older Vim versions, the plugins always use "current_compiler" and
1210not "b:current_compiler". What the command actually does is the following:
1211
1212- Delete the "current_compiler" and "b:current_compiler" variables.
1213- Define the "CompilerSet" user command. With "!" it does ":set", without "!"
1214 it does ":setlocal".
1215- Execute ":runtime! compiler/{name}.vim". The plugins are expected to set
1216 options with "CompilerSet" and set the "current_compiler" variable to the
1217 name of the compiler.
Bram Moolenaar05159a02005-02-26 23:04:13 +00001218- Delete the "CompilerSet" user command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001219- Set "b:current_compiler" to the value of "current_compiler".
1220- Without "!" the old value of "current_compiler" is restored.
1221
1222
1223For writing a compiler plugin, see |write-compiler-plugin|.
1224
1225
Bram Moolenaarbae0c162007-05-10 19:30:25 +00001226GCC *quickfix-gcc* *compiler-gcc*
1227
1228There's one variable you can set for the GCC compiler:
1229
1230g:compiler_gcc_ignore_unmatched_lines
1231 Ignore lines that don't match any patterns
1232 defined for GCC. Useful if output from
1233 commands run from make are generating false
1234 positives.
1235
1236
Bram Moolenaar071d4272004-06-13 20:20:40 +00001237MANX AZTEC C *quickfix-manx* *compiler-manx*
1238
1239To use Vim with Manx's Aztec C compiler on the Amiga you should do the
1240following:
1241- Set the CCEDIT environment variable with the command: >
1242 mset "CCEDIT=vim -q"
1243- Compile with the -qf option. If the compiler finds any errors, Vim is
1244 started and the cursor is positioned on the first error. The error message
1245 will be displayed on the last line. You can go to other errors with the
1246 commands mentioned above. You can fix the errors and write the file(s).
1247- If you exit Vim normally the compiler will re-compile the same file. If you
1248 exit with the :cq command, the compiler will terminate. Do this if you
1249 cannot fix the error, or if another file needs to be compiled first.
1250
1251There are some restrictions to the Quickfix mode on the Amiga. The
1252compiler only writes the first 25 errors to the errorfile (Manx's
1253documentation does not say how to get more). If you want to find the others,
1254you will have to fix a few errors and exit the editor. After recompiling,
1255up to 25 remaining errors will be found.
1256
1257If Vim was started from the compiler, the :sh and some :! commands will not
1258work, because Vim is then running in the same process as the compiler and
1259stdin (standard input) will not be interactive.
1260
1261
Bram Moolenaar8c8de832008-06-24 22:58:06 +00001262PERL *quickfix-perl* *compiler-perl*
1263
1264The Perl compiler plugin doesn't actually compile, but invokes Perl's internal
1265syntax checking feature and parses the output for possible errors so you can
1266correct them in quick-fix mode.
1267
1268Warnings are forced regardless of "no warnings" or "$^W = 0" within the file
1269being checked. To disable this set g:perl_compiler_force_warnings to a zero
1270value. For example: >
1271 let g:perl_compiler_force_warnings = 0
1272
1273
Bram Moolenaar071d4272004-06-13 20:20:40 +00001274PYUNIT COMPILER *compiler-pyunit*
1275
1276This is not actually a compiler, but a unit testing framework for the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001277Python language. It is included into standard Python distribution
1278starting from version 2.0. For older versions, you can get it from
Bram Moolenaar071d4272004-06-13 20:20:40 +00001279http://pyunit.sourceforge.net.
1280
1281When you run your tests with the help of the framework, possible errors
1282are parsed by Vim and presented for you in quick-fix mode.
1283
1284Unfortunately, there is no standard way to run the tests.
1285The alltests.py script seems to be used quite often, that's all.
1286Useful values for the 'makeprg' options therefore are:
1287 setlocal makeprg=./alltests.py " Run a testsuite
Bram Moolenaar26df0922014-02-23 23:39:13 +01001288 setlocal makeprg=python\ %:S " Run a single testcase
Bram Moolenaar071d4272004-06-13 20:20:40 +00001289
1290Also see http://vim.sourceforge.net/tip_view.php?tip_id=280.
1291
1292
1293TEX COMPILER *compiler-tex*
1294
1295Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim)
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001296uses make command if possible. If the compiler finds a file named "Makefile"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001297or "makefile" in the current directory, it supposes that you want to process
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001298your *TeX files with make, and the makefile does the right work. In this case
1299compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched. If
Bram Moolenaar071d4272004-06-13 20:20:40 +00001300neither "Makefile" nor "makefile" is found, the compiler will not use make.
1301You can force the compiler to ignore makefiles by defining
1302b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for
1303existence only).
1304
1305If the compiler chose not to use make, it need to choose a right program for
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001306processing your input. If b:tex_flavor or g:tex_flavor (in this precedence)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001307variable exists, it defines TeX flavor for :make (actually, this is the name
1308of executed command), and if both variables do not exist, it defaults to
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001309"latex". For example, while editing chapter2.tex \input-ed from mypaper.tex
Bram Moolenaar071d4272004-06-13 20:20:40 +00001310written in AMS-TeX: >
1311
1312 :let b:tex_flavor = 'amstex'
1313 :compiler tex
1314< [editing...] >
1315 :make mypaper
1316
1317Note that you must specify a name of the file to process as an argument (to
1318process the right file when editing \input-ed or \include-ed file; portable
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001319solution for substituting % for no arguments is welcome). This is not in the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001320semantics of make, where you specify a target, not source, but you may specify
1321filename without extension ".tex" and mean this as "make filename.dvi or
1322filename.pdf or filename.some_result_extension according to compiler".
1323
1324Note: tex command line syntax is set to usable both for MikTeX (suggestion
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001325by Srinath Avadhanula) and teTeX (checked by Artem Chuprina). Suggestion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001326from |errorformat-LaTeX| is too complex to keep it working for different
1327shells and OSes and also does not allow to use other available TeX options,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001328if any. If your TeX doesn't support "-interaction=nonstopmode", please
Bram Moolenaar071d4272004-06-13 20:20:40 +00001329report it with different means to express \nonstopmode from the command line.
1330
1331=============================================================================
13327. The error format *error-file-format*
1333
1334 *errorformat* *E372* *E373* *E374*
1335 *E375* *E376* *E377* *E378*
1336The 'errorformat' option specifies a list of formats that are recognized. The
1337first format that matches with an error message is used. You can add several
1338formats for different messages your compiler produces, or even entries for
1339multiple compilers. See |efm-entries|.
1340
1341Each entry in 'errorformat' is a scanf-like string that describes the format.
1342First, you need to know how scanf works. Look in the documentation of your
1343C compiler. Below you find the % items that Vim understands. Others are
1344invalid.
1345
1346Special characters in 'errorformat' are comma and backslash. See
1347|efm-entries| for how to deal with them. Note that a literal "%" is matched
1348by "%%", thus it is not escaped with a backslash.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02001349Keep in mind that in the `:make` and `:grep` output all NUL characters are
1350replaced with SOH (0x01).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001351
1352Note: By default the difference between upper and lowercase is ignored. If
1353you want to match case, add "\C" to the pattern |/\C|.
1354
1355
1356Basic items
1357
1358 %f file name (finds a string)
Bram Moolenaard76ce852018-05-01 15:02:04 +02001359 %o module name (finds a string)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001360 %l line number (finds a number)
1361 %c column number (finds a number representing character
1362 column of the error, (1 <tab> == 1 character column))
1363 %v virtual column number (finds a number representing
1364 screen column of the error (1 <tab> == 8 screen
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001365 columns))
Bram Moolenaar071d4272004-06-13 20:20:40 +00001366 %t error type (finds a single character)
1367 %n error number (finds a number)
1368 %m error message (finds a string)
1369 %r matches the "rest" of a single-line file message %O/P/Q
Bram Moolenaarc8734422012-06-01 22:38:45 +02001370 %p pointer line (finds a sequence of '-', '.', ' ' or
1371 tabs and uses the length for the column number)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001372 %*{conv} any scanf non-assignable conversion
1373 %% the single '%' character
Bram Moolenaar2641f772005-03-25 21:58:17 +00001374 %s search text (finds a string)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001375
Bram Moolenaare344bea2005-09-01 20:46:49 +00001376The "%f" conversion may depend on the current 'isfname' setting. "~/" is
Bram Moolenaarf4630b62005-05-20 21:31:17 +00001377expanded to the home directory and environment variables are expanded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001378
Bram Moolenaare344bea2005-09-01 20:46:49 +00001379The "%f" and "%m" conversions have to detect the end of the string. This
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00001380normally happens by matching following characters and items. When nothing is
Bram Moolenaare344bea2005-09-01 20:46:49 +00001381following the rest of the line is matched. If "%f" is followed by a '%' or a
1382backslash, it will look for a sequence of 'isfname' characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001383
1384On MS-DOS, MS-Windows and OS/2 a leading "C:" will be included in "%f", even
1385when using "%f:". This means that a file name which is a single alphabetical
1386letter will not be detected.
1387
1388The "%p" conversion is normally followed by a "^". It's used for compilers
1389that output a line like: >
1390 ^
1391or >
1392 ---------^
1393to indicate the column of the error. This is to be used in a multi-line error
1394message. See |errorformat-javac| for a useful example.
1395
Bram Moolenaar85eee132018-05-06 17:57:30 +02001396The "%s" conversion specifies the text to search for, to locate the error line.
Bram Moolenaar2641f772005-03-25 21:58:17 +00001397The text is used as a literal string. The anchors "^" and "$" are added to
1398the text to locate the error line exactly matching the search text and the
1399text is prefixed with the "\V" atom to make it "very nomagic". The "%s"
1400conversion can be used to locate lines without a line number in the error
1401output. Like the output of the "grep" shell command.
1402When the pattern is present the line number will not be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001403
Bram Moolenaard76ce852018-05-01 15:02:04 +02001404The "%o" conversion specifies the module name in quickfix entry. If present
1405it will be used in quickfix error window instead of the filename. The module
1406name is used only for displaying purposes, the file name is used when jumping
1407to the file.
1408
Bram Moolenaar071d4272004-06-13 20:20:40 +00001409Changing directory
1410
1411The following uppercase conversion characters specify the type of special
Bram Moolenaara9defad2018-07-08 18:20:24 +02001412format strings. At most one of them may be given as a prefix at the beginning
Bram Moolenaar071d4272004-06-13 20:20:40 +00001413of a single comma-separated format pattern.
1414Some compilers produce messages that consist of directory names that have to
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001415be prepended to each file name read by %f (example: GNU make). The following
Bram Moolenaar071d4272004-06-13 20:20:40 +00001416codes can be used to scan these directory names; they will be stored in an
1417internal directory stack. *E379*
1418 %D "enter directory" format string; expects a following
1419 %f that finds the directory name
1420 %X "leave directory" format string; expects following %f
1421
1422When defining an "enter directory" or "leave directory" format, the "%D" or
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001423"%X" has to be given at the start of that substring. Vim tracks the directory
Bram Moolenaar071d4272004-06-13 20:20:40 +00001424changes and prepends the current directory to each erroneous file found with a
1425relative path. See |quickfix-directory-stack| for details, tips and
1426limitations.
1427
1428
1429Multi-line messages *errorformat-multi-line*
1430
1431It is possible to read the output of programs that produce multi-line
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001432messages, i.e. error strings that consume more than one line. Possible
Bram Moolenaar071d4272004-06-13 20:20:40 +00001433prefixes are:
1434 %E start of a multi-line error message
1435 %W start of a multi-line warning message
1436 %I start of a multi-line informational message
1437 %A start of a multi-line message (unspecified type)
Bram Moolenaarb3656ed2006-03-20 21:59:49 +00001438 %> for next line start with current pattern again |efm-%>|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001439 %C continuation of a multi-line message
1440 %Z end of a multi-line message
1441These can be used with '+' and '-', see |efm-ignore| below.
1442
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001443Using "\n" in the pattern won't work to match multi-line messages.
1444
Bram Moolenaar071d4272004-06-13 20:20:40 +00001445Example: Your compiler happens to write out errors in the following format
1446(leading line numbers not being part of the actual output):
1447
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001448 1 Error 275 ~
1449 2 line 42 ~
1450 3 column 3 ~
1451 4 ' ' expected after '--' ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00001452
1453The appropriate error format string has to look like this: >
1454 :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%m
1455
1456And the |:clist| error message generated for this error is:
1457
1458 1:42 col 3 error 275: ' ' expected after '--'
1459
1460Another example: Think of a Python interpreter that produces the following
1461error message (line numbers are not part of the actual output):
1462
1463 1 ==============================================================
1464 2 FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest)
1465 3 --------------------------------------------------------------
1466 4 Traceback (most recent call last):
1467 5 File "unittests/dbfacadeTest.py", line 89, in testFoo
1468 6 self.assertEquals(34, dtid)
1469 7 File "/usr/lib/python2.2/unittest.py", line 286, in
1470 8 failUnlessEqual
1471 9 raise self.failureException, \
1472 10 AssertionError: 34 != 33
1473 11
1474 12 --------------------------------------------------------------
1475 13 Ran 27 tests in 0.063s
1476
1477Say you want |:clist| write the relevant information of this message only,
1478namely:
1479 5 unittests/dbfacadeTest.py:89: AssertionError: 34 != 33
1480
1481Then the error format string could be defined as follows: >
1482 :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%m
1483
1484Note that the %C string is given before the %A here: since the expression
1485' %.%#' (which stands for the regular expression ' .*') matches every line
1486starting with a space, followed by any characters to the end of the line,
1487it also hides line 7 which would trigger a separate error message otherwise.
1488Error format strings are always parsed pattern by pattern until the first
1489match occurs.
Bram Moolenaarb3656ed2006-03-20 21:59:49 +00001490 *efm-%>*
1491The %> item can be used to avoid trying patterns that appear earlier in
1492'errorformat'. This is useful for patterns that match just about anything.
1493For example, if the error looks like this:
1494
1495 Error in line 123 of foo.c: ~
1496 unknown variable "i" ~
1497
1498This can be found with: >
1499 :set efm=xxx,%E%>Error in line %l of %f:,%Z%m
1500Where "xxx" has a pattern that would also match the second line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001501
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001502Important: There is no memory of what part of the errorformat matched before;
1503every line in the error file gets a complete new run through the error format
1504lines. For example, if one has: >
1505 setlocal efm=aa,bb,cc,dd,ee
1506Where aa, bb, etc. are error format strings. Each line of the error file will
1507be matched to the pattern aa, then bb, then cc, etc. Just because cc matched
1508the previous error line does _not_ mean that dd will be tried first on the
1509current line, even if cc and dd are multi-line errorformat strings.
1510
1511
Bram Moolenaar071d4272004-06-13 20:20:40 +00001512
1513Separate file name *errorformat-separate-filename*
1514
1515These prefixes are useful if the file name is given once and multiple messages
1516follow that refer to this file name.
1517 %O single-line file message: overread the matched part
1518 %P single-line file message: push file %f onto the stack
1519 %Q single-line file message: pop the last file from stack
1520
1521Example: Given a compiler that produces the following error logfile (without
1522leading line numbers):
1523
1524 1 [a1.tt]
1525 2 (1,17) error: ';' missing
1526 3 (21,2) warning: variable 'z' not defined
1527 4 (67,3) error: end of file found before string ended
1528 5
1529 6 [a2.tt]
1530 7
1531 8 [a3.tt]
1532 9 NEW compiler v1.1
1533 10 (2,2) warning: variable 'x' not defined
1534 11 (67,3) warning: 's' already defined
1535
1536This logfile lists several messages for each file enclosed in [...] which are
1537properly parsed by an error format like this: >
1538 :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-Q
1539
1540A call of |:clist| writes them accordingly with their correct filenames:
1541
1542 2 a1.tt:1 col 17 error: ';' missing
1543 3 a1.tt:21 col 2 warning: variable 'z' not defined
1544 4 a1.tt:67 col 3 error: end of file found before string ended
1545 8 a3.tt:2 col 2 warning: variable 'x' not defined
1546 9 a3.tt:67 col 3 warning: 's' already defined
1547
1548Unlike the other prefixes that all match against whole lines, %P, %Q and %O
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001549can be used to match several patterns in the same line. Thus it is possible
Bram Moolenaar071d4272004-06-13 20:20:40 +00001550to parse even nested files like in the following line:
1551 {"file1" {"file2" error1} error2 {"file3" error3 {"file4" error4 error5}}}
1552The %O then parses over strings that do not contain any push/pop file name
1553information. See |errorformat-LaTeX| for an extended example.
1554
1555
1556Ignoring and using whole messages *efm-ignore*
1557
1558The codes '+' or '-' can be combined with the uppercase codes above; in that
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001559case they have to precede the letter, e.g. '%+A' or '%-G':
Bram Moolenaar071d4272004-06-13 20:20:40 +00001560 %- do not include the matching multi-line in any output
1561 %+ include the whole matching line in the %m error string
1562
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001563One prefix is only useful in combination with '+' or '-', namely %G. It parses
Bram Moolenaar071d4272004-06-13 20:20:40 +00001564over lines containing general information like compiler version strings or
1565other headers that can be skipped.
1566 %-G ignore this message
1567 %+G general message
1568
1569
1570Pattern matching
1571
1572The scanf()-like "%*[]" notation is supported for backward-compatibility
1573with previous versions of Vim. However, it is also possible to specify
1574(nearly) any Vim supported regular expression in format strings.
1575Since meta characters of the regular expression language can be part of
1576ordinary matching strings or file names (and therefore internally have to
1577be escaped), meta symbols have to be written with leading '%':
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001578 %\ The single '\' character. Note that this has to be
Bram Moolenaar071d4272004-06-13 20:20:40 +00001579 escaped ("%\\") in ":set errorformat=" definitions.
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001580 %. The single '.' character.
1581 %# The single '*'(!) character.
1582 %^ The single '^' character. Note that this is not
1583 useful, the pattern already matches start of line.
1584 %$ The single '$' character. Note that this is not
1585 useful, the pattern already matches end of line.
1586 %[ The single '[' character for a [] character range.
1587 %~ The single '~' character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001588When using character classes in expressions (see |/\i| for an overview),
1589terms containing the "\+" quantifier can be written in the scanf() "%*"
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001590notation. Example: "%\\d%\\+" ("\d\+", "any number") is equivalent to "%*\\d".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001591Important note: The \(...\) grouping of sub-matches can not be used in format
1592specifications because it is reserved for internal conversions.
1593
1594
1595Multiple entries in 'errorformat' *efm-entries*
1596
1597To be able to detect output from several compilers, several format patterns
1598may be put in 'errorformat', separated by commas (note: blanks after the comma
1599are ignored). The first pattern that has a complete match is used. If no
1600match is found, matching parts from the last one will be used, although the
1601file name is removed and the error message is set to the whole message. If
1602there is a pattern that may match output from several compilers (but not in a
1603right way), put it after one that is more restrictive.
1604
1605To include a comma in a pattern precede it with a backslash (you have to type
1606two in a ":set" command). To include a backslash itself give two backslashes
1607(you have to type four in a ":set" command). You also need to put a backslash
1608before a space for ":set".
1609
1610
1611Valid matches *quickfix-valid*
1612
1613If a line does not completely match one of the entries in 'errorformat', the
1614whole line is put in the error message and the entry is marked "not valid"
1615These lines are skipped with the ":cn" and ":cp" commands (unless there is
1616no valid line at all). You can use ":cl!" to display all the error messages.
1617
1618If the error format does not contain a file name Vim cannot switch to the
1619correct file. You will have to do this by hand.
1620
1621
1622Examples
1623
1624The format of the file from the Amiga Aztec compiler is:
1625
1626 filename>linenumber:columnnumber:errortype:errornumber:errormessage
1627
1628 filename name of the file in which the error was detected
1629 linenumber line number where the error was detected
1630 columnnumber column number where the error was detected
1631 errortype type of the error, normally a single 'E' or 'W'
1632 errornumber number of the error (for lookup in the manual)
1633 errormessage description of the error
1634
1635This can be matched with this 'errorformat' entry:
1636 %f>%l:%c:%t:%n:%m
1637
1638Some examples for C compilers that produce single-line error outputs:
1639%f:%l:\ %t%*[^0123456789]%n:\ %m for Manx/Aztec C error messages
1640 (scanf() doesn't understand [0-9])
1641%f\ %l\ %t%*[^0-9]%n:\ %m for SAS C
1642\"%f\"\\,%*[^0-9]%l:\ %m for generic C compilers
1643%f:%l:\ %m for GCC
1644%f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f',
1645%Dgmake[%*\\d]:\ Leaving\ directory\ `%f'
1646 for GCC with gmake (concat the lines!)
1647%f(%l)\ :\ %*[^:]:\ %m old SCO C compiler (pre-OS5)
1648%f(%l)\ :\ %t%*[^0-9]%n:\ %m idem, with error type and number
1649%f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m
1650 for GCC, with some extras
1651
1652Extended examples for the handling of multi-line messages are given below,
1653see |errorformat-Jikes| and |errorformat-LaTeX|.
1654
1655Note the backslash in front of a space and double quote. It is required for
1656the :set command. There are two backslashes in front of a comma, one for the
1657:set command and one to avoid recognizing the comma as a separator of error
1658formats.
1659
1660
1661Filtering messages
1662
1663If you have a compiler that produces error messages that do not fit in the
1664format string, you could write a program that translates the error messages
1665into this format. You can use this program with the ":make" command by
1666changing the 'makeprg' option. For example: >
1667 :set mp=make\ \\\|&\ error_filter
1668The backslashes before the pipe character are required to avoid it to be
1669recognized as a command separator. The backslash before each space is
1670required for the set command.
1671
1672=============================================================================
16738. The directory stack *quickfix-directory-stack*
1674
1675Quickfix maintains a stack for saving all used directories parsed from the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001676make output. For GNU-make this is rather simple, as it always prints the
1677absolute path of all directories it enters and leaves. Regardless if this is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001678done via a 'cd' command in the makefile or with the parameter "-C dir" (change
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001679to directory before reading the makefile). It may be useful to use the switch
Bram Moolenaar071d4272004-06-13 20:20:40 +00001680"-w" to force GNU-make to print out the working directory before and after
1681processing.
1682
1683Maintaining the correct directory is more complicated if you don't use
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001684GNU-make. AIX-make for example doesn't print any information about its
1685working directory. Then you need to enhance the makefile. In the makefile of
1686LessTif there is a command which echoes "Making {target} in {dir}". The
Bram Moolenaar6dfc28b2010-02-11 14:19:15 +01001687special problem here is that it doesn't print information on leaving the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001688directory and that it doesn't print the absolute path.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001689
1690To solve the problem with relative paths and missing "leave directory"
1691messages Vim uses following algorithm:
1692
16931) Check if the given directory is a subdirectory of the current directory.
1694 If this is true, store it as the current directory.
16952) If it is not a subdir of the current directory, try if this is a
1696 subdirectory of one of the upper directories.
16973) If the directory still isn't found, it is assumed to be a subdirectory
1698 of Vim's current directory.
1699
1700Additionally it is checked for every file, if it really exists in the
1701identified directory. If not, it is searched in all other directories of the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001702directory stack (NOT the directory subtree!). If it is still not found, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001703assumed that it is in Vim's current directory.
1704
Bram Moolenaare667c952010-07-05 22:57:59 +02001705There are limitations in this algorithm. These examples assume that make just
Bram Moolenaar071d4272004-06-13 20:20:40 +00001706prints information about entering a directory in the form "Making all in dir".
1707
17081) Assume you have following directories and files:
1709 ./dir1
1710 ./dir1/file1.c
1711 ./file1.c
1712
1713 If make processes the directory "./dir1" before the current directory and
1714 there is an error in the file "./file1.c", you will end up with the file
1715 "./dir1/file.c" loaded by Vim.
1716
1717 This can only be solved with a "leave directory" message.
1718
17192) Assume you have following directories and files:
1720 ./dir1
1721 ./dir1/dir2
1722 ./dir2
1723
1724 You get the following:
1725
1726 Make output Directory interpreted by Vim
1727 ------------------------ ----------------------------
1728 Making all in dir1 ./dir1
1729 Making all in dir2 ./dir1/dir2
1730 Making all in dir2 ./dir1/dir2
1731
1732 This can be solved by printing absolute directories in the "enter directory"
Bram Moolenaar214641f2017-03-05 17:04:09 +01001733 message or by printing "leave directory" messages.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001734
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001735To avoid this problem, ensure to print absolute directory names and "leave
Bram Moolenaar071d4272004-06-13 20:20:40 +00001736directory" messages.
1737
1738Examples for Makefiles:
1739
1740Unix:
1741 libs:
1742 for dn in $(LIBDIRS); do \
1743 (cd $$dn; echo "Entering dir '$$(pwd)'"; make); \
1744 echo "Leaving dir"; \
1745 done
1746
1747Add
1748 %DEntering\ dir\ '%f',%XLeaving\ dir
1749to your 'errorformat' to handle the above output.
1750
1751Note that Vim doesn't check if the directory name in a "leave directory"
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001752messages is the current directory. This is why you could just use the message
Bram Moolenaar071d4272004-06-13 20:20:40 +00001753"Leaving dir".
1754
1755=============================================================================
17569. Specific error file formats *errorformats*
1757
1758 *errorformat-Jikes*
1759Jikes(TM), a source-to-bytecode Java compiler published by IBM Research,
1760produces simple multi-line error messages.
1761
1762An 'errorformat' string matching the produced messages is shown below.
1763The following lines can be placed in the user's |vimrc| to overwrite Vim's
1764recognized default formats, or see |:set+=| how to install this format
1765additionally to the default. >
1766
1767 :set efm=%A%f:%l:%c:%*\\d:%*\\d:,
1768 \%C%*\\s%trror:%m,
1769 \%+C%*[^:]%trror:%m,
1770 \%C%*\\s%tarning:%m,
1771 \%C%m
1772<
1773Jikes(TM) produces a single-line error message when invoked with the option
1774"+E", and can be matched with the following: >
1775
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001776 :setl efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%m
Bram Moolenaar071d4272004-06-13 20:20:40 +00001777<
1778 *errorformat-javac*
1779This 'errorformat' has been reported to work well for javac, which outputs a
1780line with "^" to indicate the column of the error: >
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001781 :setl efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%#
Bram Moolenaar071d4272004-06-13 20:20:40 +00001782or: >
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001783 :setl efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%#
Bram Moolenaar071d4272004-06-13 20:20:40 +00001784<
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001785Here is an alternative from Michael F. Lamb for Unix that filters the errors
1786first: >
1787 :setl errorformat=%Z%f:%l:\ %m,%A%p^,%-G%*[^sl]%.%#
Bram Moolenaar26df0922014-02-23 23:39:13 +01001788 :setl makeprg=javac\ %:S\ 2>&1\ \\\|\ vim-javac-filter
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001789
1790You need to put the following in "vim-javac-filter" somewhere in your path
1791(e.g., in ~/bin) and make it executable: >
1792 #!/bin/sed -f
1793 /\^$/s/\t/\ /g;/:[0-9]\+:/{h;d};/^[ \t]*\^/G;
1794
1795In English, that sed script:
1796- Changes single tabs to single spaces and
1797- Moves the line with the filename, line number, error message to just after
1798 the pointer line. That way, the unused error text between doesn't break
1799 vim's notion of a "multi-line message" and also doesn't force us to include
1800 it as a "continuation of a multi-line message."
1801
Bram Moolenaar071d4272004-06-13 20:20:40 +00001802 *errorformat-ant*
1803For ant (http://jakarta.apache.org/) the above errorformat has to be modified
1804to honour the leading [javac] in front of each javac output line: >
1805 :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#
1806
1807The 'errorformat' can also be configured to handle ant together with either
1808javac or jikes. If you're using jikes, you should tell ant to use jikes' +E
1809command line switch which forces jikes to generate one-line error messages.
1810This is what the second line (of a build.xml file) below does: >
1811 <property name = "build.compiler" value = "jikes"/>
1812 <property name = "build.compiler.emacs" value = "true"/>
1813
1814The 'errorformat' which handles ant with both javac and jikes is: >
1815 :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m,
1816 \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#
1817<
1818 *errorformat-jade*
1819parsing jade (see http://www.jclark.com/) errors is simple: >
1820 :set efm=jade:%f:%l:%c:%t:%m
1821<
1822 *errorformat-LaTeX*
1823The following is an example how an 'errorformat' string can be specified
1824for the (La)TeX typesetting system which displays error messages over
1825multiple lines. The output of ":clist" and ":cc" etc. commands displays
1826multi-lines in a single line, leading white space is removed.
1827It should be easy to adopt the above LaTeX errorformat to any compiler output
1828consisting of multi-line errors.
1829
1830The commands can be placed in a |vimrc| file or some other Vim script file,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001831e.g. a script containing LaTeX related stuff which is loaded only when editing
Bram Moolenaar071d4272004-06-13 20:20:40 +00001832LaTeX sources.
1833Make sure to copy all lines of the example (in the given order), afterwards
1834remove the comment lines. For the '\' notation at the start of some lines see
1835|line-continuation|.
1836
1837 First prepare 'makeprg' such that LaTeX will report multiple
1838 errors; do not stop when the first error has occurred: >
1839 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
1840<
1841 Start of multi-line error messages: >
1842 :set efm=%E!\ LaTeX\ %trror:\ %m,
1843 \%E!\ %m,
1844< Start of multi-line warning messages; the first two also
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001845 include the line number. Meaning of some regular expressions:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001846 - "%.%#" (".*") matches a (possibly empty) string
1847 - "%*\\d" ("\d\+") matches a number >
1848 \%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#,
1849 \%+W%.%#\ at\ lines\ %l--%*\\d,
1850 \%WLaTeX\ %.%#Warning:\ %m,
1851< Possible continuations of error/warning messages; the first
1852 one also includes the line number: >
1853 \%Cl.%l\ %m,
1854 \%+C\ \ %m.,
1855 \%+C%.%#-%.%#,
1856 \%+C%.%#[]%.%#,
1857 \%+C[]%.%#,
1858 \%+C%.%#%[{}\\]%.%#,
1859 \%+C<%.%#>%.%#,
1860 \%C\ \ %m,
1861< Lines that match the following patterns do not contain any
1862 important information; do not include them in messages: >
1863 \%-GSee\ the\ LaTeX%m,
1864 \%-GType\ \ H\ <return>%m,
1865 \%-G\ ...%.%#,
1866 \%-G%.%#\ (C)\ %.%#,
1867 \%-G(see\ the\ transcript%.%#),
1868< Generally exclude any empty or whitespace-only line from
1869 being displayed: >
1870 \%-G\\s%#,
1871< The LaTeX output log does not specify the names of erroneous
1872 source files per line; rather they are given globally,
1873 enclosed in parentheses.
1874 The following patterns try to match these names and store
1875 them in an internal stack. The patterns possibly scan over
1876 the same input line (one after another), the trailing "%r"
1877 conversion indicates the "rest" of the line that will be
1878 parsed in the next go until the end of line is reached.
1879
1880 Overread a file name enclosed in '('...')'; do not push it
1881 on a stack since the file apparently does not contain any
1882 error: >
1883 \%+O(%f)%r,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001884< Push a file name onto the stack. The name is given after '(': >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001885 \%+P(%f%r,
1886 \%+P\ %\\=(%f%r,
1887 \%+P%*[^()](%f%r,
1888 \%+P[%\\d%[^()]%#(%f%r,
1889< Pop the last stored file name when a ')' is scanned: >
1890 \%+Q)%r,
1891 \%+Q%*[^()])%r,
1892 \%+Q[%\\d%*[^()])%r
1893
1894Note that in some cases file names in the LaTeX output log cannot be parsed
1895properly. The parser might have been messed up by unbalanced parentheses
1896then. The above example tries to catch the most relevant cases only.
1897You can customize the given setting to suit your own purposes, for example,
1898all the annoying "Overfull ..." warnings could be excluded from being
1899recognized as an error.
1900Alternatively to filtering the LaTeX compiler output, it is also possible
1901to directly read the *.log file that is produced by the [La]TeX compiler.
1902This contains even more useful information about possible error causes.
1903However, to properly parse such a complex file, an external filter should
1904be used. See the description further above how to make such a filter known
1905by Vim.
1906
1907 *errorformat-Perl*
1908In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl
1909error messages into a format that quickfix mode will understand. See the
Bram Moolenaar8c8de832008-06-24 22:58:06 +00001910start of the file about how to use it. (This script is deprecated, see
1911|compiler-perl|.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001912
1913
1914
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001915 vim:tw=78:ts=8:noet:ft=help:norl: