Vim documentation: quickfix
main help file
*quickfix.txt* For Vim version 7.0. Last change: 2006 Apr 30
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|
{Vi does not have any of these commands}
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 are using Manx's Aztec C compiler on the Amiga look here for how to use
it with Vim: |quickfix-manx|. If you are using another compiler you should
save the error messages in a file and start Vim with "vim -q filename". An
easy way to do this is with the |:make| command (see below). The
'errorformat' option should be set to match the error messages from your
compiler (see |errorformat| below).
*location-list* *E776*
A location list is similar to a quickfix list and contains a list of positions
in files. 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 references to a location list, the location
list is destroyed.
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'.
*:cc*
:cc[!] [nr] Display error [nr]. If [nr] is omitted, the same
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.
*:ll*
:ll[!] [nr] Same as ":cc", except the location list for the
current window is used instead of the quickfix list.
*:cn* *: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* *: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* *: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.
*: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] Quit Vim with an error code, so that the compiler
will not compile the same file again.
*:cf* *: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 [!].
*:lf* *: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.
:lg[etfile][!] [errorfile] *:lg* *: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.
*: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.
*: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.
*:caddb* *:caddbuffer*
:caddb[uffer] [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 new-line terminated line in the String is
processed using '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, '$')
*:lex* *:lexpr*
:lex[pr][!] {expr} Same as ":cexpr", except the location list for the
current window is used instead of the quickfix list.
*:cgete* *:cgetexpr*
:cgete[xpr][!] {expr} Create a quickfix list using the result of {expr}.
Just like ":cexpr", but don't jump to the first error.
*:lgete* *:lgetexpr*
:lgete[xpr][!] {expr} Same as ":cgetexpr", except the location list for the
current window is used instead of the quickfix list.
*:cad* *:caddexpr*
:cad[dexpr][!] {expr} Evaluate {expr} and add the resulting lines to the
current quickfix list. If a quickfix list is not
present, then a new list is created. The current
cursor position will not be changed. See |:cexpr| for
more information.
Example:
:g/mypattern/caddexpr expand("%") . ":" . line(".") . ":" . getline(".")
*:lad* *:laddexpr*
:lad[dexpr][!] {expr} Same as ":caddexpr", except the location list for the
current window is used instead of the quickfix list.
*:cl* *:clist*
:cl[ist] [from] [, [to]]
List all errors that are valid |quickfix-valid|.
If numbers [from] and/or [to] are given, the respective
range of errors is listed. A negative number counts
from the last error backwards, -1 being the last error.
The 'switchbuf' settings are respected when jumping
to a buffer.
:cl[ist]! [from] [, [to]]
List all errors.
*:lli* *:llist*
:lli[st] [from] [, [to]]
Same as ":clist", except the location list for the
current window is used instead of the quickfix list.
:lli[st]! [from] [, [to]]
List all the entries in the location list for the
current window.
If you insert or delete lines, mostly the correct error location is still
found because hidden marks are used. Sometimes, when the mark has been
deleted for some reason, the message "line changed" is shown to warn you that
the error location may not be correct. If you quit Vim and start again the
marks are lost and the error locations may not be correct anymore.
If vim is built with |+autocmd| support, two autocommands are available for
running commands before and after a quickfix command (':make', ':grep' and so
on) is executed. See |QuickFixCmdPre| and |QuickFixCmdPost| for details.
=============================================================================
2. The error window *quickfix-window*
*:cope* *:copen*
:cope[n] [height] Open a window to show the current list of errors.
When [height] is given, the window becomes that high
(if there is room). Otherwise the window is made ten
lines high.
The window will contain a special buffer, with
'buftype' equal to "quickfix". Don't change this!
If there already is a quickfix window, it will be made
the current window. It is not possible to open a
second quickfix window.
*:lop* *:lopen*
:lop[en] [height] Open a window to show the location list for the
current window. Works only when the location list for
the current window is present. You can have more than
one location window opened at a time. Otherwise, it
acts the same as ":copen".
*:ccl* *:cclose*
:ccl[ose] Close the quickfix window.
*:lcl* *:lclose*
:lcl[ose] Close the window showing the location list for the
current window.
*:cw* *:cwindow*
:cw[indow] [height] Open the quickfix window when there are recognized
errors. If the window is already open and there are
no recognized errors, close the window.
*:lw* *:lwindow*
:lw[indow] [height] Same as ":cwindow", except use the window showing the
location list for the current window.
Normally the quickfix window is at the bottom of the screen. If there are
vertical splits, it's at the bottom of the rightmost column of windows. To
make it always occupy the full width:
:botright cwindow
You can move the window around with |window-moving| commands.
For example, to move it to the top: CTRL-W K
The 'winfixheight' option will be set, which means that the window will mostly
keep its height, ignoring 'winheight' and 'equalalways'. You can change the
height manually (e.g., by dragging the status line above it with the mouse).
In the quickfix window, each line is one error. The line number is equal to
the error number. You can use ":.cc" to jump to the error under the cursor.
Hitting the <Enter> key or double-clicking the mouse on a line has the same
effect. The file containing the error is opened in the window above the
quickfix window. If there already is a window for that file, it is used
instead. If the buffer in the used window has changed, and the error is in
another file, jumping to the error will fail. You will first have to make
sure the window contains a buffer which can be abandoned.
*CTRL-W_<Enter>* *CTRL-W_<CR>*
You can use CTRL-W <Enter> to open a new window and jump to the error there.
When the quickfix window has been filled, two autocommand events are
triggered. First the 'filetype' option is set to "qf", which triggers the
FileType event. Then the BufReadPost event is triggered, using "quickfix" for
the buffer name. This can be used to perform some action on the listed
errors. Example:
au BufReadPost quickfix setlocal modifiable
\ | silent exe 'g/^/s//\=line(".")." "/'
\ | setlocal nomodifiable
This prepends the line number to each line. Note the use of "\=" in the
substitute string of the ":s" command, which is used to evaluate an
expression.
The BufWinEnter event is also triggered, again using "quickfix" for the buffer
name.
Note: Making changes in the quickfix window has no effect on the list of
errors. 'modifiable' is off to avoid making changes. If you delete or insert
lines anyway, the relation between the text and the error number is messed up.
If you really want to do this, you could write the contents of the quickfix
window to a file and use ":cfile" to have it parsed and used as the new error
list.
*location-list-window*
The location list window displays the entries in a location list. When you
open a location list window, it is created below the current window and
displays the location list for the current window. The location list window
is similar to the quickfix window, except that you can have more than one
location list window open at a time. When you use a location list command in
this window, the displayed location list is used.
When you select a file from the location list window, the following steps are
used to find a window to edit the file:
1. If a window with the location list displayed in the location list window is
present, then the file is opened in that window.
2. If the above step fails and if the file is already opened in another
window, then that window is used.
3. If the above step fails then an existing window showing a buffer with
'buftype' not set is used.
4. If the above step fails, then the file is edited in a new window.
In all of the above cases, if the location list for the selected window is not
yet set, then it is set to the location list displayed in the location list
window.
=============================================================================
3. Using more than one list of errors *quickfix-error-lists*
So far has been assumed that there is only one list of errors. Actually the
ten last used lists are remembered. When starting a new list, the previous
ones are automatically kept. Two commands can be used to access older error
lists. They set one of the existing error lists as the current one.
*:colder* *:col* *E380*
:col[der] [count] Go to older error list. When [count] is given, do
this [count] times. When already at the oldest error
list, an error message is given.
*:lolder* *:lol*
:lol[der] [count] Same as ":colder", except use the location list for
the current window instead of the quickfix list.
*:cnewer* *:cnew* *E381*
:cnew[er] [count] Go to newer error list. When [count] is given, do
this [count] times. When already at the newest error
list, an error message is given.
*:lnewer* *:lnew*
:lnew[er] [count] Same as ":cnewer", except use the location list for
the current window instead of the quickfix list.
When adding a new error list, it becomes the current list.
When ":colder" has been used and ":make" or ":grep" is used to add a new error
list, one newer list is overwritten. This is especially useful if you are
browsing with ":grep" |grep|. If you want to keep the more recent error
lists, use ":cnewer 99" first.
=============================================================================
4. Using :make *:make_makeprg*
*:mak* *:make*
:mak[e][!] [arguments] 1. If vim was built with |+autocmd|, all relevant
|QuickFixCmdPre| autocommands are executed.
2. If the 'autowrite' option is on, write any changed
buffers
3. An errorfile name is made from 'makeef'. If
'makeef' doesn't contain "##", and a file with this
name already exists, it is deleted.
4. The program given with the 'makeprg' option is
started (default "make") with the optional
[arguments] and the output is saved in the
errorfile (for Unix it is also echoed on the
screen).
5. The errorfile is read using 'errorformat'.
6. If [!] is not given the first error is jumped to.
7. The errorfile is deleted.
8. If vim was built with |+autocmd|, all relevant
|QuickFixCmdPost| autocommands are executed.
9. You can now move through the errors with commands
like |:cnext| and |:cprevious|, see above.
This command does not accept a comment, any "
characters are considered part of the arguments.
*:lmak* *:lmake*
:lmak[e][!] [arguments]
Same as ":make", except the location list for the
current window is used instead of the quickfix list.
The ":make" command executes the command given with the 'makeprg' option.
This is done by passing the command to the shell given with the 'shell'
option. This works almost like typing
":!{makeprg} [arguments] {shellpipe} {errorfile}".
{makeprg} is the string given with the 'makeprg' option. Any command can be
used, not just "make". Characters '%' and '#' are expanded as usual on a
command-line. You can use "%<" to insert the current file name without
extension, or "#<" to insert the alternate file name without extension, for
example:
:set makeprg=make\ #<.o
[arguments] is anything that is typed after ":make".
{shellpipe} is the 'shellpipe' option.
{errorfile} is the 'makeef' option, with ## replaced to make it unique.
The placeholder "$*" can be used for the argument list in {makeprog} if the
command needs some additional characters after its arguments. The $* is
replaced then by all arguments. Example:
:set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
or simpler
:let &mp = 'latex \\nonstopmode \\input\{$*}'
"$*" can be given multiple times, for example:
:set makeprg=gcc\ -o\ $*\ $*
The 'shellpipe' option defaults to ">" for the Amiga, MS-DOS and Win32. This
means that the output of the compiler is saved in a file and not shown on the
screen directly. For Unix "| tee" is used. The compiler output is shown on
the screen and saved in a file the same time. Depending on the shell used
"|& tee" or "2>&1| tee" is the default, so stderr output will be included.
If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful
for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).
==============================================================================
5. Using :vimgrep and :grep *grep* *lid*
Vim has two ways to find matches for a pattern: Internal and external. The
advantage of the internal grep is that it works on all systems and uses the
powerful Vim search patterns. An external grep program can be used when the
Vim grep does not do what you want.
The internal method will be slower, because files are read into memory. The
advantages are:
- Line separators and encoding are automatically recognized, as if a file is
being edited.
- Uses Vim search patterns. Multi-line patterns can be used.
- When plugins are enabled: compressed and remote files can be searched.
|gzip| |netrw|
To be able to do this Vim loads each file as if it is being edited. When
there is no match in the file the associated buffer is wiped out again. The
'hidden' option is ignored here to avoid running out of memory or file
descriptors when searching many files. However, when the |:hide| command
modifier is used the buffers are kept loaded. This makes following searches
in the same files a lot faster.
5.1 using Vim's internal grep
*:vim* *:vimgrep* *E682* *E683*
:vim[grep][!] /{pattern}/[g][j] {file} ...
Search for {pattern} in the files {file} ... and set
the error list to the matches.
Without the 'g' flag each line is added only once.
With 'g' every match is added.
{pattern} is a Vim search pattern. Instead of
enclosing it in / any non-ID character (see
|'isident'|) can be used, so long as it does not
appear in {pattern}.
'ignorecase' applies. To overrule it put |/\c| in the
pattern to ignore case or |/\C| to match case.
'smartcase' is not used.
When a number is put before the command this is used
as the maximum number of matches to find. Use
":1vimgrep pattern file" to find only the first.
Useful if you only want to check if there is a match
and quit quickly when it's found.
Without the 'j' flag Vim jumps to the first match.
With 'j' only the quickfix list is updated.
With the [!] any changes in the current buffer are
abandoned.
Every second or so the searched file name is displayed
to give you an idea of the progress made.
Examples:
:vimgrep /an error/ *.c
:vimgrep /\<FileName\>/ *.h include/*
:vimgrep /myfunc/ **/*.c
For the use of "**" see |starstar-wildcard|.
:vim[grep][!] {pattern} {file} ...
Like above, but instead of enclosing the pattern in a
non-ID character use a white-separated pattern. The
pattern must start with an ID character.
Example:
:vimgrep Error *.c
*:lv* *:lvimgrep*
:lv[imgrep][!] /{pattern}/[g][j] {file} ...
:lv[imgrep][!] {pattern} {file} ...
Same as ":vimgrep", except the location list for the
current window is used instead of the quickfix list.
*:vimgrepa* *:vimgrepadd*
:vimgrepa[dd][!] /{pattern}/[g][j] {file} ...
:vimgrepa[dd][!] {pattern} {file} ...
Just like ":vimgrep", but instead of making a new list
of errors the matches are appended to the current
list.
*:lvimgrepa* *:lvimgrepadd*
:lvimgrepa[dd][!] /{pattern}/[g][j] {file} ...
:lvimgrepa[dd][!] {pattern} {file} ...
Same as ":vimgrepadd", except the location list for
the current window is used instead of the quickfix
list.
5.2 External grep
Vim can interface with "grep" and grep-like programs (such as the GNU
id-utils) in a similar way to its compiler integration (see |:make| above).
[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where
"re" stands for Regular Expression.]
*:gr* *:grep*
:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of
'makeprg' and 'grepformat' instead of 'errorformat'.
When 'grepprg' is "internal" this works like
|:vimgrep|. Note that the pattern needs to be
enclosed in separator characters then.
*:lgr* *:lgrep*
:lgr[ep][!] [arguments] Same as ":grep", except the location list for the
current window is used instead of the quickfix list.
*:grepa* *:grepadd*
:grepa[dd][!] [arguments]
Just like ":grep", but instead of making a new list of
errors the matches are appended to the current list.
Example:
:grep nothing %
:bufdo grepadd! something %
The first command makes a new error list which is
empty. The second command executes "grepadd" for each
listed buffer. Note the use of ! to avoid that
":grepadd" jumps to the first error, which is not
allowed with |:bufdo|.
*:lgrepa* *:lgrepadd*
:lgrepa[dd][!] [arguments]
Same as ":grepadd", except the location list for the
current window is used instead of the quickfix list.
5.3 Setting up external grep
If you have a standard "grep" program installed, the :grep command may work
well with the defaults. The syntax is very similar to the standard command:
:grep foo *.c
Will search all files with the .c extension for the substring "foo". The
arguments to :grep are passed straight to the "grep" program, so you can use
whatever options your "grep" supports.
By default, :grep invokes grep with the -n option (show file and line
numbers). You can change this with the 'grepprg' option. You will need to set
'grepprg' if:
a) You are using a program that isn't called "grep"
b) You have to call grep with a full path
c) You want to pass other options automatically (e.g. case insensitive
search.)
Once "grep" has executed, Vim parses the results using the 'grepformat'
option. This option works in the same way as the 'errorformat' option - see
that for details. You may need to change 'grepformat' from the default if
your grep outputs in a non-standard format, or you are using some other
program with a special format.
Once the results are parsed, Vim loads the first file containing a match and
jumps to the appropriate line, in the same way that it jumps to a compiler
error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc.
commands to see the other matches.
5.4 Using :grep with id-utils
You can set up :grep to work with the GNU id-utils like this:
:set grepprg=lid\ -Rgrep\ -s
:set grepformat=%f:%l:%m
then
:grep (regexp)
works just as you'd expect.
(provided you remembered to mkid first :)
5.5 Browsing source code with :vimgrep or :grep
Using the stack of error lists that Vim keeps, you can browse your files to
look for functions and the functions they call. For example, suppose that you
have to add an argument to the read_file() function. You enter this command:
:vimgrep /\<read_file\>/ *.c
You use ":cn" to go along the list of matches and add the argument. At one
place you have to get the new argument from a higher level function msg(), and
need to change that one too. Thus you use:
:vimgrep /\<msg\>/ *.c
While changing the msg() functions, you find another function that needs to
get the argument from a higher level. You can again use ":vimgrep" to find
these functions. Once you are finished with one function, you can use
:colder
to go back to the previous one.
This works like browsing a tree: ":vimgrep" goes one level deeper, creating a
list of branches. ":colder" goes back to the previous level. You can mix
this use of ":vimgrep" and "colder" to browse all the locations in a tree-like
way. If you do this consistently, you will find all locations without the
need to write down a "todo" list.
=============================================================================
6. Selecting a compiler *compiler-select*
*:comp* *:compiler* *E666*
:comp[iler][!] {name} Set options to work with compiler {name}.
Without the "!" options are set for the
current buffer. With "!" global options are
set.
If you use ":compiler foo" in "file.foo" and
then ":compiler! bar" in another buffer, Vim
will keep on using "foo" in "file.foo".
{not available when compiled without the
|+eval| feature}
The Vim plugins in the "compiler" directory will set options to use the
selected compiler. For ":compiler" local options are set, for ":compiler!"
global options.
*current_compiler*
To support older Vim versions, the plugins always use "current_compiler" and
not "b:current_compiler". What the command actually does is the following:
- Delete the "current_compiler" and "b:current_compiler" variables.
- Define the "CompilerSet" user command. With "!" it does ":set", without "!"
it does ":setlocal".
- Execute ":runtime! compiler/{name}.vim". The plugins are expected to set
options with "CompilerSet" and set the "current_compiler" variable to the
name of the compiler.
- Delete the "CompilerSet" user command.
- Set "b:current_compiler" to the value of "current_compiler".
- Without "!" the old value of "current_compiler" is restored.
For writing a compiler plugin, see |write-compiler-plugin|.
MANX AZTEC C *quickfix-manx* *compiler-manx*
To use Vim with Manx's Aztec C compiler on the Amiga you should do the
following:
- Set the CCEDIT environment variable with the command:
mset "CCEDIT=vim -q"
- Compile with the -qf option. If the compiler finds any errors, Vim is
started and the cursor is positioned on the first error. The error message
will be displayed on the last line. You can go to other errors with the
commands mentioned above. You can fix the errors and write the file(s).
- If you exit Vim normally the compiler will re-compile the same file. If you
exit with the :cq command, the compiler will terminate. Do this if you
cannot fix the error, or if a. For Unix "| tee" is used. The compiler output is shown on
the screen and saved in a file the same time. Depending on the shell used
"|& tee" or "2>&1| tee" is the default, so stderr output will be included.
If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful
for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).
==============================================================================
5. Using :vimgrep and :grep *grep* *lid*
Vim has two ways to find matches for a pattern: Internal and external. The
advantage of the internal grep is that it works on all systems and uses the
powerful Vim search patterns. An external grep program can be used when the
Vim grep does not do what you want.
The internal method will be slower, because files are read into memory. The
advantages are:
- Line separators and encoding are automatically recognized, as if a file is
being edited.
- Uses Vim search patterns. Multi-line patterns can be used.
- When plugins are enabled: compressed and remote files can be searched.
|gzip| |netrw|
To be able to do this Vim loads each file as if it is being edited. When
there is no match in the file the associated buffer is wiped out again. The
'hidden' option is ignored here to avoid running out of memory or file
descriptors when searching many files. However, when the |:hide| command
modifier is used the buffers are kept loaded. This makes following searches
in the same files a lot faster.
5.1 using Vim's internal grep
*:vim* *:vimgrep* *E682* *E683*
:vim[grep][!] /{pattern}/[g][j] {file} ...
Search for {pattern} in the files {file} ... and set
the error list to the matches.
Without the 'g' flag each line is added only once.
With 'g' every match is added.
{pattern} is a Vim search pattern. Instead of
enclosing it in / any non-ID character (see
|'isident'|) can be used, so long as it does not
appear in {pattern}.
'ignorecase' applies. To overrule it put |/\c| in the
pattern to ignore case or |/\C| to match case.
'smartcase' is not used.
When a number is put before the command this is used
as the maximum number of matches to find. Use
":1vimgrep pattern file" to find only the first.
Useful if you only want to check if there is a match
and quit quickly when it's found.
Without the 'j' flag Vim jumps to the first match.
With 'j' only the quickfix list is updated.
With the [!] any changes in the current buffer are
abandoned.
Every second or so the searched file name is displayed
to give you an idea of the progress made.
Examples:
:vimgrep /an error/ *.c
:vimgrep /\<FileName\>/ *.h include/*
:vimgrep /myfunc/ **/*.c
For the use of "**" see |starstar-wildcard|.
:vim[grep][!] {pattern} {file} ...
Like above, but instead of enclosing the pattern in a
non-ID character use a white-separated pattern. The
pattern must start with an ID character.
Example:
:vimgrep Error *.c
*:lv* *:lvimgrep*
:lv[imgrep][!] /{pattern}/[g][j] {file} ...
:lv[imgrep][!] {pattern} {file} ...
Same as ":vimgrep", except the location list for the
current window is used instead of the quickfix list.
*:vimgrepa* *:vimgrepadd*
:vimgrepa[dd][!] /{pattern}/[g][j] {file} ...
:vimgrepa[dd][!] {pattern} {file} ...
Just like ":vimgrep", but instead of making a new list
of errors the matches are appended to the current
list.
*:lvimgrepa* *:lvimgrepadd*
:lvimgrepa[dd][!] /{pattern}/[g][j] {file} ...
:lvimgrepa[dd][!] {pattern} {file} ...
Same as ":vimgrepadd", except the location list for
the current window is used instead of the quickfix
list.
5.2 External grep
Vim can interface with "grep" and grep-like programs (such as the GNU
id-utils) in a similar way to its compiler integration (see |:make| above).
[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where
"re" stands for Regular Expression.]
*:gr* *:grep*
:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of
'makeprg' and 'grepformat' instead of 'errorformat'.
When 'grepprg' is "internal" this works like
|:vimgrep|. Note that the pattern needs to be
enclosed in separator characters then.
*:lgr* *:lgrep*
:lgr[ep][!] [arguments] Same as ":grep", except the location list for the
current window is used instead of the quickfix list.
*:grepa* *:grepadd*
:grepa[dd][!] [arguments]
Just like ":grep", but instead of making a new list of
errors the matches are appended to the current list.
Example:
:grep nothing %
:bufdo grepadd! something %
The first command makes a new error list which is
empty. The second command executes "grepadd" for each
listed buffer. Note the use of ! to avoid that
":grepadd" jumps to the first error, which is not
allowed with |:bufdo|.
*:lgrepa* *:lgrepadd*
:lgrepa[dd][!] [arguments]
Same as ":grepadd", except the location list for the
current window is used instead of the quickfix list.
5.3 Setting up external grep
If you have a standard "grep" program installed, the :grep command may work
well with the defaults. The syntax is very similar to the standard command:
:grep foo *.c
Will search all files with the .c extension for the substring "foo". The
arguments to :grep are passed straight to the "grep" program, so you can use
whatever options your "grep" supports.
By default, :grep invokes grep with the -n option (show file and line
numbers). You can change this with the 'grepprg' option. You will need to set
'grepprg' if:
a) You are using a program that isn't called "grep"
b) You have to call grep with a full path
c) You want to pass other options automatically (e.g. case insensitive
search.)
Once "grep" has executed, Vim parses the results using the 'grepformat'
option. This option works in the same way as the 'errorformat' option - see
that for details. You may need to change 'grepformat' from the default if
your grep outputs in a non-standard format, or you are using some other
program with a special format.
Once the results are parsed, Vim loads the first file containing a match and
jumps to the appropriate line, in the same way that it jumps to a compiler
error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc.
commands to see the other matches.
5.4 Using :grep with id-utils
You can set up :grep to work with the GNU id-utils like this:
:set grepprg=lid\ -Rgrep\ -s
:set grepformat=%f:%l:%m
then
:grep (regexp)
works just as you'd expect.
(provided you remembered to mkid first :)
5.5 Browsing source code with :vimgrep or :grep
Using the stack of error lists that Vim keeps, you can browse your files to
look for functions and the functions they call. For example, suppose that you
have to add an argument to the read_file() function. You enter this command:
:vimgrep /\<read_file\>/ *.c
You use ":cn" to go along the list of matches and add the argument. At one
place you have to get the new argument from a higher level function msg(), and
need to change that one too. Thus you use:
:vimgrep /\<msg\>/ *.c
While changing the msg() functions, you find another function that needs to
get the argument from a higher level. You can again use ":vimgrep" to find
these functions. Once you are finished with one function, you can use
:colder
to go back to the previous one.
This works like browsing a tree: ":vimgrep" goes one level deeper, creating a
list of branches. ":colder" goes back to the previous level. You can mix
this use of ":vimgrep" and "colder" to browse all the locations in a tree-like
way. If you do this consistently, you will find all locations without the
need to write down a "todo" list.
=============================================================================
6. Selecting a compiler *compiler-select*
*:comp* *:compiler* *E666*
:comp[iler][!] {name} Set options to work with compiler {name}.
Without the "!" options are set for the
current buffer. With "!" global options are
set.
If you use ":compiler foo" in "file.foo" and
then ":compiler! bar" in another buffer, Vim
will keep on using "foo" in "file.foo".
{not available when compiled without the
|+eval| feature}
The Vim plugins in the "compiler" directory will set options to use the
selected compiler. For ":compiler" local options are set, for ":compiler!"
global options.
*current_compiler*
To support older Vim versions, the plugins always use "current_compiler" and
not "b:current_compiler". What the command actually does is the following:
- Delete the "current_compiler" and "b:current_compiler" variables.
- Define the "CompilerSet" user command. With "!" it does ":set", without "!"
it does ":setlocal".
- Execute ":runtime! compiler/{name}.vim". The plugins are expected to set
options with "CompilerSet" and set the "current_compiler" variable to the
name of the compiler.
- Delete the "CompilerSet" user command.
- Set "b:current_compiler" to the value of "current_compiler".
- Without "!" the old value of "current_compiler" is restored.
For writing a compiler plugin, see |write-compiler-plugin|.
MANX AZTEC C *quickfix-manx* *compiler-manx*
To use Vim with Manx's Aztec C compiler on the Amiga you should do the
following:
- Set the CCEDIT environment variable with the command:
mset "CCEDIT=vim -q"
- Compile with the -qf option. If the compiler finds any errors, Vim is
started and the cursor is positioned on the first error. The error message
will be displayed on the last line. You can go to other errors with the
commands mentioned above. You can fix the errors and write the file(s).
- If you exit Vim normally the compiler will re-compile the same file. If you
exit with the :cq command, the compiler will terminate. Do this if you
cannot fix the error, or if a. For Unix "| tee" is used. The compiler output is shown on
the screen and saved in a file the same time. Depending on the shell used
"|& tee" or "2>&1| tee" is the default, so stderr output will be included.
If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful
for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).
==============================================================================
5. Using :vimgrep and :grep *grep* *lid*
Vim has two ways to find matches for a pattern: Internal and external. The
advantage of the internal grep is that it works on all systems and uses the
powerful Vim search patterns. An external grep program can be used when the
Vim grep does not do what you want.
The internal method will be slower, because files are read into memory. The
advantages are:
- Line separators and encoding are automatically recognized, as if a file is
being edited.
- Uses Vim search patterns. Multi-line patterns can be used.
- When plugins are enabled: compressed and remote files can be searched.
|gzip| |netrw|
To be able to do this Vim loads each file as if it is being edited. When
there is no match in the file the associated buffer is wiped out again. The
'hidden' option is ignored here to avoid running out of memory or file
descriptors when searching many files. However, when the |:hide| command
modifier is used the buffers are kept loaded. This makes following searches
in the same files a lot faster.
5.1 using Vim's internal grep
*:vim* *:vimgrep* *E682* *E683*
:vim[grep][!] /{pattern}/[g][j] {file} ...
Search for {pattern} in the files {file} ... and set
the error list to the matches.
Without the 'g' flag each line is added only once.
With 'g' every match is added.
{pattern} is a Vim search pattern. Instead of
enclosing it in / any non-ID character (see
|'isident'|) can be used, so long as it does not
appear in {pattern}.
'ignorecase' applies. To overrule it put |/\c| in the
pattern to ignore case or |/\C| to match case.
'smartcase' is not used.
When a number is put before the command this is used
as the maximum number of matches to find. Use
":1vimgrep pattern file" to find only the first.
Useful if you only want to check if there is a match
and quit quickly when it's found.
Without the 'j' flag Vim jumps to the first match.
With 'j' only the quickfix list is updated.
With the [!] any changes in the current buffer are
abandoned.
Every second or so the searched file name is displayed
to give you an idea of the progress made.
Examples:
:vimgrep /an error/ *.c
:vimgrep /\<FileName\>/ *.h include/*
:vimgrep /myfunc/ **/*.c
For the use of "**" see |starstar-wildcard|.
:vim[grep][!] {pattern} {file} ...
Like above, but instead of enclosing the pattern in a
non-ID character use a white-separated pattern. The
pattern must start with an ID character.
Example:
:vimgrep Error *.c
*:lv* *:lvimgrep*
:lv[imgrep][!] /{pattern}/[g][j] {file} ...
:lv[imgrep][!] {pattern} {file} ...
Same as ":vimgrep", except the location list for the
current window is used instead of the quickfix list.
*:vimgrepa* *:vimgrepadd*
:vimgrepa[dd][!] /{pattern}/[g][j] {file} ...
:vimgrepa[dd][!] {pattern} {file} ...
Just like ":vimgrep", but instead of making a new list
of errors the matches are appended to the current
list.
*:lvimgrepa* *:lvimgrepadd*
:lvimgrepa[dd][!] /{pattern}/[g][j] {file} ...
:lvimgrepa[dd][!] {pattern} {file} ...
Same as ":vimgrepadd", except the location list for
the current window is used instead of the quickfix
list.
5.2 External grep
Vim can interface with "grep" and grep-like programs (such as the GNU
id-utils) in a similar way to its compiler integration (see |:make| above).
[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where
"re" stands for Regular Expression.]
*:gr* *:grep*
:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of
'makeprg' and 'grepformat' instead of 'errorformat'.
When 'grepprg' is "internal" this works like
|:vimgrep|. Note that the pattern needs to be
enclosed in separator characters then.
*:lgr* *:lgrep*
:lgr[ep][!] [arguments] Same as ":grep", except the location list for the
current window is used instead of the quickfix list.
*:grepa* *:grepadd*
:grepa[dd][!] [arguments]
Just like ":grep", but instead of making a new list of
errors the matches are appended to the current list.
Example:
:grep nothing %
:bufdo grepadd! something %
The first command makes a new error list which is
empty. The second command executes "grepadd" for each
listed buffer. Note the use of ! to avoid that
":grepadd" jumps to the first error, which is not
allowed with |:bufdo|.
*:lgrepa* *:lgrepadd*
:lgrepa[dd][!] [arguments]
Same as ":grepadd", except the location list for the
current window is used instead of the quickfix list.
5.3 Setting up external grep
If you have a standard "grep" program installed, the :grep command may work
well with the defaults. The syntax is very similar to the standard command:
:grep foo *.c
Will search all files with the .c extension for the substring "foo". The
arguments to :grep are passed straight to the "grep" program, so you can use
whatever options your "grep" supports.
By default, :grep invokes grep with the -n option (show file and line
numbers). You can change this with the 'grepprg' option. You will need to set
'grepprg' if:
a) You are using a program that isn't called "grep"
b) You have to call grep with a full path
c) You want to pass other options automatically (e.g. case insensitive
search.)
Once "grep" has executed, Vim parses the results using the 'grepformat'
option. This option works in the same way as the 'errorformat' option - see
that for details. You may need to change 'grepformat' from the default if
your grep outputs in a non-standard format, or you are using some other
program with a special format.
Once the results are parsed, Vim loads the first file containing a match and
jumps to the appropriate line, in the same way that it jumps to a compiler
error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc.
commands to see the other matches.
5.4 Using :grep with id-utils
You can set up :grep to work with the GNU id-utils like this:
:set grepprg=lid\ -Rgrep\ -s
:set grepformat=%f:%l:%m
then
:grep (regexp)
works just as you'd expect.
(provided you remembered to mkid first :)
5.5 Browsing source code with :vimgrep or :grep
Using the stack of error lists that Vim keeps, you can browse your files to
look for functions and the functions they call. For example, suppose that you
have to add an argument to the read_file() function. You enter this command:
:vimgrep /\<read_file\>/ *.c
You use ":cn" to go along the list of matches and add the argument. At one
place you have to get the new argument from a higher level function msg(), and
need to change that one too. Thus you use:
:vimgrep /\<msg\>/ *.c
While changing the msg() functions, you find another function that needs to
get the argument from a higher level. You can again use ":vimgrep" to find
these functions. Once you are finished with one function, you can use
:colder
to go back to the previous one.
This works like browsing a tree: ":vimgrep" goes one level deeper, creating a
list of branches. ":colder" goes back to the previous level. You can mix
this use of ":vimgrep" and "colder" to browse all the locations in a tree-like
way. If you do this consistently, you will find all locations without the
need to write down a "todo" list.
=============================================================================
6. Selecting a compiler *compiler-select*
*:comp* *:compiler* *E666*
:comp[iler][!] {name} Set options to work with compiler {name}.
Without the "!" options are set for the
current buffer. With "!" global options are
set.
If you use ":compiler foo" in "file.foo" and
then ":compiler! bar" in another buffer, Vim
will keep on using "foo" in "file.foo".
{not available when compiled without the
|+eval| feature}
The Vim plugins in the "compiler" directory will set options to use the
selected compiler. For ":compiler" local options are set, for ":compiler!"
global options.
*current_compiler*
To support older Vim versions, the plugins always use "current_compiler" and
not "b:current_compiler". What the command actually does is the following:
- Delete the "current_compiler" and "b:current_compiler" variables.
- Define the "CompilerSet" user command. With "!" it does ":set", without "!"
it does ":setlocal".
- Execute ":runtime! compiler/{name}.vim". The plugins are expected to set
options with "CompilerSet" and set the "current_compiler" variable to the
name of the compiler.
- Delete the "CompilerSet" user command.
- Set "b:current_compiler" to the value of "current_compiler".
- Without "!" the old value of "current_compiler" is restored.
For writing a compiler plugin, see |write-compiler-plugin|.
MANX AZTEC C *quickfix-manx* *compiler-manx*
To use Vim with Manx's Aztec C compiler on the Amiga you should do the
following:
- Set the CCEDIT environment variable with the command:
mset "CCEDIT=vim -q"
- Compile with the -qf option. If the compiler finds any errors, Vim is
started and the cursor is positioned on the first error. The error message
will be displayed on the last line. You can go to other errors with the
commands mentioned above. You can fix the errors and write the file(s).
- If you exit Vim normally the compiler will re-compile the same file. If you
exit with the :cq command, the compiler will terminate. Do this if you
cannot fix the error, or if a. For Unix "| tee" is used. The compiler output is shown on
the screen and saved in a file the same time. Depending on the shell used
"|& tee" or "2>&1| tee" is the default, so stderr output will be included.
If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful
for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).
==============================================================================
5. Using :vimgrep and :grep *grep* *lid*
Vim has two ways to find matches for a pattern: Internal and external. The
advantage of the internal grep is that it works on all systems and uses the
powerful Vim search patterns. An external grep program can be used when the
Vim grep does not do what you want.
The internal method will be slower, because files are read into memory. The
advantages are:
- Line separators and encoding are automatically recognized, as if a file is
being edited.
- Uses Vim search patterns. Multi-line patterns can be used.
- When plugins are enabled: compressed and remote files can be searched.
|gzip| |netrw|
To be able to do this Vim loads each file as if it is being edited. When
there is no match in the file the associated buffer is wiped out again. The
'hidden' option is ignored here to avoid running out of memory or file
descriptors when searching many files. However, when the |:hide| command
modifier is used the buffers are kept loaded. This makes following searches
in the same files a lot faster.
5.1 using Vim's internal grep
*:vim* *:vimgrep* *E682* *E683*
:vim[grep][!] /{pattern}/[g][j] {file} ...
Search for {pattern} in the files {file} ... and set
the error list to the matches.
Without the 'g' flag each line is added only once.
With 'g' every match is added.
{pattern} is a Vim search pattern. Instead of
enclosing it in / any non-ID character (see
|'isident'|) can be used, so long as it does not
appear in {pattern}.
'ignorecase' applies. To overrule it put |/\c| in the
pattern to ignore case or |/\C| to match case.
'smartcase' is not used.
When a number is put before the command this is used
as the maximum number of matches to find. Use
":1vimgrep pattern file" to find only the first.
Useful if you only want to check if there is a match
and quit quickly when it's found.
Without the 'j' flag Vim jumps to the first match.
With 'j' only the quickfix list is updated.
With the [!] any changes in the current buffer are
abandoned.
Every second or so the searched file name is displayed
to give you an idea of the progress made.
Examples:
:vimgrep /an error/ *.c
:vimgrep /\<FileName\>/ *.h include/*
:vimgrep /myfunc/ **/*.c
For the use of "**" see |starstar-wildcard|.
:vim[grep][!] {pattern} {file} ...
Like above, but instead of enclosing the pattern in a
non-ID character use a white-separated pattern. The
pattern must start with an ID character.
Example:
:vimgrep Error *.c
*:lv* *:lvimgrep*
:lv[imgrep][!] /{pattern}/[g][j] {file} ...
:lv[imgrep][!] {pattern} {file} ...
Same as ":vimgrep", except the location list for the
current window is used instead of the quickfix list.
*:vimgrepa* *:vimgrepadd*
:vimgrepa[dd][!] /{pattern}/[g][j] {file} ...
:vimgrepa[dd][!] {pattern} {file} ...
Just like ":vimgrep", but instead of making a new list
of errors the ma