*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 than 10 errors are found: > function! SyntasticCheckHook(errors) if !empty(a:errors) let g:syntastic_loc_list_height = min([len(a:errors), 10]) endif endfunction < (Please keep in mind however that Vim options |winheight| and |winminheight| also affect window sizes.) ============================================================================== 7. Compatibility with other software *syntastic-compatibility* ------------------------------------------------------------------------------ 7.1. airline *syntastic-airline* The "airline" Vim plugin (https://github.com/vim-airline/vim-airline) comes with an extension for showing syntastic-related flags on the |'statusline'|. "airline" versions v0.8 and earlier use |'syntastic_stl_format'| to format the |'statusline'| flags. Newer versions ignore |'syntastic_stl_format'|, and require you to set variables 'airline#extensions#syntastic#stl_format_err' and 'airline#extensions#syntastic#stl_format_warn' separately for errors and warnings (with the same syntax as |'syntastic_stl_format'|) if you want to change the flags from the defaults. When using "airline" you should NOT follow the recommendation outlined in the |syntastic-statusline-flag| section above to modify your |'statusline'|. "airline" shall make all necessary changes automatically. ------------------------------------------------------------------------------ 7.2. The csh and tcsh shells *syntastic-csh* The "csh" and "tcsh" shells are mostly compatible with syntastic. However, some checkers assume Bourne shell syntax for redirecting "stderr". For this reason, you should point |'syntastic_shell'| to a Bourne-compatible shell, such as "zsh", "bash", "ksh", or even the original Bourne "sh": > let g:syntastic_shell = "/bin/sh" < ------------------------------------------------------------------------------ 7.3. EasyGrep *syntastic-easygrep* The "EasyGrep" Vim plugin (https://github.com/dkprice/vim-easygrep) can use either |quickfix| lists, or location lists (see |location-list|). Syntastic can be run along with "EasyGrep" provided that the latter is configured to use |quickfix| lists (which is the default at the time of this writing): > let g:EasyGrepWindow = 0 < ------------------------------------------------------------------------------ 7.4. Eclim *syntastic-eclim* Syntastic can be used together with "Eclim" (see http://eclim.org/). However, by default Eclim disables syntastic's checks for the filetypes it supports, in order to run its own validation. If you'd prefer to use Eclim but still run syntastic's checks, set |g:EclimFileTypeValidate| to 0: > let g:EclimFileTypeValidate = 0 < It is also possible to re-enable syntastic checks only for some filetypes, and run Eclim's validation for others. Please consult Eclim's documentation for details. ------------------------------------------------------------------------------ 7.5. ferret *syntastic-ferret* At the time of this writing syntastic conflicts with the "ferret" Vim plugin (https://github.com/wincent/ferret). The "ferret" plugin assumes control over loclist windows even when configured to use |quickfix| lists. This interferes with syntastic's functioning. ------------------------------------------------------------------------------ 7.6. The fish shell *syntastic-fish* At the time of this writing the "fish" shell (see http://fishshell.com/) doesn't support the standard UNIX syntax for file redirections, and thus it can't be used together with syntastic. You can however set |'syntastic_shell'| to a more traditional shell, such as "zsh", "bash", "ksh", or even the original Bourne "sh": > let g:syntastic_shell = "/bin/sh" < ------------------------------------------------------------------------------ 7.7. The fizsh shell *syntastic-fizsh* Using syntastic with the "fizsh" shell (see https://github.com/zsh-users/fizsh) is possible, but potentially problematic. In order to do it you'll need to set 'shellredir' like this: > set shellredir=>%s\ 2>&1 < Please keep in mind however that Vim can't take advantage of any of the interactive features of "fizsh". Using a more traditional shell such as "zsh", "bash", "ksh", or the original Bourne "sh" might be a better choice: > let g:syntastic_shell = "/bin/sh" < ------------------------------------------------------------------------------ 7.8. flagship *syntastic-flagship* The "flagship" Vim plugin (https://github.com/tpope/vim-flagship) has its own mechanism of showing flags on the |'statusline'|. To allow "flagship" to manage syntastic's statusline flag add the following |autocommand| to your vimrc, rather than explicitly adding the flag to your |'statusline'| as described in the |syntastic-statusline-flag| section above: > autocmd User Flags call Hoist("window", "SyntasticStatuslineFlag") < ------------------------------------------------------------------------------ 7.9. powerline *syntastic-powerline* The "powerline" Vim plugin (https://github.com/powerline/powerline) comes packaged with a syntastic segment. To customize this segment create a file "~/.config/powerline/themes/vim/default.json", with a content like this: > { "segment_data" : { "powerline.segments.vim.plugin.syntastic.syntastic" : { "args" : { "err_format" : "Err: {first_line} #{num} ", "warn_format" : "Warn: {first_line} #{num} " } } } } < ------------------------------------------------------------------------------ 7.10. The PowerShell shell *syntastic-powershell* At the time of this writing syntastic is not compatible with using "PowerShell" (https://msdn.microsoft.com/en-us/powershell) as Vim's 'shell'. You may still run Vim from "PowerShell", but you do have to point Vim's 'shell' to a more traditional program, such as "cmd.exe" on Windows, or "/bin/sh" on UNIX: > set shell=c:\Windows\system32\cmd.exe set shell=/bin/sh < ------------------------------------------------------------------------------ 7.11. python-mode *syntastic-pymode* Syntastic can be used along with the "python-mode" Vim plugin (see https://github.com/klen/python-mode). However, they both run syntax checks by default when you save buffers to disk, and this is probably not what you want. To avoid both plugins opening error windows, you can either set passive mode for python in syntastic (see |'syntastic_mode_map'|), or disable lint checks in "python-mode", by setting |pymode_lint_on_write| to 0. E.g.: > let g:pymode_lint_on_write = 0 < ------------------------------------------------------------------------------ 7.12. vim-auto-save *syntastic-vim-auto-save* Syntastic can be used together with the "vim-auto-save" Vim plugin (see https://github.com/907th/vim-auto-save). However, syntastic checks in active mode only work with "vim-auto-save" version 0.1.7 or later. ------------------------------------------------------------------------------ 7.13. vim-go *syntastic-vim-go* Syntastic can be used along with the "vim-go" Vim plugin (see https://github.com/fatih/vim-go). However, both "vim-go" and syntastic run syntax checks by default when you save buffers to disk. To avoid conflicts, you have to either set passive mode in syntastic for the "go" filetype (see |syntastic_mode_map|), or prevent "vim-go" from showing a quickfix window when |g:go_fmt_command| fails, by setting |g:go_fmt_fail_silently| to 1. E.g.: > let g:go_fmt_fail_silently = 1 < "vim-go" version 1.4 and earlier always uses |quickfix| lists. Starting with version 1.5, "vim-go" can also use location lists (see |location-list|). To avoid conflicts with syntastic, you probably want to configure "vim-go" to stick with |quickfix| lists: > let g:go_list_type = "quickfix" < ------------------------------------------------------------------------------ 7.14. vim-virtualenv *syntastic-vim-virtualenv* At the time of this writing, syntastic can't run linters installed in Python virtual environments activated by "vim-virtualenv" (see https://github.com/jmcantrell/vim-virtualenv). This is a limitation of "vim-virtualenv". ------------------------------------------------------------------------------ 7.15. YouCompleteMe *syntastic-ycm* Syntastic can be used together with the "YouCompleteMe" Vim plugin (see https://github.com/ycm-core/YouCompleteMe). However, by default "YouCompleteMe" disables syntastic's checkers for the "c", "cpp", "objc", and "objcpp" filetypes, in order to allow its own checkers to run. If you want to use YCM's identifier completer but still run syntastic's checkers for those filetypes you have to set |g:ycm_show_diagnostics_ui| to 0. E.g.: > let g:ycm_show_diagnostics_ui = 0 < ------------------------------------------------------------------------------ 7.16. The zsh shell and MacVim *syntastic-zsh* If you're running MacVim together with the "zsh" shell (http://www.zsh.org/) you need to be aware that MacVim does not source your .zshrc file, but will source a .zshenv file. Consequently you have to move any setup steps relevant to the linters you're using from .zshrc to .zshenv, otherwise your linters will misbehave when run by syntastic. This is particularly important for programs such as "rvm" (https://rvm.io/) or "rbenv" (http://rbenv.org/), that rely on setting environment variables. ============================================================================== 8. About *syntastic-about* The core maintainers of syntastic are: Martin Grenfell (GitHub: scrooloose) Gregor Uhlenheuer (GitHub: kongo2002) LCD 047 (GitHub: lcd047) Find the latest version of syntastic at: http://github.com/vim-syntastic/syntastic ============================================================================== 9. License *syntastic-license* Syntastic is released under the WTFPL. See http://sam.zoy.org/wtfpl/COPYING. vim:tw=78:sw=4:ft=help:norl: