*quickfix.txt* For Vim version 5.6. Last change: 1999 Oct 28 VIM REFERENCE MANUAL by Bram Moolenaar {Vi does not have any of these commands} The quickfix commands are not available when the |+quickfix| feature was disabled at compile time. Using the QuickFix mode *quickfix* *Quickfix* 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 then examine each problem and fix it, without having to remember all the error messages. If you are using 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 below. 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 another file needs to be compiled first. 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 below). The following commands can be used if you are in QuickFix mode: *: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. *:cn* *:cnext* :[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'. :[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'. *: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'. *:crewind* *:cr* :cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST error is displayed. See |:cc|. *:clast* *:cla* :cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST error is displayed. See |:cc|. *: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 [!]. *:cl* *:clist* :cl[ist] [from] [, [to]] List all errors that include a file name. 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. *:mak* *:make* :mak[e] [arguments] 1. If the 'autowrite' option is on, write any changed buffers 2. An errorfile name is made from 'makeef'. If 'makeef' doesn't contain "##", and a file with this name already exists, it is deleted. 3. 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). 4. The errorfile is then read and the first error is jumped to. 5. The errorfile is deleted. This command does not accept a comment, any " characters are considered part of the arguments. *:gr* *:grep* :gr[ep] [arguments] Just like ":make", but use 'grepprg' instead of 'makeprg' and 'grepformat' instead of 'errorformat'. See |grep|. [Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where "re" stands for Regular Expression.] A template for the errorfile name can be set with the 'makeef' option. If it includes "##", Vim will replace this with a number to make it a unique name. The format of the file from the Aztec compiler is: filename>linenumber:columnnumber:errortype:errornumber:errormessage filename name of the file in which the error was detected linenumber line number where the error was detected columnnumber column number where the error was detected errortype type of the error, normally a single 'E' or 'W' errornumber number of the error (for lookup in the manual) errormessage description of the error *errorformat* Another compiler is likely to use a different format. You should set the 'errorformat' option to a scanf-like string that describes the format. First, you need to know how scanf works. Look in the documentation of your C compiler. Vim will understand the following conversion characters. Others are invalid. %f file name (finds a string) %l line number (finds a number) %c column number (finds a number) %t error type (finds a single character) %n error number (finds a number) %m error message (finds a string) %r matches the "rest" of a single-line file message %O/P/Q %*{conv} any scanf non-assignable conversion %% the single '%' character The following uppercase conversion characters specify the type of special format strings. At most one of them may be given as a prefix at the begin of a single comma-separated format pattern. Some compilers produce messages that consist of directory names that have to be prepended to each file name read by %f (example: GUN make). The following codes can be used to scan these directory names; they will be stored in an internal directory stack. %D "enter directory" format string; expects a following %f that finds the directory name %X "leave directory" format string; expects following %f *errorformat-multi-line* It is possible to read the output of programs that produce multi-line messages, ie. error strings that consume more than one line. Possible prefixes are: %A start of a multi-line message (unspecified type) %E start of a multi-line error message %W start of a multi-line warning message %C continuation of a multi-line message %Z end of a multi-line message %G global; useful only in conjunction with '+' or '-' %O single-line file message: overread the matched part %P single-line file message: push file %f onto the stack %Q single-line file message: pop the last file from stack The codes '+' or '-' can be combined with the uppercase codes above; in that case they have to precede the letter, eg. '%+A' or '%-G': %- do not include the matching line in any output %+ include the whole matching line in the %m error string The scanf()-like "%*[]" notation is supported for backward-compatibility with previous versions of Vim. However, it is also possible to specify (nearly) any Vim supported regular expression in format strings. Since meta characters of the regular expression language can be part of ordinary matching strings or file names (and therefore internally have to be escaped), meta symbols have to be written with leading '%': %\ the single '\' character. Note that this has to be escaped ("%\\") in ":set errorformat=" definitions. %. the single '.' character. %# the single '*'(!) character. %^ the single '^' character. %$ the single '$' character. %[ the single '[' character. %~ the single '~' character. When using character classes in expressions (see |/\i| for an overview), terms containing the "\+" quantifier can be written in the scanf() "%*" notation. Example: "%\\d%\\+" ("\d\+", "any number") is equivalent to "%*\\d". Important note: The \(...\) grouping of expressions can not be used in format specifications because it is reserved for internal conversions. Some examples for C compilers that produce single-line error outputs: %f>%l:%c:%t:%n:%m" for the AztecC.Err file %f:%l:\ %t%*[^0123456789]%n:\ %m for Manx/Aztec C error messages (scanf() doesn't understand [0-9]) %f\ %l\ %t%*[^0-9]%n:\ %m for SAS C \"%f\"\\,%*[^0-9]%l:\ %m for generic C compilers %f:%l:\ %m for GCC %f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f', %Dgmake[%*\\d]:\ Leaving\ directory\ `%f' for GCC with gmake (concat the lines!) %f(%l)\ :\ %*[^:]:\ %m old SCO C compiler (pre-OS5) %f(%l)\ :\ %t%*[^0-9]%n:\ %m idem, with error type and number %f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m for GCC, with some extras Extended examples for the handling of multi-line messages are given below, see |errorformat-Jikes| and |errorformat-LaTeX|. Note the backslash in front of a space and double quote. It is required for the :set command. There are two backslashes in front of a comma, one for the :set command and one to avoid recognizing the comma as a separator of error formats. The "%f" conversion depends on the current 'isfname' setting. The "%f" and "%m" conversions have to detect the end of the string. They should be followed by a character that cannot be in the string. Everything up to that character is included in the string. Be careful: "%f%l" will include everything up to the first '%' in the file name. If the "%f" or "%m" is at the end, everything up to the end of the line is included. When defining an "enter directory" or "leave directory" format, the "%D" or "%X" has to be given at the start of that substring. Vim tracks the directory changes and prepends the current directory to each erroneous file found with a relative path. See |quickfix-directory-stack| for details, tips and limitations. To be able to detect output from several compilers, several format patterns may be put in 'errorformat', separated by commas (note: blanks after the comma are ignored). The first pattern that has a complete match is used. If no match is found, matching parts from the last one will be used, although the file name is removed and the error message is set to the whole message. If there is a pattern that may match output from several compilers (but not in a right way), put it after one that is more restrictive. To include a comma in a pattern precede it with a backslash (you have to type two in a set command). To include a backslash itself give two backslashes (you have to type four in a set command). If a line is detected that does not completely match the 'errorformat', the whole line is put in the error message and the entry is marked "not valid" These lines are skipped with the ":cn" and ":cp" commands (unless there is no valid line at all). You can use ":cl!" to display all the error messages. If the error format does not contain a file name Vim cannot switch to the correct file. You will have to do this by hand. If you have a compiler that produces error messages that do not fit in the format string, you could write a program that translates the error messages into this format. You can use this program with the ":make" command by changing the 'makeprg' option. For example: > :set mp=make\ \\\|&\ error_filter The backslashes before the pipe character are required to avoid it to be recognized as a command separator. The backslash before each space is required for the set command. *quickfix-directory-stack* Quickfix maintains a stack for saving all used directories parsed from the make output. For GNU-make this is rather simple, as it always prints the absolute path of all directories it enters and leaves. Regardless if this is done via a 'cd' command in the makefile or with the parameter "-C dir" (change to directory before reading the makefile). It may be useful to use the switch "-w" to force GNU-make to print out the working directory before and after processing. Maintaining the correct directory is more complicated if you don't use GNU-make. AIX-make for example doesn't print any information about its working directory. Then you need to enhance the makefile. In the makefile of lesstiff their is a command which echos "Making {target} in {dir}". The special problem here is that it doesn't print informations on leaving the directory and that it doesn't print the absolute path. To solve the problem with relative paths and missing "leave directory" messages Vim uses following algorithm: 1) Check if the given directory is a subdirectory of the current directory. If this is true, store it as the current directory. 2) If it is not a subdir of the current directory, try if this is a subdirectory of one of the upper directories. 3) If the directory still isn't found, it is assumed to be a subdirectory of Vim's current directory. Additionally it is checked for every file, if it really exists in the identified directory. If not, it is searched in all other directories of the directory stack (NOT the directory subtree!). If it is still not found, it is assumed that it is in Vim's current directory. There are limitation in this algorithm. This examples assume that make just prints information about entering a directory in the form "Making all in dir". 1) Assume you have following directories and files: ./dir1 ./dir1/file1.c ./file1.c If make processes the directory "./dir1" before the current directory and there is an error in the file "./file1.c", you will end up with the file "./dir1/file.c" loaded by Vim. This can only be solved with a "leave directory" message. 2) Assume you have following directories and files: ./dir1 ./dir1/dir2 ./dir2 You get the following: Make output Directory interpreted by Vim ------------------------ ---------------------------- Making all in dir1 ./dir1 Making all in dir2 ./dir1/dir2 Making all in dir2 ./dir1/dir2 This can be solved by printing absolute directories in the "enter directory" message or by printing "leave directory" messages.. To avoid this problems, ensure to print absolute directory names and "leave directory" messages. Examples for Makefiles: Unix: libs: for dn in $(LIBDIRS); do \ (cd $$dn; echo "Entering dir '$$(pwd)'"; make); \ echo "Leaving dir"; \ done Add %DEntering\ dir\ '%f',%XLeaving\ dir to your 'errorformat' to handle the above output. Note that Vim doesn't check if the directory name in a "leave directory" messages is the current directory. This is why you could just use the message "Leaving dir". *errorformat-Jikes* Jikes(TM), a source-to-bytecode Java compiler published by IBM Research. produces simple multi-line error messages when invoked with the option "+E". An 'errorformat' string matching the produced messages is shown below. The following lines can be placed in the user's |vimrc| to overwrite Vim's recognized default formats, or see |:set+=| how to install this format additionally to the default. >set efm=%A%f:%l:%c:%*\\d:%*\\d:, > \%C%*\\s%trror:%m, > \%+C%*[^:]%trror:%m, > \%C%*\\s%tarning:%m, > \%C%m Note: when copying the command from this help text, please do not forget to remove the leading '>' characters that mark examples. *errorformat-LaTeX* The following is an example how an 'errorformat' string can be specified for the (La)TeX type setting system which displays error messages over multiple lines. The output of ":clist" and ":cc" etc. commands displays multi-lines in a single line, leading white space is removed. It should be easy to adopt the above LaTeX errorformat to any compiler output consisting of multi-line errors. The commands can be placed in a |vimrc| file or some other Vim script file, eg. a script containing LaTeX related stuff which is loaded only when editing LaTeX sources. Make sure to copy all lines of the example (in the given order), afterwards remove the comment lines and also leading '>' characters. For the '\' notation at the start of some lines see |line-continuation|. First prepare 'makeprg' such that LaTeX will report multiple errors; do not stop when the first error has occurred: >set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} Start of multi-line error messages: >set efm=%E!\ LaTeX\ %trror:\ %m, > \%E!\ %m, Start of multi-line warning messages; the first two also include the line number. Meaning of some regular expressions: - "%.%#" (".*") matches a (possibly empty) string - "%*\\d" ("\d\+") matches a number > \%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#, > \%+W%.%#\ at\ lines\ %l--%*\\d, > \%WLaTeX\ %.%#Warning:\ %m, Possible continuations of error/warning messages; the first one also includes the line number: > \%Cl.%l\ %m, > \%+C\ \ %m., > \%+C%.%#-%.%#, > \%+C%.%#[]%.%#, > \%+C[]%.%#, > \%+C%.%#%[{}\\]%.%#, > \%+C<%.%#>%.%#, > \%C\ \ %m, Lines that match the following patterns do not contain any important information; do not include them in messages: > \%-GSee\ the\ LaTeX%m, > \%-GType\ \ H\ %m, > \%-G\ ...%.%#, > \%-G%.%#\ (C)\ %.%#, > \%-G(see\ the\ transcript%.%#), Generally exclude any empty or whitespace-only line from being displayed: > \%-G%*\\s, The LaTeX output log does not specify the names of erroneous source files per line; rather they are given globally, enclosed in parentheses. The following patterns try to match these names and store them in an internal stack. The patterns possibly scan over the same input line (one after another), the trailing "%r" conversion indicates the "rest" of the line that will be parsed in the next go until the end of line is reached. Overread a file name enclosed in '('...')'; do not push it on a stack since the file apparently does not contain any error: > \%+O(%f)%r, Push a file name onto the stack. The name is given after '(': > \%+P(%f%r, > \%+P\ %\\=(%f%r, > \%+P%*[^()](%f%r, > \%+P[%\\d%[^()]%#(%f%r, Pop the last stored file name when a ')' is scanned: > \%+Q)%r, > \%+Q%*[^()])%r, > \%+Q[%\\d%*[^()])%r Note that in some cases file names in the LaTeX output log cannot be parsed properly. The parser might have been messed up by unbalanced parentheses then. The above example tries to catch the most relevant cases only. You can customize the given setting to suit your own purposes, for example, all the annoying "Overfull ..." warnings could be excluded from being recognized as an error. Alternatively to filtering the LaTeX compiler output, it is also possible to directly read the *.log file that is produced by the [La]TeX compiler. This contains even more useful information about possible error causes. However, to properly parse such a complex file, an external filter should be used. See the description further above how to make such a filter known by Vim. *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* :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. *:cnewer* *:cnew* :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. When adding a new error list, it becomes the current list. *:make_makeprg* 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, 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 (Manx's Amiga C). There are some restrictions to the Quickfix mode on the Amiga. The compiler only writes the first 25 errors to the errorfile (Manx's documentation does not say how to get more). If you want to find the others, you will have to fix a few errors and exit the editor. After recompiling, up to 25 remaining errors will be found. On the Amiga, if Vim was started from the compiler, the :sh and some :! commands will not work, because Vim is then running in the same process as the compiler and stdin (standard input) will not be interactive. If you insert or delete lines, mostly the correct error location is still found because hidden marks are used (Manx's Z editor does not do this). 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. vim:tw=78:ts=8:sw=8: