- quickfix.txt* For Vim version 9.0. Last change: 2023 Jan 18
VIM REFERENCE MANUAL by Bram Moolenaar
This subject is introduced in section |30.1| of the user manual.
1. Using QuickFix commands |quickfix|
2. The error window |quickfix-window|
3. Using more than one list of errors |quickfix-error-lists|
4. Using :make |:make_makeprg|
5. Using :grep |grep|
6. Selecting a compiler |compiler-select|
7. The error format |error-file-format|
8. The directory stack |quickfix-directory-stack|
9. Specific error file formats |errorformats|
10. Customizing the quickfix window |quickfix-window-function|
The quickfix commands are not available when the |+quickfix| feature was
disabled at compile time.
=============================================================================
1. Using QuickFix commands *quickfix* *Quickfix* *E42*
Vim has a special mode to speedup the edit-compile-edit cycle. This is
inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga.
The idea is to save the error messages from the compiler in a file and use Vim
to jump to the errors one by one. You can examine each problem and fix it,
without having to remember all the error messages.
In Vim the quickfix commands are used more generally to find a list of
positions in files. For example, |:vimgrep| finds pattern matches. You can
use the positions in a script with the |getqflist()| function. Thus you can
do a lot more than the edit/compile/fix cycle!
If you have the error messages in a file you can start Vim with: >
vim -q filename
From inside Vim an easy way to run a command and handle the output is with the
|:make| command (see below).
The 'errorformat' option should be set to match the error messages from your
compiler (see |errorformat| below).
*quickfix-ID*
Each quickfix list has a unique identifier called the quickfix ID and this
number will not change within a Vim session. The |getqflist()| function can be
used to get the identifier assigned to a list. There is also a quickfix list
number which may change whenever more than ten lists are added to a quickfix
stack.
*location-list* *E776*
A location list is a window-local quickfix list. You get one after commands
like `:lvimgrep`, `:lgrep`, `:lhelpgrep`, `:lmake`, etc., which create a
location list instead of a quickfix list as the corresponding `:vimgrep`,
`:grep`, `:helpgrep`, `:make` do.
*location-list-file-window*
A location list is associated with a window and each window can have a
separate location list. A location list can be associated with only one
window. The location list is independent of the quickfix list.
When a window with a location list is split, the new window gets a copy of the
location list. When there are no longer any references to a location list,
the location list is destroyed.
*quickfix-changedtick*
Every quickfix and location list has a read-only changedtick variable that
tracks the total number of changes made to the list. Every time the quickfix
list is modified, this count is incremented. This can be used to perform an
action only when the list has changed. The |getqflist()| and |getloclist()|
functions can be used to query the current value of changedtick. You cannot
change the changedtick variable.
The following quickfix commands can be used. The location list commands are
similar to the quickfix commands, replacing the 'c' prefix in the quickfix
command with 'l'.
*E924*
If the current window was closed by an |autocommand| while processing a
location list command, it will be aborted.
*E925* *E926*
If the current quickfix or location list was changed by an |autocommand| while
processing a quickfix or location list command, it will be aborted.
*:cc*
:cc[!] [nr] Display error [nr]. If [nr] is omitted, the same
:[nr]cc[!] error is displayed again. Without [!] this doesn't
work when jumping to another buffer, the current buffer
has been changed, there is the only window for the
buffer and both 'hidden' and 'autowrite' are off.
When jumping to another buffer with [!] any changes to
the current buffer are lost, unless 'hidden' is set or
there is another window for this buffer.
The 'switchbuf' settings are respected when jumping
to a buffer.
When used in the quickfix window the line number can
be used, including "." for the current line and "$"
for the last line.
*:ll*
:ll[!] [nr] Same as ":cc", except the location list for the
:[nr]ll[!] current window is used instead of the quickfix list.
*:cn* *:cne* *:cnext* *E553*
:[count]cn[ext][!] Display the [count] next error in the list that
includes a file name. If there are no file names at
all, go to the [count] next error. See |:cc| for
[!] and 'switchbuf'.
*:lne* *:lnext*
:[count]lne[xt][!] Same as ":cnext", except the location list for the
current window is used instead of the quickfix list.
:[count]cN[ext][!] *:cp* *:cprevious* *:cprev* *:cN* *:cNext*
:[count]cp[revious][!] Display the [count] previous error in the list that
includes a file name. If there are no file names at
all, go to the [count] previous error. See |:cc| for
[!] and 'switchbuf'.
:[count]lN[ext][!] *:lp* *:lprevious* *:lprev* *:lN* *:lNext*
:[count]lp[revious][!] Same as ":cNext" and ":cprevious", except the location
list for the current window is used instead of the
quickfix list.
*:cabo* *:cabove*
:[count]cabo[ve] Go to the [count] error above the current line in the
current buffer. If [count] is omitted, then 1 is
used. If there are no errors, then an error message
is displayed. Assumes that the entries in a quickfix
list are sorted by their buffer number and line
number. If there are multiple errors on the same line,
then only the first entry is used. If [count] exceeds
the number of entries above the current line, then the
first error in the file is selected.
*:lab* *:labove*
:[count]lab[ove] Same as ":cabove", except the location list for the
current window is used instead of the quickfix list.
*:cbel* *:cbelow*
:[count]cbel[ow] Go to the [count] error below the current line in the
current buffer. If [count] is omitted, then 1 is
used. If there are no errors, then an error message
is displayed. Assumes that the entries in a quickfix
list are sorted by their buffer number and line
number. If there are multiple errors on the same
line, then only the first entry is used. If [count]
exceeds the number of entries below the current line,
then the last error in the file is selected.
*:lbel* *:lbelow*
:[count]lbel[ow] Same as ":cbelow", except the location list for the
current window is used instead of the quickfix list.
*:cbe* *:cbefore*
:[count]cbe[fore] Go to the [count] error before the current cursor
position in the current buffer. If [count] is
omitted, then 1 is used. If there are no errors, then
an error message is displayed. Assumes that the
entries in a quickfix list are sorted by their buffer,
line and column numbers. If [count] exceeds the
number of entries before the current position, then
the first error in the file is selected.
*:lbe* *:lbefore*
:[count]lbe[fore] Same as ":cbefore", except the location list for the
current window is used instead of the quickfix list.
*:caf* *:cafter*
:[count]caf[ter] Go to the [count] error after the current cursor
position in the current buffer. If [count] is
omitted, then 1 is used. If there are no errors, then
an error message is displayed. Assumes that the
entries in a quickfix list are sorted by their buffer,
line and column numbers. If [count] exceeds the
number of entries after the current position, then
the last error in the file is selected.
*:laf* *:lafter*
:[count]laf[ter] Same as ":cafter", except the location list for the
current window is used instead of the quickfix list.
*:cnf* *:cnfile*
:[count]cnf[ile][!] Display the first error in the [count] next file in
the list that includes a file name. If there are no
file names at all or if there is no next file, go to
the [count] next error. See |:cc| for [!] and
'switchbuf'.
*:lnf* *:lnfile*
:[count]lnf[ile][!] Same as ":cnfile", except the location list for the
current window is used instead of the quickfix list.
:[count]cNf[ile][!] *:cpf* *:cpfile* *:cNf* *:cNfile*
:[count]cpf[ile][!] Display the last error in the [count] previous file in
the list that includes a file name. If there are no
file names at all or if there is no next file, go to
the [count] previous error. See |:cc| for [!] and
'switchbuf'.
:[count]lNf[ile][!] *:lpf* *:lpfile* *:lNf* *:lNfile*
:[count]lpf[ile][!] Same as ":cNfile" and ":cpfile", except the location
list for the current window is used instead of the
quickfix list.
*:crewind* *:cr*
:cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST
error is displayed. See |:cc|.
*:lrewind* *:lr*
:lr[ewind][!] [nr] Same as ":crewind", except the location list for the
current window is used instead of the quickfix list.
*:cfirst* *:cfir*
:cfir[st][!] [nr] Same as ":crewind".
*:lfirst* *:lfir*
:lfir[st][!] [nr] Same as ":lrewind".
*:clast* *:cla*
:cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST
error is displayed. See |:cc|.
*:llast* *:lla*
:lla[st][!] [nr] Same as ":clast", except the location list for the
current window is used instead of the quickfix list.
*:cq* *:cquit*
:cq[uit][!]
:{N}cq[uit][!]
:cq[uit][!] {N} Quit Vim with error code {N}. {N} defaults to one.
Useful when Vim is called from another program:
e.g., a compiler will not compile the same file again,
`git commit` will abort the committing process, `fc`
(built-in for shells like bash and zsh) will not
execute the command, etc.
{N} can also be zero, in which case Vim exits
normally.
WARNING: All changes in files are lost! Also when the
[!] is not used. It works like ":qall!" |:qall|,
except that Vim returns a non-zero exit code.
*:cf* *:cfi* *:cfile*
:cf[ile][!] [errorfile] Read the error file and jump to the first error.
This is done automatically when Vim is started with
the -q option. You can use this command when you
keep Vim running while compiling. If you give the
name of the errorfile, the 'errorfile' option will
be set to [errorfile]. See |:cc| for [!].
If the encoding of the error file differs from the
'encoding' option, you can use the 'makeencoding'
option to specify the encoding.
*:lf* *:lfi* *:lfile*
:lf[ile][!] [errorfile] Same as ":cfile", except the location list for the
current window is used instead of the quickfix list.
You can not use the -q command-line option to set
the location list.
:cg[etfile] [errorfile] *:cg* *:cgetfile*
Read the error file. Just like ":cfile" but don't
jump to the first error.
If the encoding of the error file differs from the
'encoding' option, you can use the 'makeencoding'
option to specify the encoding.
:lg[etfile] [errorfile] *:lg* *:lge* *:lgetfile*
Same as ":cgetfile", except the location list for the
current window is used instead of the quickfix list.
*:caddf* *:caddfile*
:caddf[ile] [errorfile] Read the error file and add the errors from the
errorfile to the current quickfix list. If a quickfix
list is not present, then a new list is created.
If the encoding of the error file differs from the
'encoding' option, you can use the 'makeencoding'
option to specify the encoding.
*:laddf* *:laddfile*
:laddf[ile] [errorfile] Same as ":caddfile", except the location list for the
current window is used instead of the quickfix list.
*:cb* *:cbuffer* *E681*
:cb[uffer][!] [bufnr] Read the error list from the current buffer.
When [bufnr] is given it must be the number of a
loaded buffer. That buffer will then be used instead
of the current buffer.
A range can be specified for the lines to be used.
Otherwise all lines in the buffer are used.
See |:cc| for [!].
*:lb* *:lbuffer*
:lb[uffer][!] [bufnr] Same as ":cbuffer", except the location list for the
current window is used instead of the quickfix list.
*:cgetb* *:cgetbuffer*
:cgetb[uffer] [bufnr] Read the error list from the current buffer. Just
like ":cbuffer" but don't jump to the first error.
*:lgetb* *:lgetbuffer*
:lgetb[uffer] [bufnr] Same as ":cgetbuffer", except the location list for
the current window is used instead of the quickfix
list.
*:cad* *:cadd* *:caddbuffer*
:cad[dbuffer] [bufnr] Read the error list from the current buffer and add
the errors to the current quickfix list. If a
quickfix list is not present, then a new list is
created. Otherwise, same as ":cbuffer".
*:laddb* *:laddbuffer*
:laddb[uffer] [bufnr] Same as ":caddbuffer", except the location list for
the current window is used instead of the quickfix
list.
*:cex* *:cexpr* *E777*
:cex[pr][!] {expr} Create a quickfix list using the result of {expr} and
jump to the first error.
If {expr} is a String, then each newline terminated
line in the String is processed using the global value
of 'errorformat' and the result is added to the
quickfix list.
If {expr} is a List, then each String item in the list
is processed and added to the quickfix list. Non
String items in the List are ignored.
See |:cc| for [!].
Examples: >
:cexpr system('grep -n xyz *')
:cexpr getline(1, '