.. _flycheck-error-list:

=================
 List all errors
=================

You can see all errors in the current buffer in Flycheck’s error list:

.. image:: /images/flycheck-error-list.png
   :align: center

The key `C-c ! l` pops up the error list:

.. define-key:: C-c ! l
                M-x flycheck-list-errors
                M-x list-flycheck-errors

   Pop up a list of errors in the current buffer.

The error list automatically updates itself after every syntax check and follows
the current buffer: If you switch to different buffer or window it automatically
shows the errors of the now current buffer.  The buffer whose errors are shown
in the error list is the *source buffer*.

Whenever the point is on an error in the *source buffer* the error list
highlights these errors—the green line in the screenshot above.

Within the error list the following key bindings are available:

==========   ====
:kbd:`RET`   Go to the current error in the source buffer
:kbd:`n`     Jump to the next error
:kbd:`p`     Jump to the previous error
:kbd:`e`     Explain the error
:kbd:`f`     Filter the error list by level
:kbd:`F`     Remove the filter
:kbd:`S`     Sort the error list by the column at point
:kbd:`g`     Check the source buffer and update the error list
:kbd:`q`     Quit the error list and hide its window
==========   ====

When you jump to an error from the error list with :kbd:`RET`, Flycheck runs
`flycheck-error-list-after-jump-hook` in the source buffer.  This is useful for
post-jump actions like recentering:

.. defcustom:: flycheck-error-list-after-jump-hook

   Functions to run after jumping to an error from the error list.  For
   example, to recenter the window on the error location:

   .. code-block:: elisp

      (add-hook 'flycheck-error-list-after-jump-hook #'recenter)

Filter the list
===============

By default the error list shows all errors but sometimes you'd like to narrow
it down.  The error list supports three filters, which combine and stay in
effect as long as the error list buffer stays alive, until you reset them all
with :kbd:`F`:

* :kbd:`f` prompts for an error level and hides all errors of lower levels.
* :kbd:`c` prompts for a syntax checker and shows only its errors, e.g. only
  the type errors from your type checker while ignoring stylistic complaints.
* :kbd:`/` prompts for a regular expression and shows only errors whose
  message or ID matches it.

The active filters are shown in the error list's mode line.

Sort the list
=============

You can press :kbd:`S` or click on the column headings to sort the error list by
any of the following columns:

* Line
* Level
* ID
* Message and checker

Click twice or press :kbd:`S` repeatedly to flip the sort order from ascending
to descending or vice versa.

Tune error list display
=======================

By default the error list pops up in a side window at the bottom of the frame,
a quarter of the frame tall, like similar lists in contemporary IDEs.  Side
windows are not affected by :kbd:`C-x 1` (`delete-other-windows`); dismiss the
error list with :kbd:`q` in its window instead.  You can change or disable
this behavior:

.. defcustom:: flycheck-error-list-display-buffer-action

   The `display-buffer` action used to display the error list.  Set to ``nil``
   to fall back to the default behavior of `display-buffer`, where the error
   list pops up at an arbitrary place wherever Emacs finds a window for it.

Entries in the built-in option `display-buffer-alist` matching the error list
buffer take precedence over this action, so any existing window-management
configuration keeps working.  For example, to display the error list at the
bottom with a third of the frame height instead:

.. code-block:: elisp

   (add-to-list 'display-buffer-alist
                `(,(rx bos "*Flycheck errors*" eos)
                 (display-buffer-reuse-window
                  display-buffer-in-side-window)
                 (side            . bottom)
                 (reusable-frames . visible)
                 (window-height   . 0.33)))

.. seealso::

   Shackle_
      An Emacs package which provides an alternative way to control buffer
      display

.. _shackle: https://github.com/wasamasa/shackle
