1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
======================
Interact with errors
======================
There are a couple of things that you can do with Flycheck errors in a buffer:
* You can navigate to errors, and go to the next or previous error.
* You can display errors to read their error messages.
* You can put error messages and IDs into the kill ring.
This section documents the corresponding commands and their customisation
options.
Navigate errors
===============
By default Flycheck hooks into Emacs’ standard error navigation on :kbd:`M-g n`
(`next-error`) and :kbd:`M-g p` (`previous-error`). When :mode:`flycheck` is
enabled these commands will jump to the next and previous Flycheck error
respectively. See :infonode:`(emacs)Compilation Mode` for more information
about these commands.
This way you don’t need to learn special keybindings to navigate Flycheck
errors; navigation should just work out of the box.
.. note::
Visible compilation buffers such as buffers from ``M-x compile``, ``M-x
grep``, etc. still take *precedence* over Flycheck’s errors.
The exact behaviour of these error navigation features is very context-dependent
and can be very confusing at times so you can disable this integration:
.. defcustom:: flycheck-standard-error-navigation
Whether to integrate Flycheck errors into Emacs’ standard error navigation.
Defaults to ``t``, set to ``nil`` to disable.
.. important::
When changing the value you must disable :mode:`flycheck` and enable it
again for the change to take effect in any buffers where :mode:`flycheck`
is enabled.
Flycheck provides an independent set of navigation commands which will always
navigate Flycheck errors in the current buffer, regardless of visible
compilation buffers and `flycheck-standard-error-navigation`:
.. define-key:: C-c ! n
M-x flycheck-next-error
Jump to the next error.
With prefix argument jump forwards by as many errors as specified by the
prefix argument, e.g. :kbd:`M-3 C-c ! n` will move to the 3rd error from the
current point. With negative prefix argument move to previous errors
instead. Signal an error if there are no more Flycheck errors.
.. define-key:: C-c ! p
M-x flycheck-previous-error
Jump to the previous Flycheck error.
With prefix argument jump backwards by as many errors as specified by the
prefix argument, e.g. :kbd:`M-3 C-c ! p` will move to the 3rd error before
the current point. With negative prefix argument move to next errors
instead. Signal an error if there are no more Flycheck errors.
.. define-key:: M-x flycheck-first-error
Jump to the first Flycheck error.
With prefix argument, jump forwards to by as many errors as specified by the
prefix argument, e.g. :kbd:`M-3 M-x flycheck-first-error` moves to the 3rd
error from the beginning of the buffer. With negative prefix argument move
to the last error instead.
By default error navigation jumps to all errors but you can choose to skip over
errors with low levels:
.. defcustom:: flycheck-navigation-minimum-level
The minimum levels of errors to consider for navigation.
If set to an error level only navigate to errors whose level is as least as
severe as this one. If ``nil`` navigate to all errors.
Display errors
==============
Whenever you move point to an error location Flycheck automatically displays all
Flycheck errors at point after a short delay which you can customise:
.. defcustom:: flycheck-display-errors-delay
The number of seconds to wait before displaying the error at point. Floating
point numbers can express fractions of seconds.
You can also disable Flycheck from automatically displaying errors at point by
customising:
.. defcustom:: flycheck-auto-display-errors-after-checking
Whether to automatically display errors at the current point after checking.
When being set to `nil`, it will prevent Flycheck from automatically displaying
error messages. This setting is useful when Flycheck is used together with
`flycheck-posframe`, to prevent `flycheck-posframe` from repeatedly displaying
errors at point.
By default Flycheck shows the error messages in the minibuffer or in a separate
buffer if the minibuffer is too small to hold the whole error message but this
behaviour is entirely customisable:
.. defcustom:: flycheck-display-errors-function
A function to display errors.
The function is given the list of Flycheck errors to display as sole argument
and shall display these errors to the user in some way.
Flycheck provides two built-in functions for this option:
.. defun:: flycheck-display-error-messages errors
flycheck-display-error-messages-unless-error-list errors
Show error messages and IDs in the echo area or in a separate buffer if the
echo area is too small (using `display-message-or-buffer` which see). The
latter only displays errors when the :ref:`error list <flycheck-error-list>`
is not visible. To enable it add the following to your :term:`init file`:
.. code-block:: elisp
(setq flycheck-display-errors-function
#'flycheck-display-error-messages-unless-error-list)
Along the same vein, Flycheck provides a way to customise how a error message is
cleared, this is especially useful if you use a Flycheck extension to display
error messages differently from the default.
.. defcustom:: flycheck-clear-displayed-errors-function
Function to hide error message displayed by `flycheck-display-errors-function`.
If set to a function, it will be called with no arguments to
clear all displayed errors at point.
By default, Flycheck only provides `flycheck-clear-displayed-error-messages` to
clear the last Flycheck error message from the minibuffer:
.. defun:: flycheck-clear-displayed-error-messages
Clear error messages displayed by `flycheck-display-error-messages`.
.. seealso::
:flyc:`flycheck-pos-tip`
A Flycheck extension to display errors in a GUI popup.
Additionally Flycheck shows errors in a GUI tooltip whenever you hover an error
location with the mouse pointer. By default the tooltip contains the messages
and IDs of all errors under the pointer, but the contents are customisable:
.. defcustom:: flycheck-help-echo-function
A function to create the contents of the tooltip.
The function is given a list of Flycheck errors to display as sole argument
and shall return a single string to use as the contents of the tooltip.
Errors from other files
=======================
Some checkers may return errors from files other than the current buffer (e.g.,
`gcc` may complain about errors in included files). These errors appear in the
error list, and are also added on the first line of the current buffer. You can
jump to the incriminating files with `flycheck-previous-error`.
By default, warnings and info messages from other files are ignored, but you can
customize the minimum level:
.. defcustom:: flycheck-relevant-error-other-file-minimum-level
The minimum level errors from other files to consider for inclusion in the
current buffer.
If set to an error level, only display errors from other files whose error
level is at least as severe as this one. If ``nil``, display all errors from
other files.
To never show any errors from other files, set
`flycheck-relevant-error-other-file-show` to ``nil``.
.. defcustom:: flycheck-relevant-error-other-file-show
Whether to show errors from other files.
Explain errors
==============
Flycheck also has the ability to display explanations for errors, provided the
error checker is capable of producing these explanations. While several
checkers produce explanations, the majority do not. Those that do are:
* `css-stylelint`
* `javascript-eslint`
* `markdown-markdownlint-cli`
* `markdown-markdownlint-cli2`
* `nix-linter`
* `perl-perlcritic`
* `python-pylint`
* `rpm-rpmlint`
* `rust`
* `rust-cargo`
* `rust-clippy`
* `sh-shellcheck`
.. define-key:: C-c ! e
M-x flycheck-explain-error-at-point
Display an explanation for the first explainable error at point.
Kill errors
===========
You can put errors into the kill ring with `C-c ! w`:
.. define-key:: C-c ! C-w
M-x flycheck-copy-errors-as-kill
Copy all messages of the errors at point into the kill ring.
.. define-key:: C-u C-c ! C-w
C-u M-x flycheck-copy-errors-as-kill
Like `C-c ! w` but with error IDs.
.. define-key:: M-0 C-c ! C-w
M-0 M-x flycheck-copy-errors-as-kill
Like `C-c ! w` but do not copy the error messages but only the error IDs.
|
