This repository has been archived by the owner on Sep 20, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
/
syntastic.txt
1214 lines (1042 loc) · 57.4 KB
/
syntastic.txt
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
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*syntastic.txt* Syntax checking on the fly has never been so pimp.
*syntastic*
It's a bird! It's a plane! ZOMG It's ... ~
_____ __ __ _ ~
/ ___/__ ______ / /_____ ______/ /_(_)____ ~
\__ \/ / / / __ \/ __/ __ `/ ___/ __/ / ___/ ~
___/ / /_/ / / / / /_/ /_/ (__ ) /_/ / /__ ~
/____/\__, /_/ /_/\__/\__,_/____/\__/_/\___/ ~
/____/ ~
Reference Manual~
==============================================================================
CONTENTS *syntastic-contents*
1.Intro........................................|syntastic-intro|
1.1.Quick start............................|syntastic-quickstart|
1.2.Recommended settings...................|syntastic-recommended|
2.Functionality provided.......................|syntastic-functionality|
2.1.The statusline flag....................|syntastic-statusline-flag|
2.2.Error signs............................|syntastic-error-signs|
2.3.Error window...........................|syntastic-error-window|
2.4.Error highlighting.....................|syntastic-highlighting|
2.5.Aggregating errors.....................|syntastic-aggregating-errors|
2.6.Filtering errors.......................|syntastic-filtering-errors|
3.Commands.....................................|syntastic-commands|
4.Global Options...............................|syntastic-global-options|
5.Checker Options..............................|syntastic-checker-options|
5.1.Choosing which checkers to use.........|syntastic-filetype-checkers|
5.2.Choosing the executable................|syntastic-config-exec|
5.3.Configuring specific checkers..........|syntastic-config-makeprg|
5.4.Sorting errors.........................|syntastic-config-sort|
5.5.Filtering errors.......................|syntastic-config-filtering|
5.6.Debugging..............................|syntastic-config-debug|
5.7.Profiling..............................|syntastic-profiling|
6.Notes........................................|syntastic-notes|
6.1.Handling of composite filetypes........|syntastic-composite|
6.2.Editing files over network.............|syntastic-netrw|
6.3.The 'shellslash' option................|syntastic-shellslash|
6.4.Saving Vim sessions....................|syntastic-sessions|
6.5.The location list callback.............|syntastic-loclist-callback|
7.Compatibility with other software............|syntastic-compatibility|
7.1.airline................................|syntastic-airline|
7.2.The csh and tcsh shells................|syntastic-csh|
7.3.EasyGrep...............................|syntastic-easygrep|
7.4.Eclim..................................|syntastic-eclim|
7.5.ferret.................................|syntastic-ferret|
7.6.The fish shell.........................|syntastic-fish|
7.7.The fizsh shell........................|syntastic-fizsh|
7.8.flagship...............................|syntastic-flagship|
7.9.powerline..............................|syntastic-powerline|
7.10.The PowerShell shell..................|syntastic-powershell|
7.11.python-mode...........................|syntastic-pymode|
7.12.vim-auto-save.........................|syntastic-vim-auto-save|
7.13.vim-go................................|syntastic-vim-go|
7.14.vim-virtualenv........................|syntastic-vim-virtualenv|
7.15.YouCompleteMe.........................|syntastic-ycm|
7.16.The zsh shell and MacVim..............|syntastic-zsh|
8.About........................................|syntastic-about|
9.License......................................|syntastic-license|
==============================================================================
1. Intro *syntastic-intro*
Syntastic is a syntax checking plugin that runs files through external syntax
linters. This can be done on demand, or automatically as files are saved
and opened. If syntax errors are detected, the user is notified and is happy
because they didn't have to compile their code or execute their script to find
them.
Syntastic comes in two parts: the syntax checker plugins, and the core. The
syntax checker plugins are defined on a per-filetype basis where each one wraps
up an external syntax checking program. The core script delegates off to these
plugins and uses their output to provide the syntastic functionality.
Take a look at the list of supported filetypes and checkers: |syntastic-checkers|.
Note: This doc only deals with using syntastic. To learn how to write syntax
checker integrations see the guide on the GitHub wiki:
https://github.com/vim-syntastic/syntastic/wiki/Syntax-Checker-Guide
------------------------------------------------------------------------------
1.1. Quick start *syntastic-quickstart*
Syntastic comes preconfigured with a default list of enabled checkers per
|filetype|. This list is kept reasonably short to prevent slowing down Vim or
trying to use conflicting checkers.
You can see the list of checkers available for the current filetype with the
`:SyntasticInfo` command.
You probably want to override the configured list of checkers for the
filetypes you use, and also change the arguments passed to specific linters
to suit your needs. See |syntastic-checker-options| below for details.
Use `:SyntasticCheck` to manually check right now. Use `:Errors` to open the
|location-list| window, and `:lclose` to close it. You can clear the error
list with `:SyntasticReset`, and you can use `:SyntasticToggleMode` to switch
between active (checking on writing the buffer) and passive (manual) checking.
You don't have to switch focus to the |location-list| window to jump to the
different errors. Vim provides several built-in commands for this, for
example `:lnext` and `:lprevious`. You may want to add shortcut mappings for
these commands, or perhaps install a plugin such as Tim Pope's "unimpaired"
(see https://github.com/tpope/vim-unimpaired) that provides such mappings.
------------------------------------------------------------------------------
1.2. Recommended settings *syntastic-recommended*
Syntastic has numerous options that can be configured, and the defaults are
not particularly well suitable for new users. It is recommended that you start
by adding the following lines to your vimrc, and return to them later as
needed: >
set statusline+=%#warningmsg#
set statusline+=%{SyntasticStatuslineFlag()}
set statusline+=%*
let g:syntastic_always_populate_loc_list = 1
let g:syntastic_auto_loc_list = 1
let g:syntastic_check_on_open = 1
let g:syntastic_check_on_wq = 0
<
==============================================================================
2. Functionality provided *syntastic-functionality*
Syntax checking can be done automatically or on demand (see
|'syntastic_mode_map'| and `:SyntasticToggleMode` for configuring this).
When syntax checking is done, the features below can be used to notify the
user of errors. See |syntastic-global-options| for how to configure and
activate/deactivate these features.
* A statusline flag
* Signs beside lines with errors
* The |location-list| can be populated with the errors for the associated
buffer
* Erroneous parts of lines can be highlighted (this functionality is only
provided by some checkers)
* Balloons (if the |+balloon_eval| feature is compiled in) can be used to
display error messages for erroneous lines when hovering the mouse over
them
* Error messages from multiple checkers can be aggregated in a single list
------------------------------------------------------------------------------
2.1. The statusline flag *syntastic-statusline-flag*
To use the statusline flag, this must appear in your |'statusline'| setting >
%{SyntasticStatuslineFlag()}
<
Something like this could be more useful: >
set statusline+=%#warningmsg#
set statusline+=%{SyntasticStatuslineFlag()}
set statusline+=%*
<
When syntax errors are detected a flag will be shown. The content of the flag
is derived from the |'syntastic_stl_format'| option.
Please note that these settings might conflict with other Vim plugins that
change the way 'statusline' works. Refer to the |syntastic-compatibility| notes
below and to the respective plugins' documentation for possible solutions.
In particular see |syntastic-airline| below if you're using the "airline" Vim
plugin (https://github.com/vim-airline/vim-airline). See |syntastic-flagship|
if you're using "flagship" (https://github.com/tpope/vim-flagship). See also
|syntastic-powerline| if you're using the "powerline" Vim plugin
(https://github.com/powerline/powerline).
------------------------------------------------------------------------------
2.2. Error signs *syntastic-error-signs*
Syntastic uses the `:sign` commands (provided that the |+signs| feature is
compiled in) to mark lines with errors and warnings in the sign column. To
enable this feature, use the |'syntastic_enable_signs'| option.
Signs are colored using the Error and Todo syntax highlight groups by default
(see |group-name|). If you wish to customize the colors for the signs, you
can use the following groups:
SyntasticErrorSign - For syntax errors, links to "error" by default
SyntasticWarningSign - For syntax warnings, links to "todo" by default
SyntasticStyleErrorSign - For style errors, links to "SyntasticErrorSign"
by default
SyntasticStyleWarningSign - For style warnings, links to
"SyntasticWarningSign" by default
Example: >
highlight SyntasticErrorSign guifg=white guibg=red
<
To set up highlighting for the line where a sign resides, you can use the
following highlight groups:
SyntasticErrorLine
SyntasticWarningLine
SyntasticStyleErrorLine - Links to "SyntasticErrorLine" by default
SyntasticStyleWarningLine - Links to "SyntasticWarningLine" by default
Example: >
highlight SyntasticErrorLine guibg=#2f0000
<
With Vim 8.0 or later you can ask Vim not to turn off the sign column when no
errors are found, by setting 'signcolumn' to "yes": >
set signcolumn=yes
<
------------------------------------------------------------------------------
2.3. The error window *syntastic-error-window*
You can use the `:Errors` command to display the errors for the current buffer
in the |location-list|.
By default syntastic doesn't fill the |location-list| with the errors found by
the checkers, in order to reduce clashes with other plugins. Consequently, if
you run `:lopen` or `:lwindow` rather than `:Errors` to open the error window
you wouldn't see syntastic's list of errors. If you insist on using `:lopen`
or `:lwindow` you should either run `:SyntasticSetLoclist` after running the
checks, or set |'syntastic_always_populate_loc_list'| which tells syntastic to
update the |location-list| automatically.
------------------------------------------------------------------------------
2.4. Error highlighting *syntastic-highlighting*
Some linters provide enough information for syntastic to be able to highlight
errors. By default the SpellBad syntax highlight group is used to color errors,
and the SpellCap group is used for warnings. If you wish to customize the
colors for highlighting you can use the following groups:
SyntasticError - Links to "SpellBad" by default (see |hl-SpellBad|)
SyntasticWarning - Links to "SpellCap" by default (see |hl-SpellCap|)
SyntasticStyleError - Links to "SyntasticError" by default
SyntasticStyleWarning - Links to "SyntasticWarning" by default
Example: >
highlight SyntasticError guibg=#2f0000
<
------------------------------------------------------------------------------
2.5. Aggregating errors *syntastic-aggregating-errors*
By default, namely if |'syntastic_aggregate_errors'| is unset, syntastic runs
in turn the checkers corresponding to the filetype of the current file (see
|syntastic-filetype-checkers|), and stops as soon as a checker reports any
errors. It then notifies you of the errors using the notification mechanisms
above. In this mode error lists are always produced by a single checker, and,
if you open the error window, the name of the checker that generated the errors
is shown on the statusline of the error window.
If |'syntastic_aggregate_errors'| is set, syntastic runs all checkers that
apply (still cf. |syntastic-filetype-checkers|), then aggregates errors found
by all checkers in a single list, and notifies you. In this mode each error
message is labeled with the name of the checker that generated it, but you can
disable generation of these labels by turning off |'syntastic_id_checkers'|.
If |'syntastic_sort_aggregated_errors'| is set (which is the default), messages
in the aggregated list are grouped by file, then sorted by line number, then
type, then column number. Otherwise messages produced by the same checker are
grouped together, and sorting within each group is decided by the variables
|'syntastic_<filetype>_<checker>_sort'|.
------------------------------------------------------------------------------
2.6. Filtering errors *syntastic-filtering-errors*
You can selectively disable some of the errors found by checkers either
using |'syntastic_quiet_messages'|, or by specifying a list of patterns in
|'syntastic_ignore_files'|.
See also: |'syntastic_<filetype>_<checker>_quiet_messages'| and
|'b:syntastic_skip_checks'|.
==============================================================================
3. Commands *syntastic-commands*
:Errors *:Errors*
When errors have been detected, use this command to pop up the |location-list|
and display the error messages.
Please note that the `:Errors` command overwrites the current location list with
syntastic's own location list.
:SyntasticToggleMode *:SyntasticToggleMode*
Toggles syntastic between active and passive mode. See |'syntastic_mode_map'|
for more info.
:SyntasticCheck *:SyntasticCheck*
Manually cause a syntax check to be done. By default the checkers in the
|'g:syntastic_<filetype>_checkers'| or |'b:syntastic_checkers'| lists are run,
cf. |syntastic-filetype-checkers|. If |'syntastic_aggregate_errors'| is unset
(which is the default), checking stops the first time a checker reports any
errors; if |'syntastic_aggregate_errors'| is set, all checkers that apply are
run in turn, and all errors found are aggregated in a single list.
The command may be followed by a (space separated) list of checkers. In this
case |'g:syntastic_<filetype>_checkers'| and |'b:syntastic_checkers'| are
ignored, and the checkers named by the command's arguments are run instead, in
the order specified. The set by |'syntastic_aggregate_errors'| still apply.
Example: >
:SyntasticCheck flake8 pylint
<
You can also run checkers for filetypes different from the current filetype
by qualifying their names with their respective filetypes, like this:
"<filetype>/<checker>".
Example: >
:SyntasticCheck lacheck text/language_check
<
:SyntasticInfo *:SyntasticInfo*
The command takes an optional argument, and outputs information about the
checkers available for the filetype named by said argument, or for the current
filetype if no argument was provided.
Example: >
:SyntasticInfo python
<
:SyntasticReset *:SyntasticReset*
Resets the list of errors and turns off all error notifiers.
:SyntasticSetLoclist *:SyntasticSetLoclist*
If |'syntastic_always_populate_loc_list'| is not set, the |location-list| is
not filled in automatically with the list of errors detected by the checkers.
This is useful if you run syntastic along with other plugins that use location
lists. The `:SyntasticSetLoclist` command allows you to stick the errors into
the location list explicitly.
==============================================================================
4. Global Options *syntastic-global-options*
*'syntastic_check_on_open'*
Type: boolean
Default: 0
If this variable is enabled, syntastic in active mode will run syntax checks
when buffers are first loaded, as well as on saving: >
let g:syntastic_check_on_open = 1
<
*'syntastic_check_on_wq'*
Type: boolean
Default: 1
In active mode syntax checks are normally run whenever buffers are written to
disk, even when the writes happen just before quitting Vim. If you want to
skip checks when you issue `:wq`, `:x`, and `:ZZ`, set this variable to 0: >
let g:syntastic_check_on_wq = 0
<
*'syntastic_aggregate_errors'*
Type: boolean
Default: 0
When enabled, syntastic runs all checkers that apply to the current filetype,
then aggregates errors found by all checkers and displays them. When disabled,
syntastic runs each checker in turn, and stops to display the results the first
time a checker finds any errors. >
let g:syntastic_aggregate_errors = 1
<
*'syntastic_id_checkers'*
Type: boolean
Default: 1
When results from multiple checkers are aggregated in a single error list
(that is either when |'syntastic_aggregate_errors'| is enabled, or when
checking a file with a composite filetype, cf. |syntastic-composite|), it
might not be immediately obvious which checker has produced a given error
message. This variable instructs syntastic to label error messages with the
names of the checkers that created them. >
let g:syntastic_id_checkers = 0
<
*'syntastic_sort_aggregated_errors'*
Type: boolean
Default: 1
By default, when results from multiple checkers are aggregated in a single
error list (that is either when |'syntastic_aggregate_errors'| is enabled, or
when checking a file with a composite filetype, cf. |syntastic-composite|),
errors are grouped by file, then sorted by line number, then grouped by type
(namely errors take precedence over warnings), then they are sorted by column
number. If you want to leave messages grouped by checker output, set this
variable to 0: >
let g:syntastic_sort_aggregated_errors = 0
<
*'syntastic_echo_current_error'*
Type: boolean
Default: 1
If enabled, syntastic will echo current error to the command window. If
multiple errors are found on the same line, |'syntastic_cursor_columns'| is
used to decide which one is shown. >
let g:syntastic_echo_current_error = 1
<
*'syntastic_cursor_columns'*
Type: boolean
Default: 1
This option controls which errors are echoed to the command window if
|'syntastic_echo_current_error'| is set and multiple errors are found on the
same line. When the option is enabled, the first error corresponding to the
current column is shown. Otherwise, the first error on the current line is
echoed, regardless of the cursor position on the current line.
When dealing with very large lists of errors, disabling this option can speed
up navigation significantly: >
let g:syntastic_cursor_column = 0
<
*'syntastic_enable_signs'*
Type: boolean
Default: 1
Use this option to tell syntastic whether to use the `:sign` interface to mark
syntax errors: >
let g:syntastic_enable_signs = 1
<
*'syntastic_error_symbol'* *'syntastic_style_error_symbol'*
*'syntastic_warning_symbol'* *'syntastic_style_warning_symbol'*
Type: string
Use these options to control what the syntastic `:sign` text contains. Several
error symbols can be customized:
syntastic_error_symbol - For syntax errors, defaults to ">>"
syntastic_style_error_symbol - For style errors, defaults to "S>"
syntastic_warning_symbol - For syntax warnings, defaults to ">>"
syntastic_style_warning_symbol - For style warnings, defaults to "S>"
Example: >
let g:syntastic_error_symbol = "\u2717"
let g:syntastic_warning_symbol = "\u26A0"
<
*'syntastic_enable_balloons'*
Type: boolean
Default: 1
Use this option to tell syntastic whether to display error messages in balloons
when the mouse is hovered over erroneous lines: >
let g:syntastic_enable_balloons = 1
<
Note that Vim must be compiled with |+balloon_eval|.
*'syntastic_enable_highlighting'*
Type: boolean
Default: 1
Use this option to tell syntastic whether to use syntax highlighting to mark
errors (where possible). Highlighting can be turned off with the following >
let g:syntastic_enable_highlighting = 0
<
*'syntastic_always_populate_loc_list'*
Type: boolean
Default: 0
By default syntastic doesn't fill the |location-list| with the errors found
by the checkers, in order to reduce clashes with other plugins. Enable this
option to tell syntastic to always stick any detected errors into the
|location-list|: >
let g:syntastic_always_populate_loc_list = 1
<
Please note that if |'syntastic_auto_jump'| is set to a non-zero value the
location list is overwritten with Syntastic's own list when taking a jump,
regardless of the value of |'syntastic_always_populate_loc_list'|. The
location list is also overwritten when running the `:Errors` command.
*'syntastic_auto_jump'*
Type: integer
Default: 0
Enable this option if you want the cursor to jump to the first detected issue
when saving or opening a file.
When set to 0 the cursor won't jump automatically. >
let g:syntastic_auto_jump = 0
<
When set to 1 the cursor will always jump to the first issue detected,
regardless of type. >
let g:syntastic_auto_jump = 1
<
When set to 2 the cursor will jump to the first issue detected, but only if
this issue is an error. >
let g:syntastic_auto_jump = 2
<
When set to 3 the cursor will jump to the first error detected, if any. If
all issues detected are warnings, the cursor won't jump. >
let g:syntastic_auto_jump = 3
<
Please note that in either situation taking the jump also has the side effect
of the location list being overwritten with Syntastic's own location list,
regardless of the value of |'syntastic_always_populate_loc_list'|.
*'syntastic_auto_loc_list'*
Type: integer
Default: 2
Use this option to tell syntastic to automatically open and/or close the
|location-list| (see |syntastic-error-window|).
When set to 0 the error window will be neither opened nor closed
automatically. >
let g:syntastic_auto_loc_list = 0
<
When set to 1 the error window will be automatically opened when errors are
detected, and closed when none are detected. >
let g:syntastic_auto_loc_list = 1
<
When set to 2 the error window will be automatically closed when no errors are
detected, but not opened automatically. >
let g:syntastic_auto_loc_list = 2
<
When set to 3 the error window will be automatically opened when errors are
detected, but not closed automatically. >
let g:syntastic_auto_loc_list = 3
<
*'syntastic_loc_list_height'*
Type: integer
Default: 10
Use this option to specify the height of the location lists that syntastic
opens. >
let g:syntastic_loc_list_height = 5
<
*'syntastic_ignore_files'*
Type: list of strings
Default: []
Use this option to specify files that syntastic should never check. It's a
list of |regular-expression| patterns. The full paths of files (see |::p|) are
matched against these patterns, and the matches are case-sensitive. Use |\c|
to specify case-insensitive patterns. Example: >
let g:syntastic_ignore_files = ['\m^/usr/include/', '\m\c\.h$']
<
*'syntastic_filetype_map'*
Type: dictionary
Default: {}
Use this option to map non-standard filetypes to standard ones. Corresponding
checkers are mapped accordingly, which allows syntastic to check files with
non-standard filetypes: >
let g:syntastic_filetype_map = {
\ "plaintex": "tex",
\ "gentoo-metadata": "xml" }
<
Composite filetypes (cf. |syntastic-composite|) can also be mapped to simple
types, which disables the default behaviour of running both checkers against
the input file: >
let g:syntastic_filetype_map = { "handlebars.html": "handlebars" }
<
*'syntastic_mode_map'*
Type: dictionary
Default: { "mode": "active",
"active_filetypes": [],
"passive_filetypes": [] }
Use this option to fine tune when automatic syntax checking is done (or not
done).
The option should be set to something like: >
let g:syntastic_mode_map = {
\ "mode": "active",
\ "active_filetypes": ["ruby", "php"],
\ "passive_filetypes": ["puppet"] }
<
"mode" can be mapped to one of two values - "active" or "passive". When set
to "active", syntastic does automatic checking whenever a buffer is saved or
initially opened. When set to "passive" syntastic only checks when the user
calls `:SyntasticCheck`.
The exceptions to these rules are defined with "active_filetypes" and
"passive_filetypes". In passive mode, automatic checks are still done for
filetypes in the "active_filetypes" array (and "passive_filetypes" is
ignored). In active mode, automatic checks are not done for any filetypes in
the "passive_filetypes" array ("active_filetypes" is ignored).
If any of "mode", "active_filetypes", or "passive_filetypes" are left
unspecified, they default to values above.
If local variable |'b:syntastic_mode'| is defined its value takes precedence
over all calculations involving |'syntastic_mode_map'| for the corresponding
buffer.
At runtime, the `:SyntasticToggleMode` command can be used to switch between
active and passive modes.
*'b:syntastic_mode'*
Type: string
Default: unset
Only the local form |'b:syntastic_mode'| is used. When set to either "active"
or "passive", it takes precedence over |'syntastic_mode_map'| when deciding
whether the corresponding buffer should be checked automatically.
*'syntastic_quiet_messages'*
Type: dictionary
Default: {}
Use this option to filter out some of the messages produced by checkers. The
option should be set to something like: >
let g:syntastic_quiet_messages = {
\ "!level": "errors",
\ "type": "style",
\ "regex": '\m\[C03\d\d\]',
\ "file:p": ['\m^/usr/include/', '\m\c\.h$'] }
<
Each element turns off messages matching the patterns specified by the
corresponding value. Values are lists, but if a list consists of a single
element you may omit the brackets (e.g. you may write "style" instead of
["style"]). Elements with values [] or "" are ignored (this is useful for
overriding filters, cf. |filter-overrides|).
"level" - takes one of two values, "warnings" or "errors"
"type" - can be either "syntax" or "style"
"regex" - each item in list is matched against the messages' text as a
case-insensitive |regular-expression|
"file" - each item in list is matched against the filenames the messages
refer to, as a case-sensitive |regular-expression|.
If a key is prefixed by an exclamation mark "!", the corresponding filter is
negated (i.e. the above example silences all messages that are NOT errors).
The "file" key may be followed by one or more filename modifiers (see
|filename-modifiers|). The modifiers are applied to the filenames the messages
refer to before matching against the value (i.e. in the above example the full
path of the issues are matched against '\m^/usr/include/' and '\m\c\.h$').
If |'syntastic_id_checkers'| is set, filters are applied before error messages
are labeled with the names of the checkers that created them.
There are also checker-specific variants of this option, providing finer
control. They are named |'syntastic_<filetype>_<checker>_quiet_messages'|.
For a particular checker, if both a |'syntastic_quiet_messages'| filter and
a checker-specific filter are present, they are both applied to the list of
errors produced by the said checker. In case of conflicting values for the
same keys, the values of the checker-specific filters take precedence.
*filter-overrides*
Since filter elements with values [] or "" are ignored, you can disable global
filters for particular checkers, by setting the values of the corresponding
elements in |'syntastic_<filetype>_<checker>_quiet_messages'| to [] or "". For
example, the following setting will silence all warnings, except for the
ones produced by "pylint": >
let g:syntastic_quiet_messages = { "level": "warnings" }
let g:syntastic_python_pylint_quiet_messages = { "level" : [] }
<
*'syntastic_stl_format'*
Type: string
Default: "[Syntax: line:%F (%t)]"
Use this option to control what the syntastic statusline text contains. Several
magic flags are available to insert information:
%e - number of errors
%w - number of warnings
%t - total number of warnings and errors
%ne - filename of file containing first error
%nw - filename of file containing first warning
%N - filename of file containing first warning or error
%pe - filename with path of file containing first error
%pw - filename with path of file containing first warning
%P - filename with path of file containing first warning or error
%fe - line number of first error
%fw - line number of first warning
%F - line number of first warning or error
These flags accept width and alignment controls similar to the ones used by
|'statusline'| flags:
%-0{minwid}.{maxwid}{flag}
All fields except {flag} are optional. A single percent sign can be given as
"%%".
Several additional flags are available to hide text under certain conditions:
%E{...} - hide the text in the brackets unless there are errors
%W{...} - hide the text in the brackets unless there are warnings
%B{...} - hide the text in the brackets unless there are both warnings AND
errors
These flags can't be nested.
Example: >
let g:syntastic_stl_format = "[%E{Err: %fe #%e}%B{, }%W{Warn: %fw #%w}]"
<
If this format is used and the current buffer has 5 errors and 1 warning
starting on lines 20 and 10 respectively then this would appear on the
statusline: >
[Err: 20 #5, Warn: 10 #1]
<
If the buffer had 2 warnings, starting on line 5 then this would appear: >
[Warn: 5 #2]
<
*'b:syntastic_skip_checks'*
Type: boolean
Default: unset
Only the local form |'b:syntastic_skip_checks'| is used. When set to a true
value, no checks are run against the corresponding buffer. Example: >
let b:syntastic_skip_checks = 1
<
*'syntastic_full_redraws'*
Type: boolean
Default: 0 in GUI Vim and MacVim, 1 otherwise
Controls whether syntastic calls `:redraw` or `:redraw!` for screen redraws.
Changing it can in principle make screen redraws smoother, but it can also
cause screen to flicker, or cause ghost characters. Leaving it to the default
should be safe.
*'syntastic_exit_checks'*
Type: boolean
Default: 0 when running under "cmd.exe" on Windows, 1 otherwise
Syntastic attempts to catch abnormal termination conditions from linters by
looking at their exit codes. The "cmd.exe" shell on Windows make these checks
meaningless, by returning 1 to Vim when the linters exit with non-zero codes.
The above variable can be used to disable exit code checks in syntastic.
*'syntastic_shell'*
Type: string
Default: Vim's 'shell'
This is the (full path to) the shell syntastic will use to run the linters.
On UNIX and Mac OS-X this shell must accept Bourne-compatible syntax for
file "stdout" and "stderr" redirections ">file" and "2>file". Examples of
compatible shells are "zsh", "bash", "ksh", and of course the original Bourne
"sh".
This shell is independent of Vim's 'shell', and it isn't used for interactive
operations. It must take care to initialize all environment variables needed
by the linters you're using. Example: >
let g:syntastic_shell = "/bin/sh"
<
*'syntastic_nested_autocommands'*
Type: boolean
Default: 0
Controls whether syntastic's autocommands |BufReadPost| and |BufWritePost|
are called from other |BufReadPost| and |BufWritePost| autocommands (see
|autocmd-nested|). This is known to trigger interoperability problems with
other plugins, so only enable it if you actually need that functionality.
*'syntastic_debug'*
Type: integer
Default: 0
Set this to the sum of one or more of the following flags to enable
debugging:
1 - trace general workflow
2 - dump location lists
4 - trace notifiers
8 - trace autocommands
16 - dump options
32 - trace running of specific checkers
Example: >
let g:syntastic_debug = 1
<
Syntastic will then add debugging messages to Vim's |message-history|. You can
examine these messages with `:mes`.
*'syntastic_debug_file'*
Type: string
Default: unset
When set, debugging messages are written to the file named by its value, in
addition to being added to Vim's |message-history|: >
let g:syntastic_debug_file = "~/syntastic.log"
<
*'syntastic_extra_filetypes'*
Type: list of strings
Default: []
List of filetypes handled by checkers external to syntastic. If you have a Vim
plugin that adds a checker for syntastic, and if the said checker deals with a
filetype that is unknown to syntastic, you might consider adding that filetype
to this list: >
let g:syntastic_extra_filetypes = [ "make", "gitcommit" ]
<
This will allow `:SyntasticInfo` to do proper tab completion for the new
filetypes.
==============================================================================
5. Checker Options *syntastic-checker-options*
------------------------------------------------------------------------------
5.1. Choosing which checkers to use *syntastic-filetype-checkers*
*'g:syntastic_<filetype>_checkers'*
You can tell syntastic which checkers to run for a given filetype by setting a
variable 'g:syntastic_<filetype>_checkers' to a list of checkers, e.g. >
let g:syntastic_php_checkers = ["php", "phpcs", "phpmd"]
<
*'b:syntastic_checkers'*
There is also a per-buffer version of this setting, |'b:syntastic_checkers'|.
When set, it takes precedence over |'g:syntastic_<filetype>_checkers'|. You can
use this in an autocmd to configure specific checkers for particular paths: >
autocmd FileType python if stridx(expand("%:p"), "/some/path/") == 0 |
\ let b:syntastic_checkers = ["pylint"] | endif
<
If neither |'g:syntastic_<filetype>_checkers'| nor |'b:syntastic_checkers'|
is set a default list of checkers is used. Beware however that this list is
deliberately kept minimal, for performance reasons.
You can specify checkers for other filetypes anywhere in these lists, by
qualifying their names with their respective filetypes: >
let g:syntastic_tex_checkers = ["lacheck", "text/language_check"]
<
Take a look elsewhere in this manual to find out what checkers and filetypes
are supported by syntastic: |syntastic-checkers|.
Use `:SyntasticInfo` to see which checkers are available for a given filetype.
------------------------------------------------------------------------------
5.2. Choosing the executable *syntastic-config-exec*
*'syntastic_<filetype>_<checker>_exec'*
The executable run by a checker is normally defined automatically, when the
checker is registered. You can however override it, by setting the variable
'g:syntastic_<filetype>_<checker>_exec': >
let g:syntastic_ruby_mri_exec = "~/bin/ruby2"
<
This variable has a local version, 'b:syntastic_<filetype>_<checker>_exec',
which takes precedence over the global one in the corresponding buffer.
*'b:syntastic_<checker>_exec'*
There is also a local variable named 'b:syntastic_<checker>_exec', which
takes precedence over both 'b:syntastic_<filetype>_<checker>_exec' and
'g:syntastic_<filetype>_<checker>_exec' in the buffers where it is defined.
------------------------------------------------------------------------------
5.3. Configuring specific checkers *syntastic-config-makeprg*
Linters are run by constructing a command line and by passing it to a shell
(see |'shell'| and |'syntastic_shell'|). In most cases this command line is
built using an internal function named "makeprgBuild()", which provides a
number of options that allow you to customise every part of the command that
gets called.
*'syntastic_<filetype>_<checker>_<option>'*
Checkers that use "makeprgBuild()" construct the corresponding command line
like this: >
let makeprg = self.makeprgBuild({
\ "exe": self.getExec(),
\ "args": "-a -b -c",
\ "fname": shellescape(expand("%", 1)),
\ "post_args": "--more --args",
\ "tail": "2>/dev/null" })
<
The result is a command line of the form: >
<exe> <args> <fname> <post_args> <tail>
<
All fields above are optional, and can be overridden by setting global
variables 'g:syntastic_<filetype>_<checker-name>_<option-name>' - even
parameters not specified in the call to "makeprgBuild()". For example to
override the arguments and the tail: >
let g:syntastic_c_pc_lint_args = "-w5 -Iz:/usr/include/linux"
let g:syntastic_c_pc_lint_tail = "2>/dev/null"
<
These variables also have buffer-local versions named
'b:syntastic_<filetype>_<checker-name>_<option-name>', which takes precedence
over the global ones in the corresponding buffers.
You can see the final outcome of setting these variables in the debug logs
(cf. |syntastic-config-debug|).
Special characters need to be escaped, so that they can survive shell
expansions. Vim function |shellescape()| can help you with escaping: >
let g:syntastic_c_cppcheck_args =
\ "-DBUILD_BASENAME=my-module " . shellescape("-DBUILD_STR(s)=#s")
<
Alternatively, you can tell syntastic to escape special characters by turning
the value into a list: >
let g:syntastic_c_cppcheck_args =
\ ["-DBUILD_BASENAME=my-module", "-DBUILD_STR(s)=#s"]
<
Each element of this list is then escaped as needed, and turned into a
separate argument for the shell.
*syntastic-config-empty*
If one of the above variables has a non-empty default and you want it to be
empty, you can set it to an empty string, e.g.: >
let g:syntastic_javascript_jslint_args = ""
<
*'syntastic_<filetype>_<checker>_exe'*
The 'exe' option is special. Normally it is the same as the 'exec' attribute
described above, but you can use it to add environment variables to the
command line, or to change the way the linter is run. For example this setup
allows you to run PC-Lint on Linux, under Wine emulation: >
let g:syntastic_c_pc_lint_exec = "wine"
let g:syntastic_c_pc_lint_exe = "wine c:/path/to/lint-nt.exe"
<
*'syntastic_<filetype>_<checker>_fname'*
The 'fname' option is also special. Normally it is automatically set by
syntastic to the name of the current file, but you can change that as needed.
For example you can tell the SML/NJ compiler to use Compilation Manager by
omitting the filename from the command line: >
let g:syntastic_sml_smlnj_fname = ""
<
*syntastic-config-no-makeprgbuild*
For checkers that do not use the "makeprgBuild()" function any specific
options that can be set should be documented in this manual (see
|syntastic-checkers|).
------------------------------------------------------------------------------
5.4. Sorting errors *syntastic-config-sort*
*'syntastic_<filetype>_<checker>_sort'*
Syntastic may decide to group the errors produced by some checkers by file,
then sort them by line number, then by type, then by column number. If you'd
prefer to see the errors in the order in which they are output by the external
checker you can set the variable |'g:syntastic_<filetype>_<checker>_sort'| to 0.
Alternatively, if syntastic doesn't reorder the errors produced by a checker
but you'd like it to sort them, you can set the same variable to 1.
There is also a local version |'b:syntastic_<filetype>_<checker>_sort'| of
this variable, that takes precedence over it in the buffers where it is
defined.
For aggregated lists (see |syntastic-aggregating-errors|) these variables are
ignored if |'syntastic_sort_aggregated_errors'| is set (which is the default).
------------------------------------------------------------------------------
5.5. Filtering errors *syntastic-config-filtering*
*'syntastic_<filetype>_<checker>_quiet_messages'*
Finally, variables 'g:syntastic_<filetype>_<checker-name>_quiet_messages' can
be used to filter out some of the messages produced by specific checkers. The
effect is identical to that of |syntastic_quiet_messages|, except only messages
from the corresponding checkers are filtered. Example: >
let g:syntastic_python_pylama_quiet_messages = {
\ "type": "style",
\ "regex": '\m\[C03\d\d\]' }
<
The syntax is of course identical to that of |syntastic_quiet_messages|.
------------------------------------------------------------------------------
5.6. Debugging *syntastic-config-debug*
*syntastic-debug*
Syntastic can log a trace of its working to Vim's |message-history|. To verify
the command line constructed by syntastic to run a linter, set the variable
|'syntastic_debug'| to a non-zero value, run the checker, then run `:mes` to
display the messages, and look for "makeprg" in the output.
From a user's perspective, the useful values for |'syntastic_debug'| are 1, 3,
and 33:
1 - logs syntastic's workflow
3 - logs workflow, linter's output, and |location-list| manipulations
33 - logs workflow and checker-specific details (such as version checks).
Debug logs can be saved to a file; see |'syntastic_debug_file'| for details.
Setting |'syntastic_debug'| to 0 turns off logging.
------------------------------------------------------------------------------
5.7. Profiling *syntastic-profiling*
A very useful tool for debugging performance problems is Vim's built-in
|profiler|. In order to enable profiling for syntastic you need to add two lines
to your vimrc (not to gvimrc): >
profile start syntastic.log
profile! file */syntastic/*
<
(assuming your copy of syntastic lives in a directory creatively named
"syntastic"). These lines must be executed before syntastic is loaded, so you
need to put them before package managers such as "pathogen" or "Vundle", and
(in newer Vim versions) before any commands related to |packages|.
A log file is created in the current directory, and is updated when you quit
Vim.
==============================================================================
6. Notes *syntastic-notes*
------------------------------------------------------------------------------
6.1. Handling of composite filetypes *syntastic-composite*
Some Vim plugins use composite filetypes, such as "django.python" or
"handlebars.html". Normally syntastic deals with this situation by splitting
the filetype in its simple components, and calling all checkers that apply.
If this behaviour is not desirable, you can disable it by mapping the
composite filetypes to simple ones using |'syntastic_filetype_map'|, e.g.: >
let g:syntastic_filetype_map = { "handlebars.html": "handlebars" }
<
------------------------------------------------------------------------------
6.2. Editing files over network *syntastic-netrw*
The standard plugin |netrw| allows Vim to transparently edit files over
network and inside archives. Currently syntastic doesn't support this mode
of operation. It can only check files that can be accessed directly by local
linters, without any translation or conversion.
------------------------------------------------------------------------------
6.3. The 'shellslash' option *syntastic-shellslash*
The 'shellslash' option is relevant only on Windows systems. This option
determines (among other things) the rules for quoting command lines, and there
is no easy way for syntastic to make sure its state is appropriate for your
shell. It should be turned off if your 'shell' (or |'syntastic_shell'|) is
"cmd.exe", and on for shells that expect an UNIX-like syntax, such as Cygwin's
"sh". Most checkers will stop working if 'shellslash' is set to the wrong
value.
------------------------------------------------------------------------------
6.4. Saving Vim sessions *syntastic-sessions*
If you use `:mksession` to save Vim sessions you should probably make sure to
remove option "blank" from 'sessionoptions': >
set sessionoptions-=blank
<
This will prevent `:mksession` from saving |syntastic-error-window| as empty
quickfix windows.
------------------------------------------------------------------------------
6.5. The location list callback *syntastic-loclist-callback*
*SyntasticCheckHook()*
Syntastic also gives you direct access to the list of errors. A function
named |SyntasticCheckHook()| is called by syntastic (if it exists) right
before populating the |location-list| and enabling the notifiers. The function
takes exactly one argument, the list of errors in |location-list| format (see
|getqflist()| for details). format. You can do essentially anything with this
list, as long as you don't change its format, and you don't add or remove
elements.
For example the following function will make the error window smaller if fewer