vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

quickfix.txt (105531B)


      1 *quickfix.txt*  For Vim version 9.2.  Last change: 2026 Sep 25
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 This subject is introduced in section |30.1| of the user manual.
      8 
      9 1. Using QuickFix commands		|quickfix|
     10 2. The error window			|quickfix-window|
     11 3. Using more than one list of errors	|quickfix-error-lists|
     12 4. Using :make				|:make_makeprg|
     13 5. Using :grep				|grep|
     14 6. Selecting a compiler			|compiler-select|
     15 7. The error format			|error-file-format|
     16 8. The directory stack			|quickfix-directory-stack|
     17 9. Specific error file formats		|errorformats|
     18 10. Customizing the quickfix window	|quickfix-window-function|
     19 
     20 The quickfix commands are not available when the |+quickfix| feature was
     21 disabled at compile time.
     22 
     23 =============================================================================
     24 1. Using QuickFix commands			*quickfix* *Quickfix* *E42*
     25 
     26 Vim has a special mode to speedup the edit-compile-edit cycle.  This is
     27 inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga.
     28 The idea is to save the error messages from the compiler in a file and use Vim
     29 to jump to the errors one by one.  You can examine each problem and fix it,
     30 without having to remember all the error messages.
     31 
     32 In Vim the quickfix commands are used more generally to find a list of
     33 positions in files.  For example, |:vimgrep| finds pattern matches.  You can
     34 use the positions in a script with the |getqflist()| function.  Thus you can
     35 do a lot more than the edit/compile/fix cycle!
     36 
     37 If you have the error messages in a file you can start Vim with: >
     38 	vim -q filename
     39 
     40 From inside Vim an easy way to run a command and handle the output is with the
     41 |:make| command (see below).
     42 
     43 The 'errorformat' option should be set to match the error messages from your
     44 compiler (see |errorformat| below).  Vim uses it to extract information such
     45 as the file name, line number and message from each line of compiler output.
     46 Lines that do not match are kept as invalid entries and are skipped by
     47 commands such as |:cnext|.  Use |:clist|! to display them as well.
     48 
     49 					*quickfix-stack* *quickfix-ID* *E1545*
     50 Each quickfix list has a unique identifier called the quickfix ID and this
     51 number will not change within a Vim session.  The |getqflist()| function can be
     52 used to get the identifier assigned to a list.  There is also a quickfix list
     53 number, which is its position in the quickfix stack.  This number may change
     54 when lists are added or removed, or when more than 'chistory' lists are kept.
     55 Use the ID when a script needs to refer to the same list reliably; use the
     56 list number when referring to its current position in the stack.
     57 
     58 						*location-list* *E776*
     59 A location list is a quickfix list tied to one window.  Each window can have a
     60 separate location list, and commands such as `:lvimgrep`, `:lgrep`,
     61 `:lhelpgrep` and `:lmake` use it instead of the global quickfix list.  The
     62 corresponding commands without the "l" prefix use the quickfix list.
     63 						*location-list-file-window*
     64 The location list is independent of the quickfix list.  A location list can
     65 be associated with only one window.
     66 
     67 When a window with a location list is split, the new window gets a copy of the
     68 location list.  When there are no longer any references to a location list,
     69 the location list is destroyed.
     70 
     71 						*quickfix-changedtick*
     72 Every quickfix and location list has a read-only changedtick variable that
     73 tracks the total number of changes made to the list.  Every time the quickfix
     74 list is modified, this count is incremented.  This can be used to perform an
     75 action only when the list has changed.  The |getqflist()| and |getloclist()|
     76 functions can be used to query the current value of changedtick.  You cannot
     77 change the changedtick variable.
     78 
     79 The following quickfix commands can be used.  The location list commands are
     80 similar to the quickfix commands, replacing the 'c' prefix in the quickfix
     81 command with 'l'.
     82 
     83 							*E924*
     84 If the current window was closed by an |autocommand| while processing a
     85 location list command, it will be aborted.
     86 
     87 							*E925* *E926*
     88 If the current quickfix or location list was changed by an |autocommand| while
     89 processing a quickfix or location list command, it will be aborted.
     90 
     91 							*:cc*
     92 :cc[!] [nr]		Display error [nr].  If [nr] is omitted, the same
     93 :[nr]cc[!]		error is displayed again.  Without [!] this doesn't
     94 			work when jumping to another buffer, the current
     95 			buffer has been changed, there is the only window for
     96 			the buffer and both 'hidden' and 'autowrite' are off.
     97 			When jumping to another buffer with [!] any changes to
     98 			the current buffer are lost, unless 'hidden' is set or
     99 			there is another window for this buffer.
    100 			The 'switchbuf' settings are respected when jumping
    101 			to a buffer.
    102 			When used in the quickfix window the line number can
    103 			be used, including "." for the current line and "$"
    104 			for the last line.
    105 
    106 							*:ll*
    107 :ll[!] [nr]		Same as ":cc", except the location list for the
    108 :[nr]ll[!]		current window is used instead of the quickfix list.
    109 
    110 						*:cn* *:cne* *:cnext* *E553*
    111 :[count]cn[ext][!]	Display the [count] next error in the list that
    112 			includes a file name.  Entries without a file name are
    113 			skipped, since Vim cannot use them to jump to a file.
    114 			If there are no file names at all, go to the [count]
    115 			next error.  See |:cc| for [!] and 'switchbuf'.
    116 
    117 :[count]cN[ext][!]		*:cp* *:cprevious*  *:cprev* *:cN* *:cNext*
    118 :[count]cp[revious][!]	Display the [count] previous error in the list that
    119 			includes a file name.  Entries without a file name are
    120 			skipped, since Vim cannot use them to jump to a file.
    121 			If there are no file names at all, go to the [count]
    122 			previous error.  See |:cc| for [!] and 'switchbuf'.
    123 
    124 							*:lne* *:lnext*
    125 :[count]lne[xt][!]	Same as ":cnext", except the location list for the
    126 			current window is used instead of the quickfix list.
    127 
    128 
    129 :[count]lN[ext][!]		*:lp* *:lprevious* *:lprev* *:lN* *:lNext*
    130 :[count]lp[revious][!]	Same as ":cNext" and ":cprevious", except the location
    131 			list for the current window is used instead of the
    132 			quickfix list.
    133 
    134 							*:cabo* *:cabove*
    135 :[count]cabo[ve]	Go to the [count] error above the current line in the
    136 			current buffer.  If [count] is omitted, then 1 is
    137 			used.  If there are no errors, then an error message
    138 			is displayed.  Assumes that the entries in a quickfix
    139 			list are sorted by their buffer number and line
    140 			number.  If there are multiple errors on the same
    141 			line, then only the first entry is used.  If [count]
    142 			exceeds the number of entries above the current line,
    143 			then the first error in the file is selected.
    144 
    145 							*:lab* *:labove*
    146 :[count]lab[ove]	Same as ":cabove", except the location list for the
    147 			current window is used instead of the quickfix list.
    148 
    149 							*:cbel* *:cbelow*
    150 :[count]cbel[ow]	Go to the [count] error below the current line in the
    151 			current buffer.  If [count] is omitted, then 1 is
    152 			used.  If there are no errors, then an error message
    153 			is displayed.  Assumes that the entries in a quickfix
    154 			list are sorted by their buffer number and line
    155 			number.  If there are multiple errors on the same
    156 			line, then only the first entry is used.  If [count]
    157 			exceeds the number of entries below the current line,
    158 			then the last error in the file is selected.
    159 
    160 							*:lbel* *:lbelow*
    161 :[count]lbel[ow]	Same as ":cbelow", except the location list for the
    162 			current window is used instead of the quickfix list.
    163 
    164 							*:cbe* *:cbefore*
    165 :[count]cbe[fore]	Go to the [count] error before the current cursor
    166 			position in the current buffer.  If [count] is
    167 			omitted, then 1 is used.  If there are no errors, then
    168 			an error message is displayed.  Assumes that the
    169 			entries in a quickfix list are sorted by their buffer,
    170 			line and column numbers.  If [count] exceeds the
    171 			number of entries before the current position, then
    172 			the first error in the file is selected.
    173 
    174 							*:lbe* *:lbefore*
    175 :[count]lbe[fore]	Same as ":cbefore", except the location list for the
    176 			current window is used instead of the quickfix list.
    177 
    178 							*:caf* *:cafter*
    179 :[count]caf[ter]	Go to the [count] error after the current cursor
    180 			position in the current buffer.  If [count] is
    181 			omitted, then 1 is used.  If there are no errors, then
    182 			an error message is displayed.  Assumes that the
    183 			entries in a quickfix list are sorted by their buffer,
    184 			line and column numbers.  If [count] exceeds the
    185 			number of entries after the current position, then
    186 			the last error in the file is selected.
    187 
    188 							*:laf* *:lafter*
    189 :[count]laf[ter]	Same as ":cafter", except the location list for the
    190 			current window is used instead of the quickfix list.
    191 
    192 							*:cnf* *:cnfile*
    193 :[count]cnf[ile][!]	Display the first error in the [count] next file in
    194 			the list that includes a file name.  If there are no
    195 			file names at all or if there is no next file, go to
    196 			the [count] next error.  See |:cc| for [!] and
    197 			'switchbuf'.
    198 
    199 							*:lnf* *:lnfile*
    200 :[count]lnf[ile][!]	Same as ":cnfile", except the location list for the
    201 			current window is used instead of the quickfix list.
    202 
    203 :[count]cNf[ile][!]			*:cpf* *:cpfile* *:cNf* *:cNfile*
    204 :[count]cpf[ile][!]	Display the last error in the [count] previous file in
    205 			the list that includes a file name.  If there are no
    206 			file names at all or if there is no next file, go to
    207 			the [count] previous error.  See |:cc| for [!] and
    208 			'switchbuf'.
    209 
    210 
    211 :[count]lNf[ile][!]			*:lpf* *:lpfile* *:lNf* *:lNfile*
    212 :[count]lpf[ile][!]	Same as ":cNfile" and ":cpfile", except the location
    213 			list for the current window is used instead of the
    214 			quickfix list.
    215 
    216 							*:crewind* *:cr*
    217 :cr[ewind][!] [nr]	Display error [nr].  If [nr] is omitted, the FIRST
    218 			error is displayed.  See |:cc|.
    219 
    220 							*:lrewind* *:lr*
    221 :lr[ewind][!] [nr]	Same as ":crewind", except the location list for the
    222 			current window is used instead of the quickfix list.
    223 
    224 							*:cfirst* *:cfir*
    225 :cfir[st][!] [nr]	Same as ":crewind".
    226 
    227 							*:lfirst* *:lfir*
    228 :lfir[st][!] [nr]	Same as ":lrewind".
    229 
    230 							*:clast* *:cla*
    231 :cla[st][!] [nr]	Display error [nr].  If [nr] is omitted, the LAST
    232 			error is displayed.  See |:cc|.
    233 
    234 							*:llast* *:lla*
    235 :lla[st][!] [nr]	Same as ":clast", except the location list for the
    236 			current window is used instead of the quickfix list.
    237 
    238 							*:cq* *:cquit*
    239 :cq[uit][!]
    240 :{N}cq[uit][!]
    241 :cq[uit][!] {N}		Quit Vim with error code {N}.  {N} defaults to one.
    242 			Useful when Vim is called from another program:
    243 			e.g., a compiler will not compile the same file again,
    244 			`git commit` will abort the committing process, `fc`
    245 			(built-in for shells like bash and zsh) will not
    246 			execute the command, etc.
    247 			{N} can also be zero, in which case Vim exits
    248 			normally.
    249 			WARNING: This abandons changes in all files, like
    250 			|:qall|!.
    251 			The [!] does not change this.  Vim returns a non-zero
    252 			exit code, unless {N} is zero.
    253 
    254 							*:cf* *:cfi* *:cfile*
    255 :cf[ile][!] [errorfile]	Read the error file and jump to the first error.
    256 			This is done automatically when Vim is started with
    257 			the -q option.  You can use this command when you
    258 			keep Vim running while compiling.  If you give the
    259 			name of the errorfile, the 'errorfile' option will
    260 			be set to [errorfile].  See |:cc| for [!].
    261 			If the encoding of the error file differs from the
    262 			'encoding' option, you can use the 'makeencoding'
    263 			option to specify the encoding.
    264 
    265 							*:lf* *:lfi* *:lfile*
    266 :lf[ile][!] [errorfile]	Same as ":cfile", except the location list for the
    267 			current window is used instead of the quickfix list.
    268 			You can not use the -q command-line option to set
    269 			the location list.
    270 
    271 
    272 :cg[etfile] [errorfile]					*:cg* *:cgetfile*
    273 			Read the error file.  Just like ":cfile" but don't
    274 			jump to the first error.
    275 			If the encoding of the error file differs from the
    276 			'encoding' option, you can use the 'makeencoding'
    277 			option to specify the encoding.
    278 
    279 
    280 :lg[etfile] [errorfile]					*:lg* *:lge* *:lgetfile*
    281 			Same as ":cgetfile", except the location list for the
    282 			current window is used instead of the quickfix list.
    283 
    284 							*:caddf* *:caddfile*
    285 :caddf[ile] [errorfile]	Read the error file and add the errors from the
    286 			errorfile to the current quickfix list.  If a quickfix
    287 			list is not present, then a new list is created.
    288 			If the encoding of the error file differs from the
    289 			'encoding' option, you can use the 'makeencoding'
    290 			option to specify the encoding.
    291 
    292 							*:laddf* *:laddfile*
    293 :laddf[ile] [errorfile]	Same as ":caddfile", except the location list for the
    294 			current window is used instead of the quickfix list.
    295 
    296 The following commands read error messages from a buffer:
    297 `:cbuffer` creates a list and jumps to its first error, `:cgetbuffer` creates
    298 a list without jumping, and `:caddbuffer` adds entries to the current list
    299 without changing the cursor position.  The corresponding commands with an "l"
    300 prefix use the location list.
    301 
    302 						*:cb* *:cbuffer* *E681*
    303 :[range]cb[uffer][!] [bufnr]
    304 			Read the error list from the current buffer.
    305 			When [bufnr] is given it must be the number of a
    306 			loaded buffer.  That buffer will then be used instead
    307 			of the current buffer.
    308 			A range can be specified for the lines to be used, for
    309 			example `:10,20cbuffer`.  Otherwise all lines in the
    310 			buffer are used.
    311 			See |:cc| for [!].
    312 
    313 						*:lb* *:lbuffer*
    314 :[range]lb[uffer][!] [bufnr]
    315 			Same as ":cbuffer", except the location list for the
    316 			current window is used instead of the quickfix list.
    317 
    318 						*:cgetb* *:cgetbuffer*
    319 :[range]cgetb[uffer] [bufnr]
    320 			Read the error list from the current buffer.  Just
    321 			like ":cbuffer" but don't jump to the first error.
    322 
    323 						*:lgetb* *:lgetbuffer*
    324 :[range]lgetb[uffer] [bufnr]
    325 			Same as ":cgetbuffer", except the location list for
    326 			the current window is used instead of the quickfix
    327 			list.
    328 
    329 						*:cad* *:cadd* *:caddbuffer*
    330 :[range]cad[dbuffer] [bufnr]
    331 			Read the error list from the current buffer and add
    332 			the errors to the current quickfix list.  If a
    333 			quickfix list is not present, then a new list is
    334 			created.  Otherwise, same as ":cbuffer".
    335 
    336 							*:laddb* *:laddbuffer*
    337 :[range]laddb[uffer] [bufnr]
    338 			Same as ":caddbuffer", except the location list for
    339 			the current window is used instead of the quickfix
    340 			list.
    341 
    342 The following commands create or update a quickfix list from an expression:
    343 `:cexpr` creates a list and jumps to its first error, `:cgetexpr` creates a
    344 list without jumping, and `:caddexpr` adds entries to the current list without
    345 changing the cursor position.  The corresponding commands with an "l" prefix
    346 use the location list.
    347 
    348 							*:cex* *:cexpr* *E777*
    349 :cex[pr][!] {expr}	Create a quickfix list using the result of {expr} and
    350 			jump to the first error.
    351 			If {expr} is a String, then each newline terminated
    352 			line in the String is processed using the global value
    353 			of 'errorformat' and the result is added to the
    354 			quickfix list.
    355 			If {expr} is a List, then each String item in the list
    356 			is processed and added to the quickfix list.  Non
    357 			String items in the List are ignored.
    358 			See |:cc| for [!].
    359 			Examples: >
    360 				:cexpr system('grep -n xyz *')
    361 				:cexpr getline(1, '$')
    362 <
    363 							*:lex* *:lexpr*
    364 :lex[pr][!] {expr}	Same as |:cexpr|, except the location list for the
    365 			current window is used instead of the quickfix list.
    366 
    367 							*:cgete* *:cgetexpr*
    368 :cgete[xpr] {expr}	Create a quickfix list using the result of {expr}.
    369 			Just like |:cexpr|, but don't jump to the first error.
    370 
    371 							*:lgete* *:lgetexpr*
    372 :lgete[xpr] {expr}	Same as |:cgetexpr|, except the location list for the
    373 			current window is used instead of the quickfix list.
    374 
    375 							*:cadde* *:caddexpr*
    376 :cadde[xpr] {expr}	Evaluate {expr} and add the resulting lines to the
    377 			current quickfix list.  If a quickfix list is not
    378 			present, then a new list is created.  The current
    379 			cursor position will not be changed.  See |:cexpr| for
    380 			more information.
    381 			Example: >
    382     :g/mypattern/caddexpr expand("%") .. ":" .. line(".") ..  ":" .. getline(".")
    383 <
    384 						*:lad* *:ladd* *:laddexpr*
    385 :lad[dexpr] {expr}	Same as ":caddexpr", except the location list for the
    386 			current window is used instead of the quickfix list.
    387 
    388 							*:cl* *:clist*
    389 :cl[ist] [from] [, [to]]
    390 			List all errors that are valid |quickfix-valid|.
    391 			If numbers [from] and/or [to] are given, the
    392 			respective range of errors is listed.  A negative
    393 			number counts from the last error backwards, -1 being
    394 			the last error.
    395 			The |:filter| command can be used to display only the
    396 			quickfix entries matching a supplied pattern.  The
    397 			pattern is matched against the filename, module name,
    398 			pattern and text of the entry.
    399 			For example, `:filter /\.c:/clist` lists only entries
    400 			whose displayed text contains `.c:`.  See |:filter|.
    401 
    402 :cl[ist] +{count}	List the current and next {count} valid errors.  This
    403 			is similar to ":clist from from+count", where "from"
    404 			is the current error position.
    405 
    406 :cl[ist]! [from] [, [to]]
    407 			List all errors.
    408 
    409 :cl[ist]! +{count}	List the current and next {count} error lines.  This
    410 			is useful to see unrecognized lines after the current
    411 			one.  For example, if ":clist" shows:
    412 	8384 testje.java:252: error: cannot find symbol ~
    413 			Then using ":cl! +3" shows the reason:
    414 	8384 testje.java:252: error: cannot find symbol ~
    415 	8385:   ZexitCode = Fmainx(); ~
    416 	8386:               ^ ~
    417 	8387:   symbol:   method Fmainx() ~
    418 
    419 :lli[st] [from] [, [to]]				*:lli* *:llist*
    420 			Same as ":clist", except the location list for the
    421 			current window is used instead of the quickfix list.
    422 
    423 :lli[st]! [from] [, [to]]
    424 			List all the entries in the location list for the
    425 			current window.
    426 
    427 If you insert or delete lines, mostly the correct error location is still
    428 found because hidden marks are used.  Sometimes, when the mark has been
    429 deleted for some reason, the message "line changed" is shown to warn you that
    430 the error location may not be correct.  If you quit Vim and start again the
    431 marks are lost and the error locations may not be correct anymore.
    432 
    433 Two autocommands are available for running commands before and after a
    434 quickfix command (':make', ':grep' and so on) is executed.  See
    435 |QuickFixCmdPre| and |QuickFixCmdPost| for details.
    436 
    437 						*QuickFixCmdPost-example*
    438 When 'encoding' differs from the locale, the error messages may have a
    439 different encoding from what Vim is using.  To convert the messages you can
    440 use this code: >
    441 	function QfMakeConv()
    442 	   let qflist = getqflist()
    443 	   for i in qflist
    444 	      let i.text = iconv(i.text, "cp936", "utf-8")
    445 	   endfor
    446 	   call setqflist(qflist)
    447 	endfunction
    448 
    449 	au QuickFixCmdPost make call QfMakeConv()
    450 Another option is using 'makeencoding'.
    451 
    452 							*quickfix-title*
    453 Every quickfix and location list has a title.  By default the title is set to
    454 the command that created the list.  The |getqflist()| and |getloclist()|
    455 functions can be used to get the title of a quickfix and a location list
    456 respectively.  The |setqflist()| and |setloclist()| functions can be used to
    457 modify the title of a quickfix and location list respectively.  Examples: >
    458 	call setqflist([], 'a', {'title' : 'Cmd output'})
    459 	echo getqflist({'title' : 1})
    460 	call setloclist(3, [], 'a', {'title' : 'Cmd output'})
    461 	echo getloclist(3, {'title' : 1})
    462 <
    463 							*quickfix-index*
    464 When you jump to a quickfix/location list entry using any of the quickfix
    465 commands (e.g. |:cc|, |:cnext|, |:cprev|, etc.), that entry becomes the
    466 currently selected entry.  The index of the currently selected entry in a
    467 quickfix/location list can be obtained using the getqflist()/getloclist()
    468 functions.  Examples: >
    469 	echo getqflist({'idx' : 0}).idx
    470 	echo getqflist({'id' : qfid, 'idx' : 0}).idx
    471 	echo getloclist(2, {'idx' : 0}).idx
    472 <
    473 For a new quickfix list, the first entry is selected and the index is 1.  Any
    474 entry in any quickfix/location list can be set as the currently selected entry
    475 using the setqflist() function.  Examples: >
    476 	call setqflist([], 'a', {'idx' : 12})
    477 	call setqflist([], 'a', {'id' : qfid, 'idx' : 7})
    478 	call setloclist(1, [], 'a', {'idx' : 7})
    479 <
    480 							*quickfix-size*
    481 You can get the number of entries (size) in a quickfix and a location list
    482 using the |getqflist()| and |getloclist()| functions respectively.  Examples: >
    483 	echo getqflist({'size' : 1})
    484 	echo getloclist(5, {'size' : 1})
    485 <
    486 							*quickfix-context*
    487 Any Vim type can be associated as a context with a quickfix or location list.
    488 The |setqflist()| and the |setloclist()| functions can be used to associate a
    489 context with a quickfix and a location list respectively.  The |getqflist()|
    490 and the |getloclist()| functions can be used to retrieve the context of a
    491 quickfix and a location list respectively.  This is useful for a Vim plugin
    492 dealing with multiple quickfix/location lists.
    493 Examples: >
    494 
    495 	let somectx = {'name' : 'Vim', 'type' : 'Editor'}
    496 	call setqflist([], 'a', {'context' : somectx})
    497 	echo getqflist({'context' : 1})
    498 
    499 	let newctx = ['red', 'green', 'blue']
    500 	call setloclist(2, [], 'a', {'id' : qfid, 'context' : newctx})
    501 	echo getloclist(2, {'id' : qfid, 'context' : 1})
    502 <
    503 							*quickfix-parse*
    504 You can parse a list of lines using 'errorformat' without creating or
    505 modifying a quickfix list using the |getqflist()| function.  Examples: >
    506 	echo getqflist({'lines' : ["F1:10:Line10", "F2:20:Line20"]})
    507 	echo getqflist({'lines' : systemlist('grep -Hn quickfix *')})
    508 This returns a dictionary where the "items" key contains the list of quickfix
    509 entries parsed from lines.  The following shows how to use a custom
    510 'errorformat' to parse the lines without modifying the 'errorformat' option: >
    511 	echo getqflist({'efm' : '%f#%l#%m', 'lines' : ['F1#10#Line']})
    512 <
    513 
    514 To execute a command for entries or files in a list, use:
    515 
    516 				 Quickfix list  Location list
    517 	Each entry		 :cdo		 :ldo
    518 	Each file		 :cfdo		 :lfdo
    519 
    520 Use `:cdo` when a command should run for every valid entry, for example
    521 `:cdo s/old/new/g` to change each matching line.  Use `:cfdo` when it should
    522 run once for each file, for example `:cfdo update` to write each affected file
    523 once.  Add the "l" prefix to use the location list instead.
    524 
    525 The commands below describe these differences in more detail.
    526 
    527 EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST:
    528 							*:cdo*
    529 :cdo[!] {cmd}		Execute {cmd} in each valid entry in the quickfix
    530 			list.  It works like doing this: >
    531 				:cfirst
    532 				:{cmd}
    533 				:cnext
    534 				:{cmd}
    535 				etc.
    536 <			When the current file can't be |abandon|ed and the [!]
    537 			is not present, the command fails.
    538 			When going to the next entry fails execution stops.
    539 			The last buffer (or where an error occurred) becomes
    540 			the current buffer.
    541 			{cmd} can contain '|' to concatenate several commands.
    542 
    543 			Only valid entries in the quickfix list are used.
    544 			A range can be used to select entries, e.g.: >
    545 				:10,$cdo cmd
    546 <			To skip entries 1 to 9.
    547 
    548 			Note: While this command is executing, the Syntax
    549 			autocommand event is disabled by adding it to
    550 			'eventignore'.  This considerably speeds up editing
    551 			each buffer.
    552 			Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|,
    553 			|:ldo|, |:cfdo| and |:lfdo|.
    554 
    555 							*:cfd* *:cfdo*
    556 :cfd[o][!] {cmd}	Execute {cmd} in each file in the quickfix list.
    557 			It works like doing this: >
    558 				:cfirst
    559 				:{cmd}
    560 				:cnfile
    561 				:{cmd}
    562 				etc.
    563 <			Otherwise it works the same as `:cdo`.
    564 
    565 							*:ld* *:ldo*
    566 :ld[o][!] {cmd}		Execute {cmd} in each valid entry in the location list
    567 			for the current window.
    568 			It works like doing this: >
    569 				:lfirst
    570 				:{cmd}
    571 				:lnext
    572 				:{cmd}
    573 				etc.
    574 <			Only valid entries in the location list are used.
    575 			Otherwise it works the same as `:cdo`.
    576 
    577 							*:lfd* *:lfdo*
    578 :lfd[o][!] {cmd}	Execute {cmd} in each file in the location list for
    579 			the current window.
    580 			It works like doing this: >
    581 				:lfirst
    582 				:{cmd}
    583 				:lnfile
    584 				:{cmd}
    585 				etc.
    586 <			Otherwise it works the same as `:ldo`.
    587 
    588 FILTERING A QUICKFIX OR LOCATION LIST:
    589 		    *cfilter-plugin* *:Cfilter* *:Lfilter* *package-cfilter*
    590 If you have too many entries in a quickfix list, you can use the cfilter
    591 plugin to reduce the number of entries.  Load the plugin with: >vim
    592 
    593     packadd cfilter
    594 
    595 Then you can use the following commands to filter a quickfix/location list: >
    596 
    597     :Cfilter[!] /{pat}/
    598     :Lfilter[!] /{pat}/
    599 
    600 The |:Cfilter| command creates a new quickfix list from the entries matching
    601 {pat} in the current quickfix list.  {pat} is a Vim |regular-expression|
    602 pattern.  Both the file name and the text of the entries are matched against
    603 {pat}.  If the optional ! is supplied, then the entries not matching {pat} are
    604 used.  The pattern can be optionally enclosed using one of the following
    605 characters: ', ", /.  If the pattern is empty, then the last used search
    606 pattern is used.
    607 
    608 The |:Lfilter| command does the same as |:Cfilter| but operates on the current
    609 location list.
    610 
    611 The current quickfix/location list is not modified by these commands, so you
    612 can go back to the unfiltered list using the |:colder|/|:lolder| command.
    613 
    614 =============================================================================
    615 2. The error window					*quickfix-window*
    616 
    617 					    *:cope* *:copen* *w:quickfix_title*
    618 :cope[n] [height]	Open a window to show the current list of errors.
    619 
    620 			When [height] is given, the window becomes that high
    621 			(if there is room).  When [height] is omitted the
    622 			window is made ten lines high.
    623 
    624 			If there already is a quickfix window, it will be made
    625 			the current window.  It is not possible to open a
    626 			second quickfix window.  If [height] is given the
    627 			existing window will be resized to it.
    628 
    629 							*quickfix-buffer*
    630 			The window will contain a special buffer, with
    631 			'buftype' equal to "quickfix".  Don't change this!
    632 			The window will have the w:quickfix_title variable set
    633 			which will indicate the command that produced the
    634 			quickfix list.  This can be used to compose a custom
    635 			status line if the value of 'statusline' is adjusted
    636 			properly.  Whenever this buffer is modified by a
    637 			quickfix command or function, the |b:changedtick|
    638 			variable is incremented.  You can get the number of
    639 			this buffer using the getqflist() and getloclist()
    640 			functions by passing the "qfbufnr" item.  For a
    641 			location list, this buffer is wiped out when the
    642 			location list is removed.
    643 
    644 							*:lop* *:lopen*
    645 :lop[en] [height]	Open a window to show the location list for the
    646 			current window.  Works only when the location list for
    647 			the current window is present.  You can have more than
    648 			one location window opened at a time.  Otherwise, it
    649 			acts the same as ":copen".
    650 
    651 							*:ccl* *:cclose*
    652 :ccl[ose]		Close the quickfix window.
    653 
    654 							*:lcl* *:lclose*
    655 :lcl[ose]		Close the window showing the location list for the
    656 			current window.
    657 
    658 							*:cw* *:cwindow*
    659 :cw[indow] [height]	Open the quickfix window when there are recognized
    660 			errors.  If the window is already open and there are
    661 			no recognized errors, close the window.
    662 
    663 			When opening the window and [height] is given, the
    664 			window becomes that high (if there is room).  When
    665 			[height] is omitted the window is made ten lines high.
    666 
    667 							*:lw* *:lwindow*
    668 :lw[indow] [height]	Same as ":cwindow", except use the window showing the
    669 			location list for the current window.
    670 
    671 							*:cbo* *:cbottom*
    672 :cbo[ttom]		Put the cursor in the last line of the quickfix window
    673 			and scroll to make it visible.  This is useful for
    674 			when errors are added by an asynchronous callback.
    675 			Only call it once in a while if there are many
    676 			updates to avoid a lot of redrawing.
    677 
    678 							*:lbo* *:lbottom*
    679 :lbo[ttom]		Same as ":cbottom", except use the window showing the
    680 			location list for the current window.
    681 
    682 Normally the quickfix window is at the bottom of the screen.  If there are
    683 vertical splits, it's at the bottom of the rightmost column of windows.  To
    684 make it always occupy the full width: >
    685 	:botright cwindow
    686 You can move the window around with |window-moving| commands.
    687 For example, to move it to the top: CTRL-W K
    688 The 'winfixheight' option will be set, which means that the window will mostly
    689 keep its height, ignoring 'winheight' and 'equalalways'.  You can change the
    690 height manually (e.g., by dragging the status line above it with the mouse).
    691 
    692 In the quickfix window, each line is one error.  The line number is equal to
    693 the error number.  The current entry is highlighted with the QuickFixLine
    694 highlighting.  You can change it to your liking, e.g.: >
    695 	:hi QuickFixLine ctermbg=Yellow guibg=Yellow
    696 
    697 You can use ":.cc" to jump to the error under the cursor.
    698 Hitting the <Enter> key or double-clicking the mouse on a line has the same
    699 effect.  The file containing the error is opened in the window above the
    700 quickfix window.  If there already is a window for that file, it is used
    701 instead.  If the buffer in the used window has changed, and the error is in
    702 another file, jumping to the error will fail.  You will first have to make
    703 sure the window contains a buffer which can be abandoned.
    704 
    705 When you select a file from the quickfix window, Vim first reuses a window
    706 that already displays the file.  Otherwise it uses a suitable window in the
    707 current tab page, or opens a new one.  The detailed selection rules are:
    708 
    709 1. If a window displaying the selected file is present in the current tabpage
    710    (starting with the window before the quickfix window), then that window is
    711    used.
    712 2. If the above step fails and if 'switchbuf' contains "usetab" and a window
    713    displaying the selected file is present in any one of the tabpages
    714    (starting with the first tabpage) then that window is used.
    715 3. If the above step fails then a window in the current tabpage displaying a
    716    buffer with 'buftype' not set (starting with the window before the quickfix
    717    window) is used.
    718 4. If the above step fails and if 'switchbuf' contains "uselast", then the
    719    previously accessed window is used.
    720 5. If the above step fails then the window before the quickfix window is used.
    721    If there is no previous window, then the window after the quickfix window
    722    is used.
    723 6. If the above step fails, then a new horizontally split window above the
    724    quickfix window is used.
    725 
    726 						*quickfix-winfixbuf*
    727 When 'winfixbuf' is set for the window that would be used to display the
    728 error, jumping to an error in another buffer is not possible in that window.
    729 For a quickfix list Vim then looks for another suitable window, using the
    730 previously accessed window if it does not have 'winfixbuf' set, and otherwise
    731 splits a new window.  For a location list this fails with |E1513|, because a
    732 location list is tied to its window and cannot move to or split off another
    733 one.  Using [!] skips these checks.
    734 
    735 					*CTRL-W_<Enter>* *CTRL-W_<CR>*
    736 You can use CTRL-W <Enter> to open a new window and jump to the error there.
    737 
    738 When the quickfix window has been filled, two autocommand events are
    739 triggered.  First the 'filetype' option is set to "qf", which triggers the
    740 FileType event (also see |qf.vim|).  Then the BufReadPost event is triggered,
    741 using "quickfix" for the buffer name.  This can be used to perform some action
    742 on the listed errors.  Example: >
    743 	au BufReadPost quickfix  setlocal modifiable
    744 		\ | silent exe 'g/^/s//\=line(".") .. " "/'
    745 		\ | setlocal nomodifiable
    746 This prepends the line number to each line.  Note the use of "\=" in the
    747 substitute string of the ":s" command, which is used to evaluate an
    748 expression.
    749 The BufWinEnter event is also triggered, again using "quickfix" for the buffer
    750 name.
    751 
    752 Note: When adding to an existing quickfix list the autocommand are not
    753 triggered.
    754 
    755 Note: Making changes in the quickfix window has no effect on the list of
    756 errors.  'modifiable' is off to avoid making changes.  If you delete or insert
    757 lines anyway, the relation between the text and the error number is messed up.
    758 If you really want to do this, you could write the contents of the quickfix
    759 window to a file and use ":cfile" to have it parsed and used as the new error
    760 list.
    761 
    762 						*location-list-window*
    763 The location list window displays the entries in a location list.  When you
    764 open a location list window, it is created below the current window and
    765 displays the location list for the current window.  The location list window
    766 is similar to the quickfix window, except that you can have more than one
    767 location list window open at a time.  When you use a location list command in
    768 this window, the displayed location list is used.
    769 
    770 When you select a file from the location list window, Vim first uses the
    771 window associated with that location list, when possible.  Otherwise it
    772 reuses a suitable window or opens a new one.  The detailed selection rules
    773 are:
    774 
    775 1. If a non-quickfix window associated with the location list is present in
    776    the current tabpage, then that window is used.
    777 2. If the above step fails and if the file is already opened in another window
    778    in the current tabpage, then that window is used.
    779 3. If the above step fails and 'switchbuf' contains "usetab" and if the file
    780    is opened in a window in any one of the tabpages, then that window is used.
    781 4. If the above step fails then a window in the current tabpage showing a
    782    buffer with 'buftype' not set is used.
    783 5. If the above step fails, then the file is edited in a new window.
    784 
    785 In all of the above cases, if the location list for the selected window is not
    786 yet set, then it is set to the location list displayed in the location list
    787 window.
    788 
    789 							*quickfix-window-ID*
    790 You can use the |getqflist()| and |getloclist()| functions to obtain the
    791 window ID of the quickfix window and location list window respectively (if
    792 present).  Examples: >
    793 	echo getqflist({'winid' : 1}).winid
    794 	echo getloclist(2, {'winid' : 1}).winid
    795 <
    796 							*getqflist-examples*
    797 The |getqflist()| and |getloclist()| functions can be used to get the various
    798 attributes of a quickfix and location list respectively.  Some examples for
    799 using these functions are below:
    800 >
    801     " get the title of the current quickfix list
    802     :echo getqflist({'title' : 0}).title
    803 
    804     " get the identifier of the current quickfix list
    805     :let qfid = getqflist({'id' : 0}).id
    806 
    807     " get the identifier of the fourth quickfix list in the stack
    808     :let qfid = getqflist({'nr' : 4, 'id' : 0}).id
    809 
    810     " check whether a quickfix list with a specific identifier exists
    811     :if getqflist({'id' : qfid}).id == qfid
    812 
    813     " get the index of the current quickfix list in the stack
    814     :let qfnum = getqflist({'nr' : 0}).nr
    815 
    816     " get the items of a quickfix list specified by an identifier
    817     :echo getqflist({'id' : qfid, 'items' : 0}).items
    818 
    819     " get the number of entries in a quickfix list specified by an id
    820     :echo getqflist({'id' : qfid, 'size' : 0}).size
    821 
    822     " get the context of the third quickfix list in the stack
    823     :echo getqflist({'nr' : 3, 'context' : 0}).context
    824 
    825     " get the number of quickfix lists in the stack
    826     :echo getqflist({'nr' : '$'}).nr
    827 
    828     " get the number of times the current quickfix list is changed
    829     :echo getqflist({'changedtick' : 0}).changedtick
    830 
    831     " get the current entry in a quickfix list specified by an identifier
    832     :echo getqflist({'id' : qfid, 'idx' : 0}).idx
    833 
    834     " get all the quickfix list attributes using an identifier
    835     :echo getqflist({'id' : qfid, 'all' : 0})
    836 
    837     " parse text from a List of lines and return a quickfix list
    838     :let myList = ["a.java:10:L10", "b.java:20:L20"]
    839     :echo getqflist({'lines' : myList}).items
    840 
    841     " parse text using a custom 'efm' and return a quickfix list
    842     :echo getqflist({'lines' : ['a.c#10#Line 10'], 'efm':'%f#%l#%m'}).items
    843 
    844     " get the quickfix list window id
    845     :echo getqflist({'winid' : 0}).winid
    846 
    847     " get the quickfix list window buffer number
    848     :echo getqflist({'qfbufnr' : 0}).qfbufnr
    849 
    850     " get the context of the current location list
    851     :echo getloclist(0, {'context' : 0}).context
    852 
    853     " get the location list window id of the third window
    854     :echo getloclist(3, {'winid' : 0}).winid
    855 
    856     " get the location list window buffer number of the third window
    857     :echo getloclist(3, {'qfbufnr' : 0}).qfbufnr
    858 
    859     " get the file window id of a location list window (winnr: 4)
    860     :echo getloclist(4, {'filewinid' : 0}).filewinid
    861 <
    862 							*setqflist-examples*
    863 The |setqflist()| and |setloclist()| functions can be used to set the various
    864 attributes of a quickfix and location list respectively.  Some examples for
    865 using these functions are below:
    866 >
    867     " create an empty quickfix list with a title and a context
    868     :let t = 'Search results'
    869     :let c = {'cmd' : 'grep'}
    870     :call setqflist([], ' ', {'title' : t, 'context' : c})
    871 
    872     " set the title of the current quickfix list
    873     :call setqflist([], 'a', {'title' : 'Mytitle'})
    874 
    875     " change the current entry in the list specified by an identifier
    876     :call setqflist([], 'a', {'id' : qfid, 'idx' : 10})
    877 
    878     " set the context of a quickfix list specified by an identifier
    879     :call setqflist([], 'a', {'id' : qfid, 'context' : {'val' : 100}})
    880 
    881     " create a new quickfix list from a command output
    882     :call setqflist([], ' ', {'lines' : systemlist('grep -Hn main *.c')})
    883 
    884     " parse text using a custom efm and add to a particular quickfix list
    885     :call setqflist([], 'a', {'id' : qfid,
    886 		\ 'lines' : ["a.c#10#L10", "b.c#20#L20"], 'efm':'%f#%l#%m'})
    887 
    888     " add items to the quickfix list specified by an identifier
    889     :let newItems = [{'filename' : 'a.txt', 'lnum' : 10, 'text' : "Apple"},
    890 		    \ {'filename' : 'b.txt', 'lnum' : 20, 'text' : "Orange"}]
    891     :call setqflist([], 'a', {'id' : qfid, 'items' : newItems})
    892 
    893     " empty a quickfix list specified by an identifier
    894     :call setqflist([], 'r', {'id' : qfid, 'items' : []})
    895 
    896     " free all the quickfix lists in the stack
    897     :call setqflist([], 'f')
    898 
    899     " set the title of the fourth quickfix list
    900     :call setqflist([], 'a', {'nr' : 4, 'title' : 'SomeTitle'})
    901 
    902     " create a new quickfix list at the end of the stack
    903     :call setqflist([], ' ', {'nr' : '$',
    904 			\ 'lines' : systemlist('grep -Hn class *.java')})
    905 
    906     " create a new location list from a command output
    907     :call setloclist(0, [], ' ', {'lines' : systemlist('grep -Hn main *.c')})
    908 
    909     " replace the location list entries for the third window
    910     :call setloclist(3, [], 'r', {'items' : newItems})
    911 <
    912 =============================================================================
    913 3. Using more than one list of errors			*quickfix-error-lists*
    914 
    915 So far it has been assumed that there is only one list of errors.  Actually
    916 there can be multiple used lists that are remembered; see 'chistory' and
    917 'lhistory'.
    918 When starting a new list, the previous ones are automatically kept.  Two
    919 commands can be used to access older error lists.  They set one of the
    920 existing error lists as the current one.
    921 
    922 						*:colder* *:col* *E380*
    923 :col[der] [count]	Go to older error list.  When [count] is given, do
    924 			this [count] times.  When already at the oldest error
    925 			list, an error message is given.
    926 
    927 						*:lolder* *:lol*
    928 :lol[der] [count]	Same as `:colder`, except use the location list for
    929 			the current window instead of the quickfix list.
    930 
    931 						*:cnewer* *:cnew* *E381*
    932 :cnew[er] [count]	Go to newer error list.  When [count] is given, do
    933 			this [count] times.  When already at the newest error
    934 			list, an error message is given.
    935 
    936 						*:lnewer* *:lnew*
    937 :lnew[er] [count]	Same as `:cnewer`, except use the location list for
    938 			the current window instead of the quickfix list.
    939 
    940 						*:chistory* *:chi*
    941 :[count]chi[story]	Show the list of error lists.  The current list is
    942 			marked with ">".  The output looks like:
    943 			  error list 1 of 3; 43 errors   :make  ~
    944 			> error list 2 of 3; 0 errors    :helpgrep tag  ~
    945 			  error list 3 of 3; 15 errors   :grep ex_help *.c ~
    946 
    947 			When [count] is given, then the count'th quickfix
    948 			list is made the current list.  Example: >
    949 				" Make the 4th quickfix list current
    950 				:4chistory
    951 <
    952 						*:lhistory* *:lhi*
    953 :[count]lhi[story]	Show the list of location lists, otherwise like
    954 			`:chistory`.
    955 
    956 When adding a new error list, it becomes the current list.
    957 
    958 When ":colder" has been used and ":make" or ":grep" is used to add a new error
    959 list, one newer list is overwritten.  This is especially useful if you are
    960 browsing with ":grep" |grep|.  If you want to keep the more recent error
    961 lists, use ":cnewer 99" first.
    962 
    963 To get the number of lists in the quickfix and location list stack, you can
    964 use the |getqflist()| and |getloclist()| functions respectively with the list
    965 number set to the special value '$'.  Examples: >
    966 	echo getqflist({'nr' : '$'}).nr
    967 	echo getloclist(3, {'nr' : '$'}).nr
    968 To get the number of the current list in the stack: >
    969 	echo getqflist({'nr' : 0}).nr
    970 <
    971 =============================================================================
    972 4. Using :make						*:make_makeprg*
    973 
    974 							*:mak* *:make*
    975 :mak[e][!] [arguments]	1. All relevant |QuickFixCmdPre| autocommands are
    976 			   executed.
    977 			2. If the 'autowrite' option is on, write any changed
    978 			   buffers
    979 			3. An errorfile name is made from 'makeef'.  If
    980 			   'makeef' doesn't contain "##", and a file with this
    981 			   name already exists, it is deleted.
    982 			4. The program given with the 'makeprg' option is
    983 			   started (default "make") with the optional
    984 			   [arguments] and the output is saved in the
    985 			   errorfile (for Unix it is also echoed on the
    986 			   screen).
    987 			5. The errorfile is read using 'errorformat'.
    988 			6. All relevant |QuickFixCmdPost| autocommands are
    989 			   executed.  See example below.
    990 			7. If [!] is not given the first error is jumped to.
    991 			8. The errorfile is deleted.
    992 			9. You can now move through the errors with commands
    993 			   like |:cnext| and |:cprevious|, see above.
    994 			This command does not accept a comment, any "
    995 			characters are considered part of the arguments.
    996 			If the encoding of the program output differs from the
    997 			'encoding' option, you can use the 'makeencoding'
    998 			option to specify the encoding.
    999 
   1000 							*:lmak* *:lmake*
   1001 :lmak[e][!] [arguments]
   1002 			Same as ":make", except the location list for the
   1003 			current window is used instead of the quickfix list.
   1004 
   1005 In short, `:make` runs 'makeprg', reads its output using 'errorformat',
   1006 optionally jumps to the first recognized error, and then removes the temporary
   1007 error file used by the normal `:make` workflow.  If 'shellpipe' is empty, or
   1008 if the program manages its own output file, this cleanup does not apply to
   1009 that program's file.  Use |:cnext| and related commands to move through the
   1010 resulting list.
   1011 
   1012 The ":make" command executes the command given with the 'makeprg' option.
   1013 This is done by passing the command to the shell given with the 'shell'
   1014 option.  This works almost like typing
   1015 
   1016 	":!{makeprg} [arguments] {shellpipe} {errorfile}".
   1017 
   1018 {makeprg} is the string given with the 'makeprg' option.  Any command can be
   1019 used, not just "make".  Characters '%' and '#' are expanded as usual on a
   1020 command-line.  You can use "%<" to insert the current file name without
   1021 extension, or "#<" to insert the alternate file name without extension, for
   1022 example: >
   1023    :set makeprg=make\ #<.o
   1024 
   1025 [arguments] is anything that is typed after ":make".
   1026 {shellpipe} is the 'shellpipe' option.
   1027 {errorfile} is the 'makeef' option, with ## replaced to make it unique.
   1028 
   1029 The placeholder "$*" can be used for the argument list in {makeprg} if the
   1030 command needs some additional characters after its arguments.  The $* is
   1031 replaced then by all arguments.  Example: >
   1032    :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
   1033 or simpler >
   1034    :let &mp = 'latex \\nonstopmode \\input\{$*}'
   1035 "$*" can be given multiple times, for example: >
   1036    :set makeprg=gcc\ -o\ $*\ $*
   1037 
   1038 The 'shellpipe' option defaults to ">" for the Amiga and ">%s 2>&1" for Win32.
   1039 This means that the output of the compiler is saved in a file and not shown on
   1040 the screen directly.  For Unix "| tee" is used.  The compiler output is shown
   1041 on the screen and saved in a file the same time.  Depending on the shell used
   1042 "|& tee" or "2>&1| tee" is the default, so stderr output will be included.
   1043 
   1044 If 'shellpipe' is empty, the {errorfile} part will be omitted.  This is useful
   1045 for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).
   1046 
   1047 
   1048 Using QuickFixCmdPost to fix the encoding ~
   1049 
   1050 It may be that 'encoding' is set to an encoding that differs from the messages
   1051 your build program produces.  This example shows how to fix this after Vim has
   1052 read the error messages: >
   1053 
   1054 	function QfMakeConv()
   1055 	   let qflist = getqflist()
   1056 	   for i in qflist
   1057 	      let i.text = iconv(i.text, "cp936", "utf-8")
   1058 	   endfor
   1059 	   call setqflist(qflist)
   1060 	endfunction
   1061 
   1062 	au QuickFixCmdPost make call QfMakeConv()
   1063 
   1064 (Example by Faque Cheng)
   1065 Another option is using 'makeencoding'.
   1066 
   1067 ==============================================================================
   1068 5. Using :vimgrep and :grep				*grep* *lid*
   1069 
   1070 Vim has two ways to find matches for a pattern: internal and external.  The
   1071 advantage of the internal grep is that it works on all systems and uses the
   1072 powerful Vim search patterns.  An external grep program can be used when the
   1073 Vim grep does not do what you want.
   1074 
   1075 The internal method will be slower, because files are read into memory.  For
   1076 large projects, consider using |:grep| with an external search program.  The
   1077 advantages of the internal method are:
   1078 - Line separators and encoding are automatically recognized, as if a file is
   1079   being edited.
   1080 - Uses Vim search patterns.  Multi-line patterns can be used.
   1081 - When plugins are enabled: compressed and remote files can be searched.
   1082 	|gzip| |netrw|
   1083 
   1084 To be able to do this Vim loads each file as if it is being edited.  When
   1085 there is no match in the file the associated buffer is wiped out again.  The
   1086 'hidden' option is ignored here to avoid running out of memory or file
   1087 descriptors when searching many files.  However, when the |:hide| command
   1088 modifier is used the buffers are kept loaded.  This makes following searches
   1089 in the same files a lot faster.
   1090 
   1091 Note that |:copen| (or |:lopen| for |:lgrep|) may be used to open a buffer
   1092 containing the search results in linked form.  The |:silent| command may be
   1093 used to suppress the default full screen grep output.  The ":grep!" form of
   1094 the |:grep| command doesn't jump to the first match automatically.  These
   1095 commands can be combined to create a NewGrep command: >
   1096 
   1097         command! -nargs=+ NewGrep execute 'silent grep! <args>' | copen 42
   1098 
   1099 
   1100 5.1 Using Vim's internal grep
   1101 
   1102 					*:vim* *:vimgrep* *E682* *E683*
   1103 :vim[grep][!] /{pattern}/[g][j][f] {file} ...
   1104 			Search for {pattern} in the files {file} ... and set
   1105 			the error list to the matches.  Files matching
   1106 			'wildignore' are ignored; files in 'suffixes' are
   1107 			searched last.
   1108 
   1109 			{pattern} is a Vim search pattern.  Instead of
   1110 			enclosing it in / any non-ID character (see
   1111 			'isident') can be used, so long as it does not appear
   1112 			in {pattern}.
   1113 			'ignorecase' applies.  To overrule it put |/\c| in the
   1114 			pattern to ignore case or |/\C| to match case.
   1115 			'smartcase' is not used.
   1116 			If {pattern} is empty (e.g. // is specified), the last
   1117 			used search pattern is used. |last-pattern|
   1118 
   1119 			Flags:
   1120 			'g'  Without the 'g' flag each line is added only
   1121 			     once.  With 'g' every match is added.
   1122 
   1123 			'j'  Without the 'j' flag Vim jumps to the first
   1124 			     match.  With 'j' only the quickfix list is
   1125 			     updated.  With the [!] any changes in the current
   1126 			     buffer are abandoned.
   1127 
   1128 			'f'  When the 'f' flag is specified, fuzzy string
   1129 			     matching is used to find matching lines.  The
   1130 			     characters in {pattern} must appear in order, but
   1131 			     need not be next to each other.  In this case,
   1132 			     {pattern} is treated as a literal string instead
   1133 			     of a regular expression.  See |fuzzy-matching|
   1134 			     for more information about fuzzy matching
   1135 			     strings.
   1136 
   1137 			|QuickFixCmdPre| and |QuickFixCmdPost| are triggered.
   1138 			A file that is opened for matching may use a buffer
   1139 			number, but it is reused if possible to avoid
   1140 			consuming buffer numbers.
   1141 
   1142 :{count}vim[grep] ...
   1143 			When a number is put before the command this is used
   1144 			as the maximum number of matches to find.  Use
   1145 			":1vimgrep pattern file" to find only the first.
   1146 			Useful if you only want to check if there is a match
   1147 			and quit quickly when it's found.
   1148 
   1149 			Every second or so the searched file name is displayed
   1150 			to give you an idea of the progress made.
   1151 			Examples: >
   1152 				:vimgrep /an error/ *.c
   1153 				:vimgrep /\<FileName\>/ *.h include/*
   1154 				:vimgrep /myfunc/ **/*.c
   1155 <			For the use of "**" see |starstar-wildcard|.
   1156 
   1157 :vim[grep][!] {pattern} {file} ...
   1158 			Like above, but instead of enclosing the pattern in a
   1159 			non-ID character use a white space separated pattern.
   1160 			The pattern must start with an ID character.
   1161 			Example: >
   1162 				:vimgrep Error *.c
   1163 <
   1164 							*:lv* *:lvimgrep*
   1165 :lv[imgrep][!] /{pattern}/[g][j][f] {file} ...
   1166 :lv[imgrep][!] {pattern} {file} ...
   1167 			Same as ":vimgrep", except the location list for the
   1168 			current window is used instead of the quickfix list.
   1169 
   1170 						*:vimgrepa* *:vimgrepadd*
   1171 :vimgrepa[dd][!] /{pattern}/[g][j][f] {file} ...
   1172 :vimgrepa[dd][!] {pattern} {file} ...
   1173 			Just like ":vimgrep", but instead of making a new list
   1174 			of errors the matches are appended to the current
   1175 			list.
   1176 
   1177 						*:lvimgrepa* *:lvimgrepadd*
   1178 :lvimgrepa[dd][!] /{pattern}/[g][j][f] {file} ...
   1179 :lvimgrepa[dd][!] {pattern} {file} ...
   1180 			Same as ":vimgrepadd", except the location list for
   1181 			the current window is used instead of the quickfix
   1182 			list.
   1183 
   1184 5.2 External grep
   1185 
   1186 Vim can interface with "grep" and grep-like programs (such as the GNU
   1187 id-utils) in a similar way to its compiler integration (see |:make| above).
   1188 
   1189 [Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where
   1190 "re" stands for Regular Expression.]
   1191 
   1192 							    *:gr* *:grep*
   1193 :gr[ep][!] [arguments]	Just like ":make", but use 'grepprg' instead of
   1194 			'makeprg' and 'grepformat' instead of 'errorformat'.
   1195 			When 'grepprg' is "internal" this works like
   1196 			|:vimgrep|.  Note that the pattern needs to be
   1197 			enclosed in separator characters then.
   1198 			If the encoding of the program output differs from the
   1199 			'encoding' option, you can use the 'makeencoding'
   1200 			option to specify the encoding.
   1201 
   1202 							    *:lgr* *:lgrep*
   1203 :lgr[ep][!] [arguments]	Same as ":grep", except the location list for the
   1204 			current window is used instead of the quickfix list.
   1205 
   1206 							*:grepa* *:grepadd*
   1207 :grepa[dd][!] [arguments]
   1208 			Just like ":grep", but instead of making a new list of
   1209 			errors the matches are appended to the current list.
   1210 			Example: >
   1211 				:call setqflist([])
   1212 				:bufdo grepadd! something %
   1213 <			The first command makes a new error list which is
   1214 			empty.  The second command executes "grepadd" for each
   1215 			listed buffer.  Note the use of ! to avoid that
   1216 			":grepadd" jumps to the first error, which is not
   1217 			allowed with |:bufdo|.
   1218 			An example that uses the argument list and avoids
   1219 			errors for files without matches: >
   1220 				:silent argdo try
   1221 				  \ | grepadd! something %
   1222 				  \ | catch /E480:/
   1223 				  \ | endtry"
   1224 <
   1225 			If the encoding of the program output differs from the
   1226 			'encoding' option, you can use the 'makeencoding'
   1227 			option to specify the encoding.
   1228 
   1229 							*:lgrepa* *:lgrepadd*
   1230 :lgrepa[dd][!] [arguments]
   1231 			Same as ":grepadd", except the location list for the
   1232 			current window is used instead of the quickfix list.
   1233 
   1234 5.3 Setting up external grep
   1235 
   1236 If you have a standard "grep" program installed, the :grep command may work
   1237 well with the defaults.  The syntax is very similar to the standard command: >
   1238 
   1239 	:grep foo *.c
   1240 
   1241 Will search all files with the .c extension for the substring "foo".  The
   1242 arguments to :grep are passed straight to the "grep" program, so you can use
   1243 whatever options your "grep" supports.
   1244 
   1245 By default, :grep invokes grep with the -n option (show file and line
   1246 numbers).  You can change this with the 'grepprg' option.  You will need to
   1247 set 'grepprg' if:
   1248 
   1249 a)	You are using a program that isn't called "grep"
   1250 b)	You have to call grep with a full path
   1251 c)	You want to pass other options automatically (e.g. case insensitive
   1252 	search.)
   1253 
   1254 Once "grep" has executed, Vim parses the results using the 'grepformat'
   1255 option.  This option works in the same way as the 'errorformat' option - see
   1256 that for details.  You may need to change 'grepformat' from the default if
   1257 your grep outputs in a non-standard format, or you are using some other
   1258 program with a special format.
   1259 
   1260 Once the results are parsed, Vim loads the first file containing a match and
   1261 jumps to the appropriate line, in the same way that it jumps to a compiler
   1262 error in |quickfix| mode.  You can then use the |:cnext|, |:clist|, etc.
   1263 commands to see the other matches.
   1264 
   1265 
   1266 5.4 Using :grep with id-utils
   1267 
   1268 You can set up :grep to work with the GNU id-utils like this: >
   1269 
   1270 	:set grepprg=lid\ -Rgrep\ -s
   1271 	:set grepformat=%f:%l:%m
   1272 
   1273 then >
   1274 	:grep (regexp)
   1275 
   1276 works just as you'd expect.
   1277 (provided you remembered to mkid first :)
   1278 
   1279 
   1280 5.5 Browsing source code with :vimgrep or :grep
   1281 
   1282 Using the stack of error lists that Vim keeps, you can browse your files to
   1283 look for functions and the functions they call.  For example, suppose that you
   1284 have to add an argument to the read_file() function.  You enter this command: >
   1285 
   1286 	:vimgrep /\<read_file\>/ *.c
   1287 
   1288 You use ":cn" to go along the list of matches and add the argument.  At one
   1289 place you have to get the new argument from a higher level function msg(), and
   1290 need to change that one too.  Thus you use: >
   1291 
   1292 	:vimgrep /\<msg\>/ *.c
   1293 
   1294 While changing the msg() functions, you find another function that needs to
   1295 get the argument from a higher level.  You can again use ":vimgrep" to find
   1296 these functions.  Once you are finished with one function, you can use >
   1297 
   1298 	:colder
   1299 
   1300 to go back to the previous one.
   1301 
   1302 This works like browsing a tree: ":vimgrep" goes one level deeper, creating a
   1303 list of branches.  ":colder" goes back to the previous level.  You can mix
   1304 this use of ":vimgrep" and "colder" to browse all the locations in a tree-like
   1305 way.  If you do this consistently, you will find all locations without the
   1306 need to write down a "todo" list.
   1307 
   1308 =============================================================================
   1309 6. Selecting a compiler					*compiler-select*
   1310 
   1311 						*:comp* *:compiler* *E666*
   1312 :comp[iler][!] {name}		Set options to work with compiler {name}.
   1313 				Without the "!" options are set for the
   1314 				current buffer.  With "!" global options are
   1315 				set.
   1316 				If you use ":compiler foo" in "file.foo" and
   1317 				then ":compiler! bar" in another buffer, Vim
   1318 				will keep on using "foo" in "file.foo".
   1319 				{not available when compiled without the
   1320 				|+eval| feature}
   1321 
   1322 
   1323 The Vim plugins in the "compiler" directory will set options to use the
   1324 selected compiler.  For `:compiler` local options are set, for `:compiler!`
   1325 global options.
   1326 
   1327 In normal use, select a compiler with `:compiler {name}` and then run |:make|.
   1328 The compiler plugin usually sets 'makeprg' and 'errorformat' so Vim can run
   1329 the compiler and read its messages.  The descriptions below document options
   1330 for particular compiler plugins.
   1331 
   1332 The values set by a compiler plugin can be changed afterwards with |:set| or
   1333 |:setlocal|.  `:compiler {name}` sets options for the current buffer, while
   1334 `:compiler! {name}` sets global options; a buffer-local value takes precedence
   1335 over a global value.
   1336 
   1337 							*current_compiler*
   1338 To support older Vim versions, the plugins always use "current_compiler" and
   1339 not "b:current_compiler".  What the command actually does is the following:
   1340 
   1341 - Delete the "current_compiler" and "b:current_compiler" variables.
   1342 - Define the "CompilerSet" user command.  With "!" it does ":set", without "!"
   1343   it does ":setlocal".
   1344 - Execute ":runtime! compiler/{name}.vim".  The plugins are expected to set
   1345   options with "CompilerSet" and set the "current_compiler" variable to the
   1346   name of the compiler.
   1347 - Delete the "CompilerSet" user command.
   1348 - Set "b:current_compiler" to the value of "current_compiler".
   1349 - Without "!" the old value of "current_compiler" is restored.
   1350 
   1351 
   1352 For writing a compiler plugin, see |write-compiler-plugin|.
   1353 
   1354 Use the |compiler-make| plugin to undo the effect of a compiler plugin.
   1355 
   1356 BIOME				      *compiler-biome* *quickfix-biome*
   1357 
   1358 Biome check lints JavaScript, TypeScript, JSX, TSX, JSON, JSONC, HTML, Vue,
   1359 Svelte, Astro, CSS, GraphQL and GritQL files.
   1360 
   1361 Commonly used compiler options can be added to 'makeprg' by setting the
   1362 b/g:biome_makeprg_params variable.  For example (global default is ""): >
   1363 
   1364   let b:biome_makeprg_params = "--diagnostic-level=error --staged"
   1365 
   1366 
   1367 CPPCHECK			*quickfix-cppcheck* *compiler-cppcheck*
   1368 
   1369 Use g/b:`c_cppcheck_params` to set cppcheck parameters.  The global
   1370 settings by default include
   1371 
   1372 - `--verbose`: Enables verbose output.
   1373 - `--force`: Forces checking of all configurations.
   1374 - `--inline-suppr`: Allows inline suppressions.
   1375 - `--enable=...`: Enables specific checks like warnings, style, performance,
   1376   portability, information, and missing includes.
   1377 - `-j`: Utilizes multiple processors if available, determined by the
   1378   `getconf` command if available (requires omitting the unusedFunction check)
   1379 
   1380 For C++ files (`filetype == 'cpp'`), the `--language=c++` option is added to
   1381 ensure Cppcheck treats the file as C++.
   1382 
   1383 If compile_commands.json is present in the current directory, it is added as a
   1384 `--project` parameter to the command line.  Otherwise, by default the
   1385 directories in &path are passed as include directories.  These can be set by
   1386 g/b:`c_cppcheck_includes` as a list of `-I` flags.  Tim Pope's vim-apathy
   1387 plug-in [0] can expand &path.  To also append the folders in a git repo use >
   1388 
   1389   let &l:path = join(systemlist('git ls-tree -d --name-only -r HEAD'), ',')
   1390 
   1391 [0] https://github.com/tpope/vim-apathy
   1392 
   1393 DOTNET							*compiler-dotnet*
   1394 
   1395 The .NET CLI compiler outputs both errors and warnings by default.  The output
   1396 may be limited to include only errors, by setting the g:dotnet_errors_only
   1397 variable to |v:true|.
   1398 
   1399 The associated project name is included in each error and warning.  To
   1400 suppress the project name, set the g:dotnet_show_project_file variable to
   1401 |v:false|.
   1402 
   1403 Example: limit output to only display errors, and suppress the project name: >
   1404 	let dotnet_errors_only = v:true
   1405 	let dotnet_show_project_file = v:false
   1406 	compiler dotnet
   1407 <
   1408 GCC					*quickfix-gcc*	*compiler-gcc*
   1409 
   1410 There's one variable you can set for the GCC compiler:
   1411 
   1412 g:compiler_gcc_ignore_unmatched_lines
   1413 				Ignore lines that don't match any patterns
   1414 				defined for GCC.  Useful if output from
   1415 				commands run from make are generating false
   1416 				positives.
   1417 
   1418 JAVAC							*compiler-javac*
   1419 
   1420 Commonly used compiler options can be added to 'makeprg' by setting the
   1421 b/g:javac_makeprg_params variable.  For example: >
   1422 
   1423 	let g:javac_makeprg_params = "-Xlint:all -encoding utf-8"
   1424 
   1425 MAVEN							*compiler-maven*
   1426 
   1427 Commonly used compiler options can be added to 'makeprg' by setting the
   1428 b/g:maven_makeprg_params variable.  For example: >
   1429 
   1430 	let g:maven_makeprg_params = "-DskipTests -U -X"
   1431 
   1432 SPOTBUGS						*compiler-spotbugs*
   1433 
   1434 SpotBugs is a static analysis tool that can be used to find bugs in Java.
   1435 It scans the Java bytecode of all classes in the currently open buffer.
   1436 (Therefore, `:compiler! spotbugs` is not supported.)
   1437 
   1438 Commonly used compiler options can be added to 'makeprg' by setting the
   1439 "b:" or "g:spotbugs_makeprg_params" variable.  For example: >vim
   1440 
   1441 	let b:spotbugs_makeprg_params = "-longBugCodes -effort:max -low"
   1442 
   1443 The global default is "-workHard -experimental".
   1444 
   1445 By default, the class files are searched in the directory where the source
   1446 files are placed.  However, typical Java projects use distinct directories
   1447 for source files and class files.  To make both known to SpotBugs, assign
   1448 their paths (distinct and relative to their common root directory) to the
   1449 following properties (using the example of a common Maven project): >vim
   1450 
   1451 	let g:spotbugs_properties = {
   1452 		\ 'sourceDirPath':	['src/main/java'],
   1453 		\ 'classDirPath':	['target/classes'],
   1454 		\ 'testSourceDirPath':	['src/test/java'],
   1455 		\ 'testClassDirPath':	['target/test-classes'],
   1456 	\ }
   1457 
   1458 Note that source and class path entries are expected to come in pairs: define
   1459 both "sourceDirPath" and "classDirPath" when you are considering at least one,
   1460 and apply the same logic to "testSourceDirPath" and "testClassDirPath".
   1461 Note that values for the path keys describe only for SpotBugs where to look
   1462 for files; refer to the documentation for particular compiler plugins for more
   1463 information.
   1464 
   1465 The default pre- and post-compiler actions are provided for Ant, Maven, and
   1466 Javac compiler plugins and can be selected by assigning the name of a compiler
   1467 plugin (`ant`, `maven`, or `javac`) to the "compiler" key: >vim
   1468 
   1469 	let g:spotbugs_properties = {
   1470 		\ 'compiler':		'maven',
   1471 	\ }
   1472 
   1473 This single setting is essentially equivalent to all the settings below, with
   1474 the exception made for the "PreCompilerAction" and "PreCompilerTestAction"
   1475 values: their listed |Funcref|s will obtain no-op implementations whereas the
   1476 implicit Funcrefs of the "compiler" key will obtain the requested defaults if
   1477 available. >vim
   1478 
   1479 	let g:spotbugs_properties = {
   1480 		\ 'PreCompilerAction':
   1481 			\ function('spotbugs#DefaultPreCompilerAction'),
   1482 		\ 'PreCompilerTestAction':
   1483 			\ function('spotbugs#DefaultPreCompilerTestAction'),
   1484 		\ 'PostCompilerAction':
   1485 			\ function('spotbugs#DefaultPostCompilerAction'),
   1486 		\ 'sourceDirPath':	['src/main/java'],
   1487 		\ 'classDirPath':	['target/classes'],
   1488 		\ 'testSourceDirPath':	['src/test/java'],
   1489 		\ 'testClassDirPath':	['target/test-classes'],
   1490 	\ }
   1491 
   1492 With default actions, the compiler of choice will attempt to rebuild the class
   1493 files for the buffer (and possibly for the whole project) as soon as a Java
   1494 syntax file is loaded; then, `spotbugs` will attempt to analyze the quality of
   1495 the compilation unit of the buffer.
   1496 
   1497 Vim commands proficient in 'makeprg' [0] can be composed with default actions.
   1498 Begin by considering which of the supported keys, "DefaultPreCompilerCommand",
   1499 "DefaultPreCompilerTestCommand", or "DefaultPostCompilerCommand", you need to
   1500 write an implementation for, observing that each of these keys corresponds to
   1501 a particular "*Action" key.  Follow it by defining a new function that always
   1502 declares an only parameter of type string and puts to use a command equivalent
   1503 of |:make|, and assigning its |Funcref| to the selected key.  For example:
   1504 >vim
   1505 	function! GenericPostCompilerCommand(arguments) abort
   1506 		execute 'make ' .. a:arguments
   1507 	endfunction
   1508 
   1509 	let g:spotbugs_properties = {
   1510 		\ 'DefaultPostCompilerCommand':
   1511 			\ function('GenericPostCompilerCommand'),
   1512 	\ }
   1513 
   1514 When "PostCompilerAction" is available, "PostCompilerActionExecutor" is also
   1515 supported.  Its value must be a Funcref pointing to a function that always
   1516 declares a single parameter of type string and decides whether |:execute| can
   1517 be dispatched on its argument, containing a pending post-compiler action,
   1518 after ascertaining the current status of |:cc| (or |:ll|): >vim
   1519 
   1520 	function! GenericPostCompilerActionExecutor(action) abort
   1521 		try
   1522 			cc
   1523 		catch /\<E42:/
   1524 			execute a:action
   1525 		endtry
   1526 	endfunction
   1527 
   1528 Complementary, some or all of the available "Pre*Action"s (or "*Pre*Command"s)
   1529 may run `:doautocmd java_spotbugs_post User` in their implementations before
   1530 |:make| (or its equivalent) to define a once-only |ShellCmdPost| `:autocmd`
   1531 that will arrange for "PostCompilerActionExecutor" to be invoked; and then run
   1532 `:doautocmd java_spotbugs_post ShellCmdPost` to consume this event: >vim
   1533 
   1534 	function! GenericPreCompilerCommand(arguments) abort
   1535 		if !exists('g:spotbugs_compilation_done')
   1536 			doautocmd java_spotbugs_post User
   1537 			execute 'make ' .. a:arguments
   1538 			" only run doautocmd when :make was synchronous
   1539 			" see note below
   1540 			doautocmd java_spotbugs_post ShellCmdPost " XXX: (a)
   1541 			let g:spotbugs_compilation_done = 1
   1542 		else
   1543 			cc
   1544 		endif
   1545 	endfunction
   1546 
   1547 	function! GenericPreCompilerTestCommand(arguments) abort
   1548 		if !exists('g:spotbugs_test_compilation_done')
   1549 			doautocmd java_spotbugs_post User
   1550 			execute 'make ' .. a:arguments
   1551 			" only run doautocmd when :make was synchronous
   1552 			" see note below
   1553 			doautocmd java_spotbugs_post ShellCmdPost " XXX: (b)
   1554 			let g:spotbugs_test_compilation_done = 1
   1555 		else
   1556 			cc
   1557 		endif
   1558 	endfunction
   1559 
   1560 	let g:spotbugs_properties = {
   1561 		\ 'compiler':		'maven',
   1562 		\ 'DefaultPreCompilerCommand':
   1563 			\ function('GenericPreCompilerCommand'),
   1564 		\ 'DefaultPreCompilerTestCommand':
   1565 			\ function('GenericPreCompilerTestCommand'),
   1566 		\ 'PostCompilerActionExecutor':
   1567 			\ function('GenericPostCompilerActionExecutor'),
   1568 	\ }
   1569 
   1570 If a command equivalent of `:make` is capable of asynchronous execution and
   1571 consuming `ShellCmdPost` events, `:doautocmd java_spotbugs_post ShellCmdPost`
   1572 must be removed from such "*Action" (or "*Command") implementations (i.e. the
   1573 lines `(a)` and `(b)` in the listed examples) to retain a sequential order for
   1574 non-blocking execution, and any notification (see below) must be suppressed.
   1575 A `ShellCmdPost` `:autocmd` can be associated with any |:augroup| by assigning
   1576 its name to the "augroupForPostCompilerAction" key.
   1577 
   1578 When default actions are not suited to a desired workflow, proceed by writing
   1579 arbitrary functions yourself and matching their Funcrefs to the supported
   1580 keys: "PreCompilerAction", "PreCompilerTestAction", and "PostCompilerAction".
   1581 
   1582 The next example re-implements the default pre-compiler actions for a Maven
   1583 project and requests other default Maven settings with the "compiler" entry:
   1584 >vim
   1585 	function! MavenPreCompilerAction() abort
   1586 		call spotbugs#DeleteClassFiles()
   1587 		compiler maven
   1588 		make compile
   1589 		cc
   1590 	endfunction
   1591 
   1592 	function! MavenPreCompilerTestAction() abort
   1593 		call spotbugs#DeleteClassFiles()
   1594 		compiler maven
   1595 		make test-compile
   1596 		cc
   1597 	endfunction
   1598 
   1599 	let g:spotbugs_properties = {
   1600 		\ 'compiler':		'maven',
   1601 		\ 'PreCompilerAction':
   1602 			\ function('MavenPreCompilerAction'),
   1603 		\ 'PreCompilerTestAction':
   1604 			\ function('MavenPreCompilerTestAction'),
   1605 	\ }
   1606 
   1607 Note that all entered custom settings will take precedence over the matching
   1608 default settings in "g:spotbugs_properties".
   1609 Note that it is necessary to notify the plugin of the result of a pre-compiler
   1610 action before further work can be undertaken.  Using |:cc| after |:make| (or
   1611 |:ll| after |:lmake|) as the last command of an action is the supported means
   1612 of such communication.
   1613 
   1614 Two commands, "SpotBugsRemoveBufferAutocmd" and "SpotBugsDefineBufferAutocmd",
   1615 are provided to toggle actions for buffer-local autocommands.  For example, to
   1616 also run actions on any |BufWritePost| and |SigUSR1| event, add these lines to
   1617 `~/.vim/after/ftplugin/java.vim`: >vim
   1618 
   1619 	if exists(':SpotBugsDefineBufferAutocmd') == 2
   1620 		SpotBugsDefineBufferAutocmd BufWritePost SigUSR1
   1621 	endif
   1622 
   1623 Otherwise, you can turn to `:doautocmd java_spotbugs User` at any time.
   1624 
   1625 The "g:spotbugs_properties" variable is consulted by the Java filetype plugin
   1626 (|ft-java-plugin|) to arrange for the described automation, and, therefore, it
   1627 must be defined before |FileType| events can take place for the buffers loaded
   1628 with Java source files.  It could, for example, be set in a project-local
   1629 |vimrc| loaded by [1].
   1630 
   1631 Both "g:spotbugs_properties" and "b:spotbugs_properties" are recognized and
   1632 must be modifiable (|:unlockvar|).  The "*Command" entries are always treated
   1633 as global functions to be shared among all Java buffers.
   1634 
   1635 The SpotBugs Java library and, by extension, its distributed shell scripts do
   1636 not support in the `-textui` mode listed pathnames with directory filenames
   1637 that contain blank characters [2].  To work around this limitation, consider
   1638 making a symbolic link to such a directory from a directory that does not have
   1639 blank characters in its name and passing this information to SpotBugs: >vim
   1640 
   1641 	let g:spotbugs_alternative_path = {
   1642 		\ 'fromPath':	'path/to/dir_without_blanks',
   1643 		\ 'toPath':	'path/to/dir with blanks',
   1644 	\ }
   1645 
   1646 [0] https://github.com/Konfekt/vim-compilers
   1647 [1] https://github.com/MarcWeber/vim-addon-local-vimrc
   1648 [2] https://github.com/spotbugs/spotbugs/issues/909
   1649 
   1650 GNU MAKE						*compiler-make*
   1651 
   1652 Since the default make program is "make", the compiler plugin for make,
   1653 :compiler make, will reset the 'makeprg' and 'errorformat' option to
   1654 the default values and unlet any variables that may have been set by a
   1655 previous compiler plugin.
   1656 
   1657 MANX AZTEC C				*quickfix-manx* *compiler-manx*
   1658 
   1659 To use Vim with Manx's Aztec C compiler on the Amiga you should do the
   1660 following:
   1661 - Set the CCEDIT environment variable with the command: >
   1662 	mset "CCEDIT=vim -q"
   1663 - Compile with the -qf option.  If the compiler finds any errors, Vim is
   1664   started and the cursor is positioned on the first error.  The error message
   1665   will be displayed on the last line.  You can go to other errors with the
   1666   commands mentioned above.  You can fix the errors and write the file(s).
   1667 - If you exit Vim normally the compiler will re-compile the same file.  If you
   1668   exit with the :cq command, the compiler will terminate.  Do this if you
   1669   cannot fix the error, or if another file needs to be compiled first.
   1670 
   1671 There are some restrictions to the Quickfix mode on the Amiga.  The
   1672 compiler only writes the first 25 errors to the errorfile (Manx's
   1673 documentation does not say how to get more).  If you want to find the others,
   1674 you will have to fix a few errors and exit the editor.  After recompiling,
   1675 up to 25 remaining errors will be found.
   1676 
   1677 If Vim was started from the compiler, the :sh and some :!  commands will not
   1678 work, because Vim is then running in the same process as the compiler and
   1679 stdin (standard input) will not be interactive.
   1680 
   1681 GROFF					*quickfix-groff* *compiler-groff*
   1682 
   1683 The GROFF compiler plugin uses the mom macro set (documented in the groff_mom
   1684 manpage) as input and expects that the output file type extension is passed to
   1685 make, say :make html or :make pdf.
   1686 
   1687 Additional arguments can be passed to groff by setting them in
   1688 `b:groff_compiler_args` or `g:groff_compiler_args`.  The `language` argument
   1689 passed to groff is set using 'spelllang'; it can be overridden by setting
   1690 `b:groff_compiler_lang`.  The default encoding is `UTF-8` and can be changed
   1691 by setting `b:groff_compiler_encoding` or `g:groff_compiler_encoding`.
   1692 
   1693 PANDOC					*quickfix-pandoc* *compiler-pandoc*
   1694 
   1695 The Pandoc compiler plugin expects that an output file type extension is
   1696 passed to make, say :make html or :make pdf.
   1697 
   1698 Additional arguments can be passed to pandoc:
   1699 
   1700 - either by appending them to make, say `:make html --self-contained` .
   1701 - or setting them in `b:pandoc_compiler_args` or `g:pandoc_compiler_args`.
   1702 
   1703 The `--from` argument is an educated guess using the buffer file type;
   1704 it can be overridden by setting `b:pandoc_compiler_from`.
   1705 The `--metadata lang` argument is set using 'spelllang';
   1706 If `--from=markdown` is assumed and no title set in a title header or
   1707 YAML block, then the filename (without extension) is used as the title.
   1708 
   1709 PERL					*quickfix-perl* *compiler-perl*
   1710 
   1711 The Perl compiler plugin doesn't actually compile, but invokes Perl's internal
   1712 syntax checking feature and parses the output for possible errors so you can
   1713 correct them in quick-fix mode.
   1714 
   1715 Warnings are forced regardless of "no warnings" or "$^W = 0" within the file
   1716 being checked.  To disable this set g:perl_compiler_force_warnings to a zero
   1717 value.  For example: >
   1718 	let g:perl_compiler_force_warnings = 0
   1719 
   1720 MYPY TYPE CHECKER					*compiler-mypy*
   1721 
   1722 Commonly used compiler options can be added to 'makeprg' by setting the
   1723 b/g:mypy_makeprg_params variable.  For example: >
   1724 
   1725 	let b:mypy_makeprg_params = "--warn-unused-ignores"
   1726 
   1727 The global default is "--strict --ignore-missing-imports".
   1728 
   1729 PYRIGHT TYPE CHECKER					*compiler-pyright*
   1730 
   1731 Commonly used compiler options can be added to 'makeprg' by setting the
   1732 b/g:pyright_makeprg_params variable.
   1733 
   1734 The global default is "pyright".
   1735 
   1736 TY TYPE CHECKER					*compiler-ty*
   1737 
   1738 Commonly used compiler options and executable can be set by the
   1739 b/g:ty_makeprg variable.  For example: >
   1740 
   1741 	let b:ty_makeprg = "uv run ty"
   1742 
   1743 The global default is "ty --no-progress --color=never".
   1744 
   1745 RUFF LINTER						*compiler-ruff*
   1746 
   1747 Commonly used compiler options can be added to 'makeprg' by setting the
   1748 b/g:ruff_makeprg_params variable.  For example: >
   1749 
   1750 	let b:ruff_makeprg_params = "--max-line-length "..&textwidth
   1751 
   1752 The global default is "--preview".
   1753 
   1754 PYLINT LINTER						*compiler-pylint*
   1755 
   1756 Commonly used compiler options can be added to 'makeprg' by setting the
   1757 b/g:pylint_makeprg_params variable.  For example: >
   1758 
   1759 	let b:pylint_makeprg_params = "--max-line-length "..&textwidth
   1760 
   1761 The global default is "--jobs=0" to use (almost) all cores.
   1762 
   1763 PYUNIT COMPILER						*compiler-pyunit*
   1764 
   1765 This is not actually a compiler, but a unit testing framework for the
   1766 Python language.  It is included into standard Python distribution
   1767 starting from version 2.0.  For older versions, you can get it from
   1768 http://pyunit.sourceforge.net.
   1769 
   1770 When you run your tests with the help of the framework, possible errors
   1771 are parsed by Vim and presented for you in quick-fix mode.
   1772 
   1773 Unfortunately, there is no standard way to run the tests.
   1774 The alltests.py script seems to be used quite often, that's all.
   1775 Useful values for the 'makeprg' options therefore are:
   1776  setlocal makeprg=./alltests.py " Run a testsuite
   1777  setlocal makeprg=python\ %:S   " Run a single testcase
   1778 
   1779 PYTEST COMPILER						*compiler-pytest*
   1780 
   1781 Commonly used compiler options can be added to 'makeprg' by setting the
   1782 b/g:pytest_makeprg_params variable.  For example: >
   1783 
   1784   let b:pytest_makeprg_params = "--verbose --no-summary --disable-warnings"
   1785 
   1786 The global default is "--tb=short --quiet"; Python warnings are suppressed.
   1787 
   1788 TEX COMPILER						*compiler-tex*
   1789 
   1790 Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim)
   1791 uses make command if possible.  If the compiler finds a file named "Makefile"
   1792 or "makefile" in the current directory, it supposes that you want to process
   1793 your *TeX files with make, and the makefile does the right work.  In this case
   1794 compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched.
   1795 If neither "Makefile" nor "makefile" is found, the compiler will not use make.
   1796 You can force the compiler to ignore makefiles by defining
   1797 b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for
   1798 existence only).
   1799 
   1800 If the compiler chose not to use make, it needs to choose a right program for
   1801 processing your input.  If b:tex_flavor or g:tex_flavor (in this precedence)
   1802 variable exists, it defines TeX flavor for :make (actually, this is the name
   1803 of executed command), and if both variables do not exist, it defaults to
   1804 "latex".  For example, while editing chapter2.tex \input-ed from mypaper.tex
   1805 written in AMS-TeX: >
   1806 
   1807 	:let b:tex_flavor = 'amstex'
   1808 	:compiler tex
   1809 <	[editing...] >
   1810 	:make mypaper
   1811 
   1812 Note that you must specify a name of the file to process as an argument (to
   1813 process the right file when editing \input-ed or \include-ed file; portable
   1814 solution for substituting % for no arguments is welcome).  This is not in the
   1815 semantics of make, where you specify a target, not source, but you may specify
   1816 filename without extension ".tex" and mean this as "make filename.dvi or
   1817 filename.pdf or filename.some_result_extension according to compiler".
   1818 
   1819 Note: tex command line syntax is set to usable both for MikTeX (suggestion
   1820 by Srinath Avadhanula) and teTeX (checked by Artem Chuprina).  Suggestion
   1821 from |errorformat-LaTeX| is too complex to keep it working for different
   1822 shells and OSes and also does not allow to use other available TeX options,
   1823 if any.  If your TeX doesn't support "-interaction=nonstopmode", please
   1824 report it with different means to express \nonstopmode from the command line.
   1825 
   1826 TOMBI					*quickfix-toml* *compiler-tombi*
   1827 
   1828 The tombi compiler plugin does not compile.
   1829 
   1830 It runs "tombi lint" and parses diagnostics into the quickfix list.
   1831 
   1832 Color codes are stripped from the linter output to keep |errorformat|
   1833 parsing reliable.  This may require a working "sed" for old versions of the
   1834 tombi linter.
   1835 
   1836 TSC COMPILER						*compiler-tsc*
   1837 
   1838 The executable and compiler options can be added to 'makeprg' by setting the
   1839 b/g:tsc_makeprg variable.  For example: >
   1840 
   1841 	let b:tsc_makeprg = "npx tsc --noEmit"
   1842 
   1843 TYPST COMPILER						*compiler-typst*
   1844 
   1845 Vim includes a compiler plugin for Typst files.  This compiler is enabled
   1846 automatically in Typst buffers by the Typst filetype plugin |ft-typst-plugin|.
   1847 Run |:make| to compile the current Typst file.
   1848 
   1849 							*g:typst_cmd*
   1850 By default Vim will use "typst" as the command to run the Typst compiler.
   1851 This can be changed by setting the |g:typst_cmd| variable: >
   1852 	let g:typst_cmd = "/path/to/other/command"
   1853 
   1854 =============================================================================
   1855 7. The error format					*error-file-format*
   1856 
   1857 					*errorformat* *E372* *E373* *E374*
   1858 						*E375* *E376* *E377* *E378*
   1859 The 'errorformat' option specifies patterns that Vim uses to read compiler
   1860 output.  A pattern can extract the file name, line number, column and message
   1861 from each line.  The first format that matches with an error message is used.
   1862 You can add several formats for different messages your compiler produces, or
   1863 even entries for multiple compilers.  See |efm-entries|.
   1864 
   1865 Each entry in 'errorformat' is a scanf-like string that describes the format.
   1866 First, you need to know how scanf works.  Look in the documentation of your
   1867 C compiler.  Below you find the % items that Vim understands.  Others are
   1868 invalid.
   1869 
   1870 Quick start: Vim already includes formats for many common compilers.  Check
   1871 |errorformats| for an example before writing your own.  If no example matches,
   1872 start with the basic items below and adapt one of the examples as needed.
   1873 
   1874 Special characters in 'errorformat' are comma and backslash.  See
   1875 |efm-entries| for how to deal with them.  Note that a literal "%" is matched
   1876 by "%%", thus it is not escaped with a backslash.
   1877 Keep in mind that in the `:make` and `:grep` output all NUL characters are
   1878 replaced with SOH (0x01).
   1879 
   1880 Note: By default the difference between upper and lowercase is ignored.  If
   1881 you want to match case, add "\C" to the pattern |/\C|.
   1882 
   1883 Vim will read lines of any length, but only the first 4095 bytes are used, the
   1884 rest is ignored.  Items can only be 1023 bytes long.
   1885 
   1886 
   1887 Basic items
   1888 
   1889 	%f		file name (finds a string)
   1890 	%b		buffer number (finds a number)
   1891 	%o		module name (finds a string)
   1892 	%l		line number (finds a number)
   1893 	%e		end line number (finds a number)
   1894 	%c		column number (finds a number representing character
   1895 			column of the error, byte index, a <tab> is 1
   1896 			character column)
   1897 	%v		virtual column number (finds a number representing the
   1898 			screen column of the error, where a <tab> is always 8
   1899 			screen columns regardless of 'tabstop')
   1900 	%k		end column number (finds a number representing
   1901 			the character column of the error, byte index, or a
   1902 			number representing screen end column of the error if
   1903 			it's used with %v)
   1904 	%t		error type (finds a single character):
   1905 			    e - error message
   1906 			    w - warning message
   1907 			    i - info message
   1908 			    n - note message
   1909 			The uppercase letters E, W, I and N are also
   1910 			recognized and have the same meaning.
   1911 	%n		error number (finds a number)
   1912 	%m		error message (finds a string)
   1913 	%r		matches the "rest" of a single-line file message %O/P/Q
   1914 	%p		pointer line (finds a sequence of '-', '.', ' ' or
   1915 			tabs and uses the length for the column number)
   1916 	%*{conv}	any scanf non-assignable conversion
   1917 	%%		the single '%' character
   1918 	%s		search text (finds a string)
   1919 
   1920 The "%f" conversion may depend on the current 'isfname' setting.  "~/" is
   1921 expanded to the home directory and environment variables are expanded.
   1922 
   1923 The "%f" and "%m" conversions have to detect the end of the string.  This
   1924 normally happens by matching following characters and items.  When nothing is
   1925 following the rest of the line is matched.  If "%f" is followed by a '%' or a
   1926 backslash, it will look for a sequence of 'isfname' characters.
   1927 
   1928 On MS-Windows a leading "C:" will be included in "%f", even when using "%f:".
   1929 This means that a file name which is a single alphabetical letter will not be
   1930 detected.
   1931 
   1932 The "%b" conversion is used to parse a buffer number.  This is useful for
   1933 referring to lines in a scratch buffer or a buffer with no name.  If a buffer
   1934 with the matching number doesn't exist, then that line is used as a non-error
   1935 line.
   1936 
   1937 The "%p" conversion is normally followed by a "^".  It's used for compilers
   1938 that output a line like: >
   1939 	    ^
   1940 or >
   1941    ---------^
   1942 to indicate the column of the error.  This is to be used in a multi-line error
   1943 message.  See |errorformat-javac| for a  useful example.
   1944 
   1945 The "%s" conversion specifies the text to search for, to locate the error
   1946 line.  The text is used as a literal string.  The anchors "^" and "$" are
   1947 added to the text to locate the error line exactly matching the search text
   1948 and the text is prefixed with the "\V" atom to make it "very nomagic".  The
   1949 "%s" conversion can be used to locate lines without a line number in the error
   1950 output.  Like the output of the "grep" shell command.
   1951 When the pattern is present the line number will not be used.
   1952 
   1953 The "%o" conversion specifies the module name in quickfix entry.  If present
   1954 it will be used in quickfix error window instead of the filename.  The module
   1955 name is used only for displaying purposes, the file name is used when jumping
   1956 to the file.
   1957 
   1958 Changing directory
   1959 
   1960 The following uppercase conversion characters specify the type of special
   1961 format strings.  At most one of them may be given as a prefix at the beginning
   1962 of a single comma-separated format pattern.
   1963 Some compilers produce messages that consist of directory names that have to
   1964 be prepended to each file name read by %f (example: GNU make).  The following
   1965 codes can be used to scan these directory names; they will be stored in an
   1966 internal directory stack.					*E379*
   1967 	%D		"enter directory" format string; expects a following
   1968 			  %f that finds the directory name
   1969 	%X		"leave directory" format string; expects following %f
   1970 
   1971 When defining an "enter directory" or "leave directory" format, the "%D" or
   1972 "%X" has to be given at the start of that substring.  Vim tracks the directory
   1973 changes and prepends the current directory to each erroneous file found with a
   1974 relative path.  See |quickfix-directory-stack| for details, tips and
   1975 limitations.
   1976 
   1977 
   1978 Multi-line messages				*errorformat-multi-line*
   1979 
   1980 It is possible to read the output of programs that produce multi-line
   1981 messages, i.e. error strings that consume more than one line.  Possible
   1982 prefixes are:
   1983 	%E		start of a multi-line error message
   1984 	%W		start of a multi-line warning message
   1985 	%I		start of a multi-line informational message
   1986 	%N		start of a multi-line note message
   1987 	%A		start of a multi-line message (unspecified type)
   1988 	%>		for next line start with current pattern again |efm-%>|
   1989 	%C		continuation of a multi-line message
   1990 	%Z		end of a multi-line message
   1991 These can be used with '+' and '-', see |efm-ignore| below.
   1992 
   1993 Using "\n" in the pattern won't work to match multi-line messages.
   1994 
   1995 Example: Your compiler happens to write out errors in the following format
   1996 (leading line numbers not being part of the actual output):
   1997 
   1998      1	Error 275 ~
   1999      2	line 42 ~
   2000      3	column 3 ~
   2001      4	' ' expected after '--' ~
   2002 
   2003 The appropriate error format string has to look like this: >
   2004    :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%m
   2005 
   2006 And the |:clist| error message generated for this error is:
   2007 
   2008  1:42 col 3 error 275:  ' ' expected after '--'
   2009 
   2010 Another example: Think of a Python interpreter that produces the following
   2011 error message (line numbers are not part of the actual output):
   2012 
   2013      1	==============================================================
   2014      2	FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest)
   2015      3	--------------------------------------------------------------
   2016      4	Traceback (most recent call last):
   2017      5	  File "unittests/dbfacadeTest.py", line 89, in testFoo
   2018      6	    self.assertEquals(34, dtid)
   2019      7	  File "/usr/lib/python2.2/unittest.py", line 286, in
   2020      8	 failUnlessEqual
   2021      9	    raise self.failureException, \
   2022     10	AssertionError: 34 != 33
   2023     11
   2024     12	--------------------------------------------------------------
   2025     13	Ran 27 tests in 0.063s
   2026 
   2027 Say you want |:clist| write the relevant information of this message only,
   2028 namely:
   2029  5 unittests/dbfacadeTest.py:89:  AssertionError: 34 != 33
   2030 
   2031 Then the error format string could be defined as follows: >
   2032   :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%m
   2033 
   2034 Note that the %C string is given before the %A here: since the expression
   2035 ' %.%#' (which stands for the regular expression ' .*') matches every line
   2036 starting with a space, followed by any characters to the end of the line,
   2037 it also hides line 7 which would trigger a separate error message otherwise.
   2038 Error format strings are always parsed pattern by pattern until the first
   2039 match occurs.
   2040 							*efm-%>*
   2041 The %> item can be used to avoid trying patterns that appear earlier in
   2042 'errorformat'.  This is useful for patterns that match just about anything.
   2043 For example, if the error looks like this:
   2044 
   2045 	Error in line 123 of foo.c: ~
   2046 	unknown variable "i" ~
   2047 
   2048 This can be found with: >
   2049 	:set efm=xxx,%E%>Error in line %l of %f:,%Z%m
   2050 Where "xxx" has a pattern that would also match the second line.
   2051 
   2052 Important: There is no memory of what part of the errorformat matched before;
   2053 every line in the error file gets a complete new run through the error format
   2054 lines.  For example, if one has: >
   2055   setlocal efm=aa,bb,cc,dd,ee
   2056 Where aa, bb, etc. are error format strings.  Each line of the error file will
   2057 be matched to the pattern aa, then bb, then cc, etc.  Just because cc matched
   2058 the previous error line does _not_ mean that dd will be tried first on the
   2059 current line, even if cc and dd are multi-line errorformat strings.
   2060 
   2061 
   2062 
   2063 Separate file name			*errorformat-separate-filename*
   2064 
   2065 These prefixes are useful if the file name is given once and multiple messages
   2066 follow that refer to this file name.
   2067 	%O		single-line file message: overread the matched part
   2068 	%P		single-line file message: push file %f onto the stack
   2069 	%Q		single-line file message: pop the last file from stack
   2070 
   2071 Example: Given a compiler that produces the following error logfile (without
   2072 leading line numbers):
   2073 
   2074      1	[a1.tt]
   2075      2	(1,17)  error: ';' missing
   2076      3	(21,2)  warning: variable 'z' not defined
   2077      4	(67,3)  error: end of file found before string ended
   2078      5
   2079      6	[a2.tt]
   2080      7
   2081      8	[a3.tt]
   2082      9	NEW compiler v1.1
   2083     10	(2,2)   warning: variable 'x' not defined
   2084     11	(67,3)  warning: 's' already defined
   2085 
   2086 This logfile lists several messages for each file enclosed in [...] which are
   2087 properly parsed by an error format like this: >
   2088   :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-Q
   2089 
   2090 A call of |:clist| writes them accordingly with their correct filenames:
   2091 
   2092   2 a1.tt:1 col 17 error: ';' missing
   2093   3 a1.tt:21 col 2 warning: variable 'z' not defined
   2094   4 a1.tt:67 col 3 error: end of file found before string ended
   2095   8 a3.tt:2 col 2 warning: variable 'x' not defined
   2096   9 a3.tt:67 col 3 warning: 's' already defined
   2097 
   2098 Unlike the other prefixes that all match against whole lines, %P, %Q and %O
   2099 can be used to match several patterns in the same line.  Thus it is possible
   2100 to parse even nested files like in the following line:
   2101   {"file1" {"file2" error1} error2 {"file3" error3 {"file4" error4 error5}}}
   2102 The %O then parses over strings that do not contain any push/pop file name
   2103 information.  See |errorformat-LaTeX| for an extended example.
   2104 
   2105 
   2106 Ignoring and using whole messages			*efm-ignore*
   2107 
   2108 The codes '+' or '-' can be combined with the uppercase codes above; in that
   2109 case they have to precede the letter, e.g. '%+A' or '%-G':
   2110 	%-		do not include the matching multi-line in any output
   2111 	%+		include the whole matching line in the %m error string
   2112 
   2113 One prefix is only useful in combination with '+' or '-', namely %G.  It
   2114 parses over lines containing general information like compiler version strings
   2115 or other headers that can be skipped.
   2116 	%-G		ignore this message
   2117 	%+G		general message
   2118 
   2119 
   2120 Pattern matching
   2121 
   2122 The scanf()-like "%*[]" notation is supported for backward-compatibility
   2123 with previous versions of Vim.  However, it is also possible to specify
   2124 (nearly) any Vim supported regular expression in format strings.
   2125 Since meta characters of the regular expression language can be part of
   2126 ordinary matching strings or file names (and therefore internally have to
   2127 be escaped), meta symbols have to be written with leading '%':
   2128 	%\		The single '\' character.  Note that this has to be
   2129 			escaped ("%\\") in ":set errorformat=" definitions.
   2130 	%.		The single '.' character.
   2131 	%#		The single '*'(!) character.
   2132 	%^		The single '^' character.  Note that this is not
   2133 			useful, the pattern already matches start of line.
   2134 	%$		The single '$' character.  Note that this is not
   2135 			useful, the pattern already matches end of line.
   2136 	%[		The single '[' character for a [] character range.
   2137 	%~		The single '~' character.
   2138 When using character classes in expressions (see |/\i| for an overview),
   2139 terms containing the "\+" quantifier can be written in the scanf() "%*"
   2140 notation.  Example: "%\\d%\\+" ("\d\+", "any number") is equivalent to
   2141 "%*\\d".
   2142 Important note: The \(...\) grouping of sub-matches can not be used in format
   2143 specifications because it is reserved for internal conversions.
   2144 
   2145 
   2146 Multiple entries in 'errorformat'			*efm-entries*
   2147 
   2148 To be able to detect output from several compilers, several format patterns
   2149 may be put in 'errorformat', separated by commas (note: blanks after the comma
   2150 are ignored).  The first pattern that has a complete match is used.  If no
   2151 match is found, matching parts from the last one will be used, although the
   2152 file name is removed and the error message is set to the whole message.  If
   2153 there is a pattern that may match output from several compilers (but not in a
   2154 right way), put it after one that is more restrictive.
   2155 
   2156 To include a comma in a pattern precede it with a backslash (you have to type
   2157 two in a ":set" command).  To include a backslash itself give two backslashes
   2158 (you have to type four in a ":set" command).  You also need to put a backslash
   2159 before a space for ":set".
   2160 
   2161 
   2162 Valid matches						*quickfix-valid*
   2163 
   2164 If a line does not completely match one of the entries in 'errorformat', the
   2165 whole line is put in the error message and the entry is marked "not valid"
   2166 These lines are skipped with the ":cn" and ":cp" commands (unless there is
   2167 no valid line at all).  You can use ":cl!" to display all the error messages.
   2168 
   2169 If the error format does not contain a file name Vim cannot switch to the
   2170 correct file.  You will have to do this by hand.
   2171 
   2172 
   2173 Examples
   2174 
   2175 The format of the file from the Amiga Aztec compiler is:
   2176 
   2177 	filename>linenumber:columnnumber:errortype:errornumber:errormessage
   2178 
   2179 	filename	name of the file in which the error was detected
   2180 	linenumber	line number where the error was detected
   2181 	columnnumber	column number where the error was detected
   2182 	errortype	type of the error, normally a single 'E' or 'W'
   2183 	errornumber	number of the error (for lookup in the manual)
   2184 	errormessage	description of the error
   2185 
   2186 This can be matched with this 'errorformat' entry:
   2187 	%f>%l:%c:%t:%n:%m
   2188 
   2189 Some examples for C compilers that produce single-line error outputs:
   2190 %f:%l:\ %t%*[^0123456789]%n:\ %m	for Manx/Aztec C error messages
   2191 					(scanf() doesn't understand [0-9])
   2192 %f\ %l\ %t%*[^0-9]%n:\ %m		for SAS C
   2193 \"%f\"\\,%*[^0-9]%l:\ %m		for generic C compilers
   2194 %f:%l:\ %m				for GCC
   2195 %f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f',
   2196 %Dgmake[%*\\d]:\ Leaving\ directory\ `%f'
   2197 					for GCC with gmake (concat the lines!)
   2198 %f(%l)\ :\ %*[^:]:\ %m			old SCO C compiler (pre-OS5)
   2199 %f(%l)\ :\ %t%*[^0-9]%n:\ %m		idem, with error type and number
   2200 %f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m
   2201 					for GCC, with some extras
   2202 
   2203 Extended examples for the handling of multi-line messages are given below,
   2204 see |errorformat-Jikes| and |errorformat-LaTeX|.
   2205 
   2206 Note the backslash in front of a space and double quote.  It is required for
   2207 the :set command.  There are two backslashes in front of a comma, one for the
   2208 :set command and one to avoid recognizing the comma as a separator of error
   2209 formats.
   2210 
   2211 
   2212 Filtering messages
   2213 
   2214 If you have a compiler that produces error messages that do not fit in the
   2215 format string, you could write a program that translates the error messages
   2216 into this format.  You can use this program with the ":make" command by
   2217 changing the 'makeprg' option.  For example: >
   2218    :set mp=make\ \\\|&\ error_filter
   2219 The backslashes before the pipe character are required to avoid it to be
   2220 recognized as a command separator.  The backslash before each space is
   2221 required for the set command.
   2222 
   2223 =============================================================================
   2224 8. The directory stack				*quickfix-directory-stack*
   2225 
   2226 Quickfix maintains a stack for saving all used directories parsed from the
   2227 make output.  For GNU-make this is rather simple, as it always prints the
   2228 absolute path of all directories it enters and leaves.  Regardless if this is
   2229 done via a 'cd' command in the makefile or with the parameter "-C dir" (change
   2230 to directory before reading the makefile).  It may be useful to use the switch
   2231 "-w" to force GNU-make to print out the working directory before and after
   2232 processing.
   2233 
   2234 This matters only when compiler output contains relative file names from
   2235 multiple directories.  If the output does not clearly report directory
   2236 changes, Vim has to guess and can select the wrong file.  Printing absolute
   2237 directory names and both entering and leaving directory messages avoids this
   2238 problem.
   2239 
   2240 Maintaining the correct directory is more complicated if you don't use
   2241 GNU-make.  AIX-make for example doesn't print any information about its
   2242 working directory.  Then you need to enhance the makefile.  In the makefile of
   2243 LessTif there is a command which echoes "Making {target} in {dir}".  The
   2244 special problem here is that it doesn't print information on leaving the
   2245 directory and that it doesn't print the absolute path.
   2246 
   2247 To solve the problem with relative paths and missing "leave directory"
   2248 messages Vim uses the following algorithm:
   2249 
   2250 1) Check if the given directory is a subdirectory of the current directory.
   2251    If this is true, store it as the current directory.
   2252 2) If it is not a subdir of the current directory, try if this is a
   2253    subdirectory of one of the upper directories.
   2254 3) If the directory still isn't found, it is assumed to be a subdirectory
   2255    of Vim's current directory.
   2256 
   2257 Additionally it is checked for every file, if it really exists in the
   2258 identified directory.  If not, it is searched in all other directories of the
   2259 directory stack (NOT the directory subtree!).  If it is still not found, it is
   2260 assumed that it is in Vim's current directory.
   2261 
   2262 There are limitations in this algorithm.  These examples assume that make just
   2263 prints information about entering a directory in the form "Making all in dir".
   2264 
   2265 1) Assume you have following directories and files:
   2266    ./dir1
   2267    ./dir1/file1.c
   2268    ./file1.c
   2269 
   2270    If make processes the directory "./dir1" before the current directory and
   2271    there is an error in the file "./file1.c", you will end up with the file
   2272    "./dir1/file.c" loaded by Vim.
   2273 
   2274    This can only be solved with a "leave directory" message.
   2275 
   2276 2) Assume you have following directories and files:
   2277    ./dir1
   2278    ./dir1/dir2
   2279    ./dir2
   2280 
   2281    You get the following:
   2282 
   2283    Make output			  Directory interpreted by Vim
   2284    ------------------------	  ----------------------------
   2285    Making all in dir1		  ./dir1
   2286    Making all in dir2		  ./dir1/dir2
   2287    Making all in dir2		  ./dir1/dir2
   2288 
   2289    This can be solved by printing absolute directories in the "enter
   2290    directory" message or by printing "leave directory" messages.
   2291 
   2292 To avoid this problem, ensure to print absolute directory names and "leave
   2293 directory" messages.
   2294 
   2295 Examples for Makefiles:
   2296 
   2297 Unix:
   2298     libs:
   2299 	    for dn in $(LIBDIRS); do				\
   2300 		(cd $$dn; echo "Entering dir '$$(pwd)'"; make); \
   2301 		echo "Leaving dir";				\
   2302 	    done
   2303 
   2304 Add
   2305     %DEntering\ dir\ '%f',%XLeaving\ dir
   2306 to your 'errorformat' to handle the above output.
   2307 
   2308 Note that Vim doesn't check if the directory name in a "leave directory"
   2309 messages is the current directory.  This is why you could just use the message
   2310 "Leaving dir".
   2311 
   2312 =============================================================================
   2313 9. Specific error file formats			*errorformats*
   2314 
   2315 						*errorformat-Jikes*
   2316 Jikes(TM), a source-to-bytecode Java compiler published by IBM Research,
   2317 produces simple multi-line error messages.
   2318 
   2319 An 'errorformat' string matching the produced messages is shown below.
   2320 The following lines can be placed in the user's |vimrc| to overwrite Vim's
   2321 recognized default formats, or see |:set+=| how to install this format
   2322 additionally to the default. >
   2323 
   2324   :set efm=%A%f:%l:%c:%*\\d:%*\\d:,
   2325 	\%C%*\\s%trror:%m,
   2326 	\%+C%*[^:]%trror:%m,
   2327 	\%C%*\\s%tarning:%m,
   2328 	\%C%m
   2329 <
   2330 Jikes(TM) produces a single-line error message when invoked with the option
   2331 "+E", and can be matched with the following: >
   2332 
   2333   :setl efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%m
   2334 <
   2335 						*errorformat-javac*
   2336 This 'errorformat' has been reported to work well for javac, which outputs a
   2337 line with "^" to indicate the column of the error: >
   2338   :setl efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%#
   2339 or: >
   2340   :setl efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%#
   2341 <
   2342 Here is an alternative from Michael F. Lamb for Unix that filters the errors
   2343 first: >
   2344   :setl errorformat=%Z%f:%l:\ %m,%A%p^,%-G%*[^sl]%.%#
   2345   :setl makeprg=javac\ %:S\ 2>&1\ \\\|\ vim-javac-filter
   2346 
   2347 You need to put the following in "vim-javac-filter" somewhere in your path
   2348 (e.g., in ~/bin) and make it executable: >
   2349    #!/bin/sed -f
   2350    /\^$/s/\t/\ /g;/:[0-9]\+:/{h;d};/^[ \t]*\^/G;
   2351 
   2352 In English, that sed script:
   2353 - Changes single tabs to single spaces and
   2354 - Moves the line with the filename, line number, error message to just after
   2355   the pointer line.  That way, the unused error text between doesn't break
   2356   vim's notion of a "multi-line message" and also doesn't force us to include
   2357   it as a "continuation of a multi-line message."
   2358 
   2359 						*errorformat-ant*
   2360 For ant (http://jakarta.apache.org/) the above errorformat has to be modified
   2361 to honour the leading [javac] in front of each javac output line: >
   2362   :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#
   2363 
   2364 The 'errorformat' can also be configured to handle ant together with either
   2365 javac or jikes.  If you're using jikes, you should tell ant to use jikes' +E
   2366 command line switch which forces jikes to generate one-line error messages.
   2367 This is what the second line (of a build.xml file) below does: >
   2368   <property name = "build.compiler"       value = "jikes"/>
   2369   <property name = "build.compiler.emacs" value = "true"/>
   2370 
   2371 The 'errorformat' which handles ant with both javac and jikes is: >
   2372   :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m,
   2373 	   \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#
   2374 <
   2375 						*errorformat-jade*
   2376 parsing jade (see http://www.jclark.com/) errors is simple: >
   2377   :set efm=jade:%f:%l:%c:%t:%m
   2378 <
   2379 						*errorformat-LaTeX*
   2380 The following is an example how an 'errorformat' string can be specified
   2381 for the (La)TeX typesetting system which displays error messages over
   2382 multiple lines.  The output of ":clist" and ":cc" etc. commands displays
   2383 multi-lines in a single line, leading white space is removed.
   2384 It should be easy to adopt the above LaTeX errorformat to any compiler output
   2385 consisting of multi-line errors.
   2386 
   2387 The commands can be placed in a |vimrc| file or some other Vim script file,
   2388 e.g. a script containing LaTeX related stuff which is loaded only when editing
   2389 LaTeX sources.
   2390 Make sure to copy all lines of the example (in the given order), afterwards
   2391 remove the comment lines.  For the '\' notation at the start of some lines see
   2392 |line-continuation|.
   2393 
   2394 		First prepare 'makeprg' such that LaTeX will report multiple
   2395 		errors; do not stop when the first error has occurred: >
   2396  :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
   2397 <
   2398 		Start of multi-line error messages: >
   2399  :set efm=%E!\ LaTeX\ %trror:\ %m,
   2400 	\%E!\ %m,
   2401 <		Start of multi-line warning messages; the first two also
   2402 		include the line number.  Meaning of some regular expressions:
   2403 		  - "%.%#"  (".*")   matches a (possibly empty) string
   2404 		  - "%*\\d" ("\d\+") matches a number >
   2405 	\%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#,
   2406 	\%+W%.%#\ at\ lines\ %l--%*\\d,
   2407 	\%WLaTeX\ %.%#Warning:\ %m,
   2408 <		Possible continuations of error/warning messages; the first
   2409 		one also includes the line number: >
   2410 	\%Cl.%l\ %m,
   2411 	\%+C\ \ %m.,
   2412 	\%+C%.%#-%.%#,
   2413 	\%+C%.%#[]%.%#,
   2414 	\%+C[]%.%#,
   2415 	\%+C%.%#%[{}\\]%.%#,
   2416 	\%+C<%.%#>%.%#,
   2417 	\%C\ \ %m,
   2418 <		Lines that match the following patterns do not contain any
   2419 		important information; do not include them in messages: >
   2420 	\%-GSee\ the\ LaTeX%m,
   2421 	\%-GType\ \ H\ <return>%m,
   2422 	\%-G\ ...%.%#,
   2423 	\%-G%.%#\ (C)\ %.%#,
   2424 	\%-G(see\ the\ transcript%.%#),
   2425 <		Generally exclude any empty or whitespace-only line from
   2426 		being displayed: >
   2427 	\%-G\\s%#,
   2428 <		The LaTeX output log does not specify the names of erroneous
   2429 		source files per line; rather they are given globally,
   2430 		enclosed in parentheses.
   2431 		The following patterns try to match these names and store
   2432 		them in an internal stack.  The patterns possibly scan over
   2433 		the same input line (one after another), the trailing "%r"
   2434 		conversion indicates the "rest" of the line that will be
   2435 		parsed in the next go until the end of line is reached.
   2436 
   2437 		Overread a file name enclosed in '('...')'; do not push it
   2438 		on a stack since the file apparently does not contain any
   2439 		error: >
   2440 	\%+O(%f)%r,
   2441 <		Push a file name onto the stack.  The name is given after '(': >
   2442 	\%+P(%f%r,
   2443 	\%+P\ %\\=(%f%r,
   2444 	\%+P%*[^()](%f%r,
   2445 	\%+P[%\\d%[^()]%#(%f%r,
   2446 <		Pop the last stored file name when a ')' is scanned: >
   2447 	\%+Q)%r,
   2448 	\%+Q%*[^()])%r,
   2449 	\%+Q[%\\d%*[^()])%r
   2450 
   2451 Note that in some cases file names in the LaTeX output log cannot be parsed
   2452 properly.  The parser might have been messed up by unbalanced parentheses
   2453 then.  The above example tries to catch the most relevant cases only.
   2454 You can customize the given setting to suit your own purposes, for example,
   2455 all the annoying "Overfull ..." warnings could be excluded from being
   2456 recognized as an error.
   2457 Alternatively to filtering the LaTeX compiler output, it is also possible
   2458 to directly read the *.log file that is produced by the [La]TeX compiler.
   2459 This contains even more useful information about possible error causes.
   2460 However, to properly parse such a complex file, an external filter should
   2461 be used.  See the description further above how to make such a filter known
   2462 by Vim.
   2463 
   2464 						*errorformat-Perl*
   2465 In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl
   2466 error messages into a format that quickfix mode will understand.  See the
   2467 start of the file about how to use it.  (This script is deprecated, see
   2468 |compiler-perl|.)
   2469 
   2470 =============================================================================
   2471 10. Customizing the quickfix window		*quickfix-window-function*
   2472 
   2473 The default format for the lines displayed in the quickfix window and location
   2474 list window is:
   2475 
   2476     <filename>|<lnum> col <col>|<text>
   2477 
   2478 The values displayed in each line correspond to the "bufnr", "lnum", "col" and
   2479 "text" fields returned by the |getqflist()| function.
   2480 
   2481 For some quickfix/location lists, the displayed text needs to be customized.
   2482 For example, if only the filename is present for a quickfix entry, then the
   2483 two "|" field separator characters after the filename are not needed.  Another
   2484 use case is to customize the path displayed for a filename.  By default, the
   2485 complete path (which may be too long) is displayed for files which are not
   2486 under the current directory tree.  The file path may need to be simplified to
   2487 a common parent directory.
   2488 
   2489 The displayed text can be customized by setting the 'quickfixtextfunc' option
   2490 to a Vim function.  This function will be called with a dict argument and
   2491 should return a List of strings to be displayed in the quickfix or location
   2492 list window.  The dict argument will have the following fields:
   2493 
   2494     quickfix	set to 1 when called for a quickfix list and 0 when called for
   2495 		a location list.
   2496     winid	for a location list, set to the id of the window with the
   2497 		location list.  For a quickfix list, set to 0.  Can be used in
   2498 		getloclist() to get the location list entry.
   2499     id		quickfix or location list identifier
   2500     start_idx	index of the first entry for which text should be returned
   2501     end_idx	index of the last entry for which text should be returned
   2502 
   2503 The function should return a single line of text to display in the quickfix
   2504 window for each entry from start_idx to end_idx.  The function can obtain
   2505 information about the entries using the |getqflist()| function and specifying
   2506 the quickfix list identifier "id".  For a location list, getloclist() function
   2507 can be used with the "winid" argument.  If an empty list is returned, then the
   2508 default format is used to display all the entries.  If an item in the returned
   2509 list is an empty string, then the default format is used to display the
   2510 corresponding entry.
   2511 
   2512 If a quickfix or location list specific customization is needed, then the
   2513 'quickfixtextfunc' attribute of the list can be set using the |setqflist()| or
   2514 |setloclist()| function.  This overrides the global 'quickfixtextfunc' option.
   2515 
   2516 The example below displays the list of old files (|v:oldfiles|) in a quickfix
   2517 window.  As there is no line, column number and error text information
   2518 associated with each entry, the 'quickfixtextfunc' function returns only the
   2519 filename.
   2520 Example: >
   2521     " create a quickfix list from v:oldfiles
   2522     call setqflist([], ' ', {'lines' : v:oldfiles, 'efm' : '%f',
   2523 					\ 'quickfixtextfunc' : 'QfOldFiles'})
   2524     func QfOldFiles(info)
   2525 	" get information about a range of quickfix entries
   2526 	let items = getqflist({'id' : a:info.id, 'items' : 1}).items
   2527 	let l = []
   2528 	for idx in range(a:info.start_idx - 1, a:info.end_idx - 1)
   2529 	    " use the simplified file name
   2530 	  call add(l, fnamemodify(bufname(items[idx].bufnr), ':p:.'))
   2531 	endfor
   2532 	return l
   2533     endfunc
   2534 <
   2535 
   2536  vim:tw=78:ts=8:noet:ft=help:norl: