Repository files navigation

               ,              / \,,_  .'|           ,{{| /}}}}/_.'            _____________________________________________          }}}}` '{{'  '.            /                                             \        {{{{{    _   ;, \          /            Ladies and Gentlemen,              \     ,}}}}}}    /o`\  ` ;)        |                                                |    {{{{{{   /           (        |                 this is ...                    |    }}}}}}   |            \       |                                                |   {{{{{{{{   \            \      |                                                |   }}}}}}}}}   '.__      _  |     |    _____             __             __  _      |   {{{{{{{{       /`._  (_\ /     |   / ___/__  ______  / /_____ ______/ /_(_)____ |    }}}}}}'      |    //___/   --=:   \__ \/ / / / __ \/ __/ __ `/ ___/ __/ / ___/ |jgs `{{{{`       |     '--'       |  ___/ / /_/ / / / / /_/ /_/ (__  ) /_/ / /__   |     }}}`                         | /____/\__, /_/ /_/\__/\__,_/____/\__/_/\___/   |                                  |      /____/                                    |                                  |                                               /                                   \_____________________________________________/

1. Deprecation note
2. Introduction
3. Installation
   3.1.Requirements
   3.2.Installing syntastic with Pathogen
4. Recommended settings
5. FAQ
   5.1.I installed syntastic but it isn't reporting any errors...
   5.2.Syntastic supports several checkers for my filetype, how do I tell it which one(s) to use?
   5.3.How can I run checkers for "foreign" filetypes against the current file?
   5.4.I have enabled multiple checkers for the current filetype. How can I display all errors from all checkers together?
   5.5.How can I pass additional arguments to a checker?
   5.6.I run a checker and the location list is not updated...
   5.6.I run:lopen or:lwindow and the error window is empty...
   5.7.How can I jump between the different errors without using the location list at the bottom of the window?
   5.8.The error window is closed automatically when I:quit the current buffer but not when I:bdelete it?
   5.9.My favourite checker needs to load a configuration file from the project's root rather than the current directory...
   5.10.What is the difference between syntax checkers and style checkers?
   5.11.How can I check scripts written for different versions of Python?
   5.12.How can I check scripts written for different versions of Ruby?
   5.13.Theperl checker has stopped working...
   5.14.What happened to therustc checker?
   5.15.What happened to thetsc checker?
   5.16.What happened to thexcrun checker?
   5.17.What happened to thevalac checker?
   5.18.What happened to the Julialint checker?
6. Resources

This project is no longer maintained. If you need a syntax checking pluginforVim you might be interested in Syntastic's spiritual succesor,ALE. Although it shares no code with syntastic and it takes a verydifferent approach to design,ALE can be considered a natural evolutionof syntastic in terms of goals and functionality. Check it out, you probablywon't be disappointed.

Syntastic is a syntax checking plugin forVim created byMartin Grenfell. It runs files through external syntax checkersand displays any resulting errors to the user. This can be done on demand, orautomatically as files are saved. If syntax errors are detected, the user isnotified and is happy because they didn't have to compile their code or executetheir script to find them.

At the time of this writing, syntastic has checking plugins for ACPISource Language, ActionScript, Ada, Ansible configurations, API Blueprint,AppleScript, AsciiDoc, Assembly languages, BEMHTML, Bro, Bourne shell, C, C++,C#, Cabal, Chef, CMake, CoffeeScript, Coco, Coq, CSS, Cucumber, CUDA, D, Dart,DocBook, Dockerfile, Dust, Elixir, Erlang, eRuby, Fortran, Gentoo metadata,GLSL, Go, Haml, Haskell, Haxe, Handlebars, HSS, HTML, Java, JavaScript, JSON,JSX, LESS, Lex, Limbo, LISP, LLVM intermediate language, Lua, Markdown,MATLAB, Mercury, NASM, Nix, Objective-C, Objective-C++, OCaml, Perl, PerlPOD, PHP, gettext Portable Object, Raku, OS X and iOS property lists, Pug(formerly Jade), Puppet, Python, QML, R, Racket, RDF TriG, RDF Turtle, RelaxNG, reStructuredText, RPM spec, Ruby, SASS/SCSS, Scala, Slim, SML, Solidity,Sphinx, SQL, Stylus, Tcl, TeX, Texinfo, Twig, TypeScript, Verilog, VHDL, Vimhelp, VimL, Vue.js, xHtml, XML, XSLT, XQuery, YACC, YAML, YANG data models,YARA rules, z80, Zope page templates, and Zsh. See themanual fordetails about the corresponding supported checkers (:help syntastic-checkersin Vim).

A number of third-party Vim plugins also provide checkers for syntastic, forexample:merlin,omnisharp-vim,rust.vim,syntastic-extras,syntastic-more,tsuquyomi,vim-crystal,vim-eastwood, andvim-swift.

Below is a screenshot showing the methods that Syntastic uses to display syntaxerrors. Note that, in practise, you will only have a subset of these methodsenabled.

1. Errors are loaded into the location list for the corresponding window.
2. When the cursor is on a line containing an error, the error message is echoed in the command window.
3. Signs are placed beside lines with errors - note that warnings are displayed in a different color.
4. There is a configurable statusline flag you can include in your statusline config.
5. Hover the mouse over a line containing an error and the error message is displayed as a balloon.
6. (not shown) Highlighting errors with syntax highlighting. Erroneous parts of lines can be highlighted.

Syntastic itself has rather relaxed requirements: it doesn't have any externaldependencies, and it needs a version ofVim compiled with a few commonfeatures:autocmd,eval,file_in_path,modify_fname,quickfix,reltime,statusline, anduser_commands. Not all possible combinations offeatures that include the ones above make equal sense on all operating systems,but Vim version 7 or later with the "normal", "big", or "huge" feature setsshould be fine.

Syntastic should work with any modern plugin managers for Vim, such asNeoBundle,Pathogen,Vim-Addon-Manager,Vim-Plug, orVundle. Instructions for installing syntasticwithPathogen are included below for completeness.

Starting with Vim version 7.4.1486 you can also load syntastic using thestandard mechanism of packages, without the help of third-party plugin managers(see:help packages in Vim for details). Beware however that, while supportfor packages has been added in Vim 7.4.1384, the functionality needed bysyntastic is present only in versions 7.4.1486 and later.

Last but not least: syntastic doesn't know how to do any syntax checks byitself. In order to get meaningful results you need to install externalcheckers corresponding to the types of files you use. Please consult themanual (:help syntastic-checkers in Vim) for a list of supportedcheckers.

If you already havePathogen working then skipStep 1 and go toStep 2.

First I'll show you how to install Tim Pope'sPathogen so that it's easy toinstall syntastic. Do this in your terminal so that you get thepathogen.vimfile and the directories it needs:

mkdir -p~/.vim/autoload~/.vim/bundle&& \curl -LSso~/.vim/autoload/pathogen.vim https://tpo.pe/pathogen.vim

Next youneed to add this to your~/.vimrc:

executepathogen#infect()

You now have pathogen installed and can put syntastic into~/.vim/bundle likethis:

cd~/.vim/bundle&& \git clone --depth=1 https://github.com/vim-syntastic/syntastic.git

Quit vim and start it back up to reload it, then type:

:Helptags

If you get an error when you do this, then you probably didn't installPathogen right. Go back toStep 1 and make sure you did thefollowing:

1. Created both the~/.vim/autoload and~/.vim/bundle directories.
2. Added theexecute pathogen#infect() line to your~/.vimrc file
3. Did thegit clone of syntastic inside~/.vim/bundle
4. Have permissions to access all of these directories.

Syntastic has numerous options that can be configured, and the defaultsare not particularly well suitable for new users. It is recommendedthat you start by adding the following lines to yourvimrc file, andreturn to them after reading the manual (see:help syntastic in Vim):

setstatusline+=%#warningmsg#setstatusline+=%{SyntasticStatuslineFlag()}setstatusline+=%*letg:syntastic_always_populate_loc_list=1letg:syntastic_auto_loc_list=1letg:syntastic_check_on_open=1letg:syntastic_check_on_wq=0

5.1. Q. I installed syntastic but it isn't reporting any errors...

A. The most likely reason is that none of the syntax checkers that it requiresare installed. For example: by default, python requires eitherflake8 orpylint to be installed and in your$PATH. Read themanual(:help syntastic-checkers in Vim) to find out what executables aresupported. Note that aliases do not work; the actual executables must beavailable in your$PATH. Symbolic links are okay though. You can seesyntastic's idea of available checkers by running:SyntasticInfo.

A second probable reason is that none of the available checkers areenabled. Syntastic comes preconfigured with a default list of enabled checkersper filetype, but this list is kept short in order to prevent slowing down Vimor trying to run conflicting checks. The command:SyntasticInfo will show youwhich checkers are enabled. You can tell syntastic which checkers (among theavailable ones) you want to run by settingg:syntastic_<filetype>_checkers inyourvimrc (seebelow).

A third possible reason is that the$PATH seen by syntastic might not be sameas the$PATH in your login shell. Syntastic runs checkers using the shellpointed to by Vim'sshell (or byg:syntastic_shell, if set), and that's theshell you need to configure to set the proper$PATH and environment variablesfor your checkers. You can see syntastic's idea of$PATH by running

:echosyntastic#util#system('echo "$PATH"')

on UNIX and Mac OS-X systems, or

:echosyntastic#util#system('echo %PATH%')

on Windows.

Finally, another reason it could fail is that either the command line optionsor the error output for a syntax checker may have changed. In this case, makesure you have the latest version of the syntax checker installed. If it stillfails then post anissue - or better yet, create a pull request.

5.2. Q. Syntastic supports several checkers for my filetype, how do I tell itwhich one(s) to use?

A. Add a line like this to yourvimrc:

letg:syntastic_<filetype>_checkers= ['<checker-name>']

To see the list of supported checkers for your filetype read themanual (:help syntastic-checkers in Vim).

For example, Python has the following checkers, among others:flake8,pyflakes,pylint and a nativepython checker. To tell syntastic to usepylint, you would use this setting:

letg:syntastic_python_checkers= ['pylint']

Checkers can be chained together like this:

letg:syntastic_php_checkers= ['php','phpcs','phpmd']

This is telling syntastic to run thephp checker first, and if no errors arefound, runphpcs, and thenphpmd.

You can also run checkers explicitly by calling:SyntasticCheck <checker>.For example to runphpcs andphpmd:

:SyntasticCheck phpcs phpmd

This works for any checkers available for the current filetype, even if theyaren't listed ing:syntastic_<filetype>_checkers.

5.3. Q. How can I run checkers for "foreign" filetypes against the currentfile?

A. You need to qualify the name of the "foreign" checker with the nameof its filetype. For example to checktex files with the checkerlanguage_check (which normally acts only on files of typetext), you canaddtext/language_check to the list fo checkers fortex:

letg:syntastic_tex_checkers= ['lacheck','text/language_check']

This also works with:SyntasticCheck, e.g. the following command runstext/language_check against the current file regardless of the currentfiletype:

:SyntasticCheck text/language_check

Of course, the checkers specified this way need to be known to syntastic, andthey need to be shown as available when you run:SyntasticInfo. You can'tjust make up a combination of a filetype and a program name and expect it towork as a checker.

5.4. Q. I have enabled multiple checkers for the current filetype. How can Idisplay all errors from all checkers together?

A. Setg:syntastic_aggregate_errors to 1 in yourvimrc:

letg:syntastic_aggregate_errors=1

See:help syntastic-aggregating-errors for more details.

5.5. Q. How can I pass additional arguments to a checker?

A. In most cases a command line is constructed using an internal functionnamedmakeprgBuild(), which provides a number of options that allow you tocustomise every part of the command that gets run. You can set these optionsusing global variables.

The general form of the globalargs variable issyntastic_<filetype>_<checker>_args. Thus if you wanted to pass--my --args --here to the Rubymri checker you would add this line to yourvimrc:

letg:syntastic_ruby_mri_args="--my --args --here"

See:help syntastic-checker-options for more information.

A number of checkers don't use themakeprgBuild() function mentioned above,or have additional options that can be configured. For these checkers the exactlist of options should be included in themanual(:help syntastic-checkers in Vim).

5.6. Q. I run a checker and the location list is not updated...
5.6. Q. I run:lopen or:lwindow and the error window is empty...

A. By default the location list is changed only when you run the:Errorscommand, in order to minimise conflicts with other plugins. If you want thelocation list to always be updated when you run the checkers, add this line toyourvimrc:

letg:syntastic_always_populate_loc_list=1

5.7. Q. How can I jump between the different errors without using the locationlist at the bottom of the window?

A. Vim provides several built-in commands for this. See:help :lnext and:help :lprevious.

If you use these commands a lot then you may want to add shortcut mappings toyourvimrc, or install something likeunimpaired, which provides suchmappings (among other things).

5.8. Q. The error window is closed automatically when I:quit the current bufferbut not when I:bdelete it?

A. There is no safe way to handle that situation automatically, but you canwork around it:

nnoremap<silent><C-d>:lclose<CR>:bdelete<CR>cabbrev<silent>bd<C-r>=(getcmdtype()==#':'&&getcmdpos()==1 ?'lclose\|bdelete' :'bd')<CR>

5.9. My favourite checker needs to load a configuration file from theproject's root rather than the current directory...

A. You can set up anautocmd to search for the configuration file in thecurrent directory and upwards, and add it to the checker's options when found.For example forjscs:

function!FindConfig(prefix, what, where)let cfg=findfile(a:what,escape(a:where,'') .';')return cfg!=#'' ?'' .a:prefix .'' .shellescape(cfg) :''endfunctionautocmdFileTypejavascriptletb:syntastic_javascript_jscs_args=\get(g:,'syntastic_javascript_jscs_args','') .\FindConfig('-c','.jscsrc',expand('<afile>:p:h',1))

5.10. Q. What is the difference between syntax checkers and style checkers?

A. The errors and warnings they produce are highlighted differently and canbe filtered by different rules, but otherwise the distinction is pretty mucharbitrary. There is an ongoing effort to keep things consistent, so you cangenerally expect messages produced by syntax checkers to bemostly relatedto syntax, and messages produced by style checkers to bemostly about style.But there can be no formal guarantee that, say, a style checker that runs intoa syntax error wouldn't die with a fatal message, nor that a syntax checkerwouldn't give you warnings against using some constructs as being bad practice.There is also no guarantee that messages marked asstyle are less severe thanthe ones marked assyntax (whatever that might mean). And there are even afew Frankenstein checkers (for exampleflake8 andpylama) that, by theirnature, produce both kinds of messages. Syntastic is not smart enough to beable to sort out these things by itself.

Generally it's more useful to look at this from the perspective of filteringunwanted messages, rather than as an indicator of severity levels. Thedistinction between syntax and style is orthogonal to the distinction betweenerrors and warnings, and thus you can turn off messages based on level, ontype, or both.

e.g. To disable all style messages:

letg:syntastic_quiet_messages= {"type":"style" }

See:help syntastic_quiet_messages for more information.

5.11. Q. How can I check scripts written for different versions of Python?

A. Install a Python version manager such asvirtualenvorpyenv, activate the environment for the relevant versionof Python, and install in it the checkers you want to use. Setg:syntastic_python_checkers accordingly in yourvimrc, and runVimfrom the virtual environment.

If you're starting Vim from a desktop manager rather than from a terminal youmight need to write wrapper scripts around your checkers, to activate thevirtual environment before running the actual checks. Then you'll need topoint the relevantg:syntastic_python_<checker>_exec variables to the wrapperscripts.

5.12. Q. How can I check scripts written for different versions of Ruby?

A. Install a Ruby version manager such asrvm orrbenv,activate the relevant version of Ruby, and install in it the checkers you wantto use. Setg:syntastic_ruby_checkers accordingly in yourvimrc, and runVim under the relevant Ruby version.

If you're starting Vim from a desktop manager rather than from a terminaland depending on the version manager you use you might need to write wrapperscripts around your checkers, to activate the relevant version of Rubybefore running the actual checks. Then you'll need to point the relevantg:syntastic_ruby_<checker>_exec variables to the wrapper scripts.

5.13. Q. Theperl checker has stopped working...

A. Theperl checker runsperl -c against your file, which in turnexecutes anyBEGIN,UNITCHECK, andCHECK blocks, and anyusestatements in your file (cf.perlrun). This is probably fine if youwrote the file yourself, but it's a security problem if you're checkingthird-party files. Since there is currently no way to disable this behaviourwhile still producing useful results, the checker is now disabled by default.To (re-)enable it, make sure theg:syntastic_perl_checkers list includesperl, and setg:syntastic_enable_perl_checker to 1 in yourvimrc:

letg:syntastic_enable_perl_checker=1

5.14. Q. What happened to therustc checker?

A. It is now part of therust.vim plugin. If you install this plugin thechecker should be picked up automatically by syntastic.

5.15. Q. What happened to thetsc checker?

A. It didn't meet people's expectations and it has been removed. The plugintsuquyomi comes packaged with a checker for TypeScript. If youinstall this plugin the checker should be picked up automatically by syntastic.

5.16. Q. What happened to thexcrun checker?

A. Thexcrun checker used to have a security problem and it has been removed.A better checker forSwift is part of thevim-swift plugin. If youinstall this plugin the checker should be picked up automatically by syntastic.

5.17. Q. What happened to thevalac checker?

A. It is now part of thevala.vim plugin. If you install this plugin thechecker should be picked up automatically by syntastic.

5.18. Q. What happened to the Julialint checker?

A. It was removed, since theLint.jl packagehas been deprecatedand no longer works with recent Julia versions.

The preferred place for posting suggestions, reporting bugs, and generaldiscussions related to syntastic is theissue tracker at GitHub.A guide for writing syntax checkers can be found in thewiki.There are also a dedicatedgoogle group, and asyntastic tag at StackOverflow.

Syntastic aims to provide a common interface to syntax checkers for as manylanguages as possible. For particular languages, there are, of course, otherplugins that provide more functionality than syntastic. You might want to takea look atghcmod-vim,jedi-vim,python-mode,vim-go, orYouCompleteMe.