# Vim documentation: quickfix

main help file

    *quickfix.txt*  For Vim version 6.3b.  Last change: 2004 Mar 27

    		  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.

    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).

    The following quickfix commands can be used:

    							*: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* *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'.

    :[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'.

    :[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'.

    							*:crewind* *:cr*
    :cr[ewind][!] [nr]	Display error [nr].  If [nr] is omitted, the FIRST
    			error is displayed.  See |:cc|.

    							*:cfirst* *:cfir*
    :cfir[st][!] [nr]	Same as ":crewind".

    							*: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 [!].

    							*:cg* *:cgetfile*
    :cg[etfile][!] [errorfile]
    			Read the error file.  Just like ":cfile" but don't
    			jump to the first error.

    							*: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.

    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.

    =============================================================================

    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.

    							*:ccl* *:cclose*
    :ccl[ose]		Close the quickfix 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.

    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 <CR> 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.

    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.  This can be used to
    perform some action on the listed errors.  Example:
    	au BufReadPost quickfix  silent g/^/s//\=line(".")." "/
    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.

    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.

    =============================================================================

    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.

    						*: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.

    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 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 read using 'errorformat'.
    			5. If [!] is not given the first error is jumped to.
    			6. The errorfile is deleted.
    			7. 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.

    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 :grep						*grep* *lid*

    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'.

    							*: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|.

    5.1 Setting up 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.2 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.3 Browsing source code with :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:

    	:grep 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:

    	:grep 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 ":grep" 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: ":grep" goes one level deeper, creating a
    list of branches.  ":colder" goes back to the previous level.  You can mix
    this use of ":grep" 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 another file needs to be compiled first.

    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.

    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.

    PYUNIT COMPILER						*compiler-pyunit*

    This is not actually a compiler, but a unit testing framework for the
    Python language. It is included into standard Python distribution
    starting from version 2.0. For older versions, you can get it from
    	http://pyunit.sourceforge.net.

    When you run your tests with the help of the framework, possible errors
    are parsed by Vim and presented for you in quick-fix mode.

    Unfortunately, there is no standard way to run the tests.
    The alltests.py script seems to be used quite often, that's all.
    Useful values for the 'makeprg' options therefore are:
     setlocal makeprg=./alltests.py " Run a testsuite
     setlocal makeprg=python %      " Run a single testcase

     Also see	http://vim.sourceforge.net/tip_view.php?tip_id=280.

    TEX COMPILER						*compiler-tex*

    Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim)
    uses make command if possible. If the compiler finds a file named "Makefile"
    or "makefile" in the current directory, it supposes that you want to process
    your *TeX files with make, and the makefile does the right work. In this case
    compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched. If
    neither "Makefile" nor "makefile" is found, the compiler will not use make.
    You can force the compiler to ignore makefiles by defining
    b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for
    existence only).

    If the compiler chose not to use make, it need to choose a right program for
    processing your input. If b:tex_flavor or g:tex_flavor (in this precedence)
    variable exists, it defines TeX flavor for :make (actually, this is the name
    of executed command), and if both variables do not exist, it defaults to
    "latex". For example, while editing chapter2.tex \input-ed from mypaper.tex
    written in AMS-TeX:

    	:let b:tex_flavor = 'amstex'
    	:compiler tex
     	[editing...]
    	:make mypaper

    Note that you must specify a name of the file to process as an argument (to
    process the right file when editing \input-ed or \include-ed file; portable
    solution for substituting % for no arguments is welcome). This is not in the
    semantics of make, where you specify a target, not source, but you may specify
    filename without extension ".tex" and mean this as "make filename.dvi or
    filename.pdf or filename.some_result_extension according to compiler".

    Note: tex command line syntax is set to usable both for MikTeX (suggestion
    by Srinath Avadhanula) and teTeX (checked by Artem Chuprina). Suggestion
    from |errorformat-LaTeX| is too complex to keep it working for different
    shells and OSes and also does not allow to use other available TeX options,
    if any. If your TeX doesn't support "-interaction=nonstopmode", please
    report it with different means to express \nonstopmode from the command line.

    =============================================================================

    7. The error format					*error-file-format*

    					*errorformat* *E372* *E373* *E374*

    						*E375* *E376* *E377* *E378*
    The 'errorformat' option specifies a list of formats that are recognized.  The
    first format that matches with an error message is used.  You can add several
    formats for different messages your compiler produces, or even entries for
    multiple compilers.  See |efm-entries|.

    Each entry in 'errorformat' is a scanf-like string that describes the format.
    First, you need to know how scanf works.  Look in the documentation of your
    C compiler.  Below you find the % items that Vim understands.  Others are
    invalid.

    Special characters in 'errorformat' are comma and backslash.  See
    |efm-entries| for how to deal with them.  Note that a literal "%" is matched
    by "%%", thus it is not escaped with a backslash.

    Note: By default the difference between upper and lowercase is ignored.  If
    you want to match case, add "\C" to the pattern |/\C|.

    Basic items

    	%f		file name (finds a string)
    	%l		line number (finds a number)
    	%c		column number (finds a number representing character
    			column of the error, (1 <tab> == 1 character column))
    	%v		virtual column number (finds a number representing
    			screen column of the error (1 <tab> == 8 screen
    			columns)
    	%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
    	%p		pointer line (finds a sequence of '-', '.' or '' '' and
    			uses the length for the column number)
    	%*{conv}	any scanf non-assignable conversion
    	%%		the single '%' character

    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.  But when the next character
    is a '%' or a backslash, "%f" will look for any 'isfname' character and "%m"
    finds anything.  If the "%f" or "%m" is at the end, everything up to the end
    of the line is included.

    On MS-DOS, MS-Windows and OS/2 a leading "C:" will be included in "%f", even
    when using "%f:".  This means that a file name which is a single alphabetical
    letter will not be detected.

    The "%p" conversion is normally followed by a "^".  It's used for compilers
    that output a line like:
    	    ^
    or
       ---------^
    to indicate the column of the error.  This is to be used in a multi-line error
    message.  See |errorformat-javac| for a  useful example.

    Changing directory

    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: GNU make). The following
    codes can be used to scan these directory names; they will be stored in an

    internal directory stack.					*E379*
    	%D		"enter directory" format string; expects a following
    			  %f that finds the directory name
    	%X		"leave directory" format string; expects following %f

    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.

    Multi-line messages				*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:
    	%E		start of a multi-line error message
    	%W		start of a multi-line warning message
    	%I		start of a multi-line informational message
    	%A		start of a multi-line message (unspecified type)
    	%C		continuation of a multi-line message
    	%Z		end of a multi-line message
    These can be used with '+' and '-', see |efm-ignore| below.

    Example: Your compiler happens to write out errors in the following format
    (leading line numbers not being part of the actual output):

         1	Error 275
         2	line 42
         3	column 3
         4	'' '' expected after '--'

    The appropriate error format string has to look like this:
       :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%m

    And the |:clist| error message generated for this error is:

     1:42 col 3 error 275:  '' '' expected after '--'

    Another example: Think of a Python interpreter that produces the following
    error message (line numbers are not part of the actual output):

         1	==============================================================
         2	FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest)
         3	--------------------------------------------------------------
         4	Traceback (most recent call last):
         5	  File "unittests/dbfacadeTest.py", line 89, in testFoo
         6	    self.assertEquals(34, dtid)
         7	  File "/usr/lib/python2.2/unittest.py", line 286, in
         8	 failUnlessEqual
         9	    raise self.failureException, \
        10	AssertionError: 34 != 33
        11
        12	--------------------------------------------------------------
        13	Ran 27 tests in 0.063s

    Say you want |:clist| write the relevant information of this message only,
    namely:
     5 unittests/dbfacadeTest.py:89:  AssertionError: 34 != 33

    Then the error format string could be defined as follows:
      :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%m

    Note that the %C string is given before the %A here: since the expression
    '' %.%#' (which stands for the regular expression '' .*') matches every line
    starting with a space, followed by any characters to the end of the line,
    it also hides line 7 which would trigger a separate error message otherwise.
    Error format strings are always parsed pattern by pattern until the first
    match occurs.

    Separate file name			*errorformat-separate-filename*

    These prefixes are useful if the file name is given once and multiple messages
    follow that refer to this file name.
    	%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

    Example: Given a compiler that produces the following error logfile (without
    leading line numbers):

         1	[a1.tt]
         2	(1,17)  error: ';' missing
         3	(21,2)  warning: variable 'z' not defined
         4	(67,3)  error: end of file found before string ended
         5
         6	[a2.tt]
         7
         8	[a3.tt]
         9	NEW compiler v1.1
        10	(2,2)   warning: variable 'x' not defined
        11	(67,3)  warning: 's' already defined

    This logfile lists several messages for each file enclosed in [...] which are
    properly parsed by an error format like this:
      :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-Q

    A call of |:clist| writes them accordingly with their correct filenames:

      2 a1.tt:1 col 17 error: ';' missing
      3 a1.tt:21 col 2 warning: variable 'z' not defined
      4 a1.tt:67 col 3 error: end of file found before string ended
      8 a3.tt:2 col 2 warning: variable 'x' not defined
      9 a3.tt:67 col 3 warning: 's' already defined

    Unlike the other prefixes that all match against whole lines, %P, %Q and %O
    can be used to match several patterns in the same line. Thus it is possible
    to parse even nested files like in the following line:
      {"file1" {"file2" error1} error2 {"file3" error3 {"file4" error4 error5}}}
    The %O then parses over strings that do not contain any push/pop file name
    information.  See |errorformat-LaTeX| for an extended example.

    Ignoring and using whole messages			*efm-ignore*

    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 multi-line in any output
    	%+		include the whole matching line in the %m error string

    One prefix is only useful in combination with '+' or '-', namely %G. It parses
    over lines containing general information like compiler version strings or
    other headers that can be skipped.
    	%-G		ignore this message
    	%+G		general message

    Pattern matching

    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 for a [] character range.
    	%~		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 sub-matches can not be used in format
    specifications because it is reserved for internal conversions.

    Multiple entries in 'errorformat'			*efm-entries*

    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).  You also need to put a backslash
    before a space for ":set".

    Valid matches						*quickfix-valid*

    If a line does not completely match one of the entries in '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.

    Examples

    The format of the file from the Amiga 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

    This can be matched with this 'errorformat' entry:
    	%f>%l:%c:%t:%n:%m

    Some examples for C compilers that produce single-line error outputs:
    %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.

    Filtering messages

    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.

    =============================================================================

    8. The directory stack				*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
    there is a command which echoes "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".

    =============================================================================

    9. Specific error file formats			*errorformats*

    						*errorformat-Jikes*
    Jikes(TM), a source-to-bytecode Java compiler published by IBM Research,
    produces simple multi-line error messages.

    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

    Jikes(TM) produces a single-line error message when invoked with the option
    "+E", and can be matched with the following:

      :set efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%m

    						*errorformat-javac*
    This 'errorformat' has been reported to work well for javac, which outputs a
    line with "^" to indicate the column of the error:
      :set efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%#
    or:
      :set efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%#

    						*errorformat-ant*
     For ant	http://jakarta.apache.org/ the above errorformat has to be modified
    to honour the leading [javac] in front of each javac output line:
      :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#

    The 'errorformat' can also be configured to handle ant together with either
    javac or jikes.  If you're using jikes, you should tell ant to use jikes' +E
    command line switch which forces jikes to generate one-line error messages.
    This is what the second line (of a build.xml file) below does:
      <property name = "build.compiler"       value = "jikes"/>
      <property name = "build.compiler.emacs" value = "true"/>

    The 'errorformat' which handles ant with both javac and jikes is:
      :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m,
    	   \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#

    						*errorformat-jade*
     parsing jade see	http://www.jclark.com/ errors is simple:
      :set efm=jade:%f:%l:%c:%t:%m

    						*errorformat-LaTeX*
    The following is an example how an 'errorformat' string can be specified
    for the (La)TeX typesetting 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.  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\ <return>%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.

    						*errorformat-Perl*
    In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl
    error messages into a format that quickfix mode will understand.  See the
    start of the file about how to use it.

    top - main help file