Repository files navigation

ALE (Asynchronous Lint Engine) is a plugin providing linting (syntax checkingand semantic errors) in Neovim 0.7.0+ and Vim 8.0+ while you edit your text files,and acts as a VimLanguage Server Protocol client.

ALE makes use of Neovim and Vim 8 job control functions and timers torun linters on the contents of text buffers and return errors astext is changed in Vim. This allows for displaying warnings anderrors in files being edited in Vim before files have been savedback to a filesystem.

In other words, this plugin allows you to lint while you type.

ALE offers support for fixing code with command line tools in a non-blockingmanner with the:ALEFix feature, supporting tools in many languages, likeprettier,eslint,autopep8, and more.

ALE acts as a "language client" to support a variety of Language Server Protocolfeatures, including:

• Diagnostics (via Language Server Protocol linters)
• Go To Definition (:ALEGoToDefinition)
• Completion (Built in completion support, or with Deoplete)
• Finding references (:ALEFindReferences)
• Hover information (:ALEHover)
• Symbol search (:ALESymbolSearch)

If you don't care about Language Server Protocol, ALE won't load any of the codefor working with it unless needed. One of ALE's general missions is that youwon't pay for the features that you don't use.

Help Wanted: If you would like to help maintain this plugin by managing themany issues and pull requests that are submitted, please send the author anemail atdev@w0rp.com.

If you enjoy this plugin, feel free to contribute or check out the author'sother content atw0rp.com.

ALE has been around for many years, and there are many ways to run asynchronouslinting and fixing of code in Vim. ALE offers the following.

• No dependencies for ALE itself
• Lightweight plugin architecture (No JavaScript or Python required)
• Low memory footprint
• Runs virtually everywhere, including remote shells, and ingit commit
• Out of the box support for running particular linters and language servers
• Near-zero configuration with custom code for better defaults
• Highly customizable and well-documented (:help ale-options)
• Breaking changes for the plugin are extremely rare
• Integrates with Neovim's LSP client (0.8+) and diagnostics (0.7+)
• Support for older Vim and Neovim versions
• Windows support
• Well-integrated with other plugins

If you would like to donate to Dense Analysis to say thank you for ALE, pleaseconsider visiting ourSponsorship page.Funds will be used to pay for our hosting fees and research. Whilst visiting oursite, please feel free to make use of our educational resources and otherrecommended tools.

ALE supports a wide variety of languages and tools. See thefull list in theSupported Languages and Tools page.

Once this plugin is installed, while editing your files in supportedlanguages and tools which have been correctly installed,this plugin will send the contents of your text buffers to a variety ofprograms for checking the syntax and semantics of your programs. By default,linters will be re-run in the background to check your syntax when you opennew buffers or as you make edits to your files.

The behavior of linting can be configured with a variety of options,documented inthe Vim help file. For more information on theoptions ALE offers, consult:help ale-options for global options and:help ale-integration-options for options specified to particular linters.

ALE can fix files with theALEFix command. Functions need to be configuredeither in each buffer with ab:ale_fixers, or globally withg:ale_fixers.

The recommended way to configure fixers is to define a List in an ftplugin file.

" In ~/.vim/ftplugin/javascript.vim, or somewhere similar." Fix files with prettier, and then ESLint.letb:ale_fixers= ['prettier','eslint']" Equivalent to the above.letb:ale_fixers= {'javascript': ['prettier','eslint']}

You can also configure your fixers from vimrc usingg:ale_fixers, before orafter ALE has been loaded.

A* in place of the filetype will apply a List of fixers to all files whichdo not match some filetype in the Dictionary.

Note that using a plain List forg:ale_fixers is not supported.

" In ~/.vim/vimrc, or somewhere similar.letg:ale_fixers= {\'*': ['remove_trailing_lines','trim_whitespace'],\'javascript': ['eslint'],\}

If you want to automatically fix files when you save them, you need to turna setting on in vimrc.

" Set this variable to 1 to fix files when you save them.letg:ale_fix_on_save=1

The:ALEFixSuggest command will suggest some supported tools for fixing code.Bothg:ale_fixers andb:ale_fixers can also accept functions, includinglambda functions, as fixers, for fixing files with custom tools.

See:help ale-fix for complete information on how to fix files with ALE.

ALE offers some support for completion via hijacking of omnicompletion while youtype. All of ALE's completion information must come from Language ServerProtocol linters, or fromtsserver for TypeScript.

When running ALE in Neovim 0.8+, ALE will integrate with Neovim's LSP client bydefault, and any auto-completion plugin that uses the native LSP client willwork when ALE runs language servers.nvim-cmp is recommended as acompletion plugin worth trying in Neovim.

ALE integrates withDeoplete as acompletion source, named'ale'. You can configure Deoplete to only use ALE asthe source of completion information, or mix it with other sources.

" Use ALE and also some plugin 'foobar' as completion sources for all code.calldeoplete#custom#option('sources', {\'_': ['ale','foobar'],\})

ALE also offers its own automatic completion support, which does not require anyother plugins, and can be enabled by changing a setting before ALE is loaded.

" Enable completion where available." This setting must be set before ALE is loaded."" You should not turn this setting on if you wish to use ALE as a completion" source for other completion plugins, like Deoplete.letg:ale_completion_enabled=1

ALE provides an omni-completion function you can use for triggeringcompletion manually with<C-x><C-o>.

setomnifunc=ale#completion#OmniFunc

ALE supports automatic imports from external modules. This behavior is enabledby default and can be disabled by setting:

letg:ale_completion_autoimport=0

Note that disabling auto import can result in missing completion items from someLSP servers (e.g. eclipselsp). See:help ale-completion for more information.

ALE supports jumping to the definition of words under your cursor with the:ALEGoToDefinition command using any enabled Language Server Protocol lintersandtsserver. In Neovim 0.8+, you can also use Neovim's built ingd keybindand more.

See:help ale-go-to-definition for more information.

ALE supports finding references for words under your cursor with the:ALEFindReferences command using any enabled Language Server Protocol lintersandtsserver.

See:help ale-find-references for more information.

ALE supports "hover" information for printing brief information about symbols atthe cursor taken from Language Server Protocol linters andtsserver with theALEHover command.

Truncated information will be displayed when the cursor rests on a symbol bydefault, as long as there are no problems on the same line.

The information can be displayed in aballoon tooltip in Vim or GVim byhovering your mouse over symbols. Mouse hovering is enabled by default in GVim,and needs to be configured for Vim 8.1+ in terminals.

See:help ale-hover for more information.

ALE supports searching for workspace symbols via Language Server Protocollinters with theALESymbolSearch command.

Search queries can be performed to find functions, types, and more which aresimilar to a given query string.

See:help ale-symbol-search for more information.

ALE supports renaming symbols in code such as variables or classnames with theALERename command.

ALEFileRename will rename file and fix import paths (tsserveronly).

ALECodeAction will execute actions on the cursor or applied to a visualrange selection, such as automatically fixing errors.

See:help ale-refactor for more information.

Add ALE to your runtime path in the usual ways.

If you have trouble reading:help ale, try the following.

packloadall |silent!helptagsALL

mkdir -p~/.vim/pack/git-plugins/startgit clone --depth 1 https://github.com/dense-analysis/ale.git~/.vim/pack/git-plugins/start/ale

mkdir -p~/.local/share/nvim/site/pack/git-plugins/startgit clone --depth 1 https://github.com/dense-analysis/ale.git~/.local/share/nvim/site/pack/git-plugins/start/ale

# Run these commands in the "Git for Windows" Bash terminalmkdir -p~/vimfiles/pack/git-plugins/startgit clone --depth 1 https://github.com/dense-analysis/ale.git~/vimfiles/pack/git-plugins/start/ale

Plug'dense-analysis/ale'

Plugin'dense-analysis/ale'

git clone https://github.com/dense-analysis/ale~/.vim/bundle/ale

{'dense-analysis/ale',config=function()-- Configuration goes here.localg=vim.gg.ale_ruby_rubocop_auto_correct_all=1g.ale_linters= {ruby= {'rubocop','ruby'},lua= {'lua_language_server'}        }end}

If you would like to see support for more languages and tools, pleasecreate an issueorcreate a pull request.If your tool can read from stdin or you have code to suggest which is good,support can be happily added for it.

If you are interested in the general direction of the project, check out thewiki home page. The wiki includesa Roadmap for the future, and more.

If you'd liked to discuss ALE and more check out the Dense Analysis Discordserver here:https://discord.gg/5zFD6pQxDk

By default, all available tools for all supported languages will be run. If youwant to only select a subset of the tools, you can defineb:ale_linters for asingle buffer, org:ale_linters globally.

The recommended way to configure linters is to define a List in an ftpluginfile.

" In ~/.vim/ftplugin/javascript.vim, or somewhere similar." Enable ESLint only for JavaScript.letb:ale_linters= ['eslint']" Equivalent to the above.letb:ale_linters= {'javascript': ['eslint']}

You can also declare which linters you want to run in your vimrc file, before orafter ALE has been loaded.

" In ~/.vim/vimrc, or somewhere similar.letg:ale_linters= {\'javascript': ['eslint'],\}

For all languages unspecified in the dictionary, all possible linters willbe run for those languages, just as when the dictionary is not defined.Running many linters should not typically obstruct editing in Vim,as they will all be executed in separate processes simultaneously.

If you don't want ALE to run anything other than what you've explicitly askedfor, you can setg:ale_linters_explicit to1.

" Only run linters named in ale_linters settings.letg:ale_linters_explicit=1

This plugin will look for linters in theale_linters directory.Each directory within corresponds to a particular filetype in Vim, and each filein each directory corresponds to the name of a particular linter.

Warnings and errors should be configured in project configuration files for therelevant tools. ALE supports disabling only warnings relating to trailingwhitespace, which Vim users often fix automatically.

" Disable whitespace warningsletg:ale_warn_about_trailing_whitespace=0

Users generally should not ignore warnings or errors in projects by changingsettings in their own editor. Instead, configure tools appropriately so anyother user of the same project will see the same problems.

Run the following to see what is currently configured:

:ALEInfo

By default, ALE displays errors and warnings with virtual text. The problems ALEshows appear with comment-like syntax after every problem found. You can set ALEto only show problems where the cursor currently lies like so.

letg:ale_virtualtext_cursor='current'

If you want to disable virtual text completely, apply the following.

letg:ale_virtualtext_cursor='disabled'

Use these options to specify what text should be used for signs:

letg:ale_sign_error='>>'letg:ale_sign_warning='--'

ALE sets some background colors automatically for warnings and errorsin the sign gutter, with the namesALEErrorSign andALEWarningSign.These colors can be customised, or even removed completely:

highlightclear ALEErrorSignhighlightclear ALEWarningSign

You can configure the sign gutter open at all times, if you wish.

letg:ale_sign_column_always=1

ALE's highlights problems with highlight groups which link toSpellBad,SpellCap,error, andtodo groups by default. The characters that arehighlighted depend on the linters being used, and the information provided toALE.

Highlighting can be disabled completely by settingg:ale_set_highlights to0.

" Set this in your vimrc file to disabling highlightingletg:ale_set_highlights=0

You can control all of the highlights ALE uses, say if you are using a differentcolor scheme which produces ugly highlights. For example:

highlight ALEWarning ctermbg=DarkMagenta

See:help ale-highlights for more information.

There are 3 global options that allow customizing the echoed message.

• g:ale_echo_msg_format where:
  • %s is the error message itself
  • %...code...% is an optional error code, and most characters can bewritten between the% characters.
  • %linter% is the linter name
  • %severity% is the severity type
• g:ale_echo_msg_error_str is the string used for error severity.
• g:ale_echo_msg_warning_str is the string used for warning severity.

So for example this:

letg:ale_echo_msg_error_str='E'letg:ale_echo_msg_warning_str='W'letg:ale_echo_msg_format='[%linter%] %s [%severity%]'

Will give you:

See:help g:ale_echo_msg_format for more information.

lightline does not have built-insupport for ALE, nevertheless there is a plugin that adds this functionality:maximbaz/lightline-ale.

For more information, check out the sources of that plugin,:help ale#statusline#Count() andlightline documentation.

vim-airline integrates with ALEfor displaying error information in the status bar. If you want to see thestatus for ALE in a nice format, it is recommended to use vim-airline with ALE.The airline extension can be enabled by adding the following to your vimrc:

" Set this. Airline will handle the rest.letg:airline#extensions#ale#enabled=1

You can implement your own statusline function without adding any other plugins.ALE provides some functions to assist in this endeavour, including:

• ale#statusline#Count: Which returns the number of problems found by ALEfor a specified buffer.
• ale#statusline#FirstProblem: Which returns a dictionary containing thefull loclist details of the first problem of a specified type found by ALEin a buffer. (e.g. The first style warning in the current buffer.)This can be useful for displaying more detailed information such as theline number of the first problem in a file.

Say you want to display all errors as one figure, and all non-errors as anotherfigure. You can do the following:

function!LinterStatus()abortletl:counts=ale#statusline#Count(bufnr(''))letl:all_errors=l:counts.error+l:counts.style_errorletl:all_non_errors=l:counts.total-l:all_errorsreturnl:counts.total==0 ?'OK' :printf(\'%dW %dE',\  all_non_errors,\  all_errors\)endfunctionsetstatusline=%{LinterStatus()}

See:help ale#statusline#Count() or:help ale#statusline#FirstProblem()for more information.

Borders for floating preview windows are enabled by default. You can use theg:ale_floating_window_border setting to configure them.

You could disable the border with an empty list.

letg:ale_floating_window_border= []

If the terminal supports Unicode, you might try setting the value like below, tomake it look nicer.

letg:ale_floating_window_border= ['│','─','╭','╮','╯','╰','│','─']

Since vim's default uses nice Unicode characters when possible, you can trickale into using that default with

letg:ale_floating_window_border=repeat([''],8)

ALE takes advantage of the power of various tools to check your code. This ofcourse means that CPU time will be used to continuously check your code. If youare concerned about the CPU time ALE will spend, which will of course implysome cost to battery life, you can adjust your settings to make your CPU doless work.

First, consider increasing the delay before which ALE will run any linterswhile you type. ALE uses a timeout which is cancelled and reset every time youtype, and this delay can be increased so linters are run less often. See:help g:ale_lint_delay for more information.

If you don't wish to run linters while you type, you can disable that behavior.Setg:ale_lint_on_text_changed tonever. You won't get as frequent errorchecking, but ALE shouldn't block your ability to edit a document after you savea file, so the asynchronous nature of the plugin will still be an advantage.

If you are still concerned, you can turn the automatic linting off altogether,including the optiong:ale_lint_on_enter, and you can run ALE manually with:ALELint.

ALE offers an API for letting any other plugin integrate with ALE. If you areinterested in writing an integration, see:help ale-lint-other-sources.

If you're running ALE in Neovim withnvim-lspconfig for configuringparticular language servers, ALE will automatically disable its LSPfunctionality for any language servers configured with nvim-lspconfig bydefault. The following setting is applied by default:

letg:ale_disable_lsp='auto'

If you are running ALE in combination with another LSP client, you may wish todisable ALE's LSP functionality entirely. You can change the setting to1 toalways disable all LSP functionality.

letg:ale_disable_lsp=1

You can also useb:ale_disable_lsp in your ftplugin files to enable or disableLSP features in ALE for different filetypes.

If you are running Neovim 0.7 or later, you can make ALE display errors andwarnings via the Neovim diagnostics API.

letg:ale_use_neovim_diagnostics_api=1

coc.nvim is a popular Vim plugin writtenin TypeScript and dependent on thenpm ecosystem forproviding full IDE features to Vim. Both ALE and coc.nvim implementLanguage Server Protocol(LSP) clients for supporting diagnostics (linting with a live server), and otherfeatures like auto-completion, and others listed above.

ALE is primarily focused on integrating with external programs through virtuallyany means, provided the plugin remains almost entirely written in Vim script.coc.nvim is primarily focused on bringing IDE features to Vim. If you want torun external programs on your files to check for errors, and also use the mostadvanced IDE features, you might want to use both plugins at the same time.

The easiest way to get both plugins to work together is to configure coc.nvim tosend diagnostics to ALE, so ALE controls how all problems are presented to you,and to disable all LSP features in ALE, so ALE doesn't try to provide LSPfeatures already provided by coc.nvim, such as auto-completion.

Open your coc.nvim configuration file with:CocConfig and add"diagnostic.displayByAle": true to your settings.

vim-lsp is a popular plugin asimplementation of Language Server Protocol (LSP) client for Vim. It providesall the LSP features including auto completion, diagnostics, go to definitions,etc.

vim-lsp-ale is a bridge plugin to solvethe problem when using both ALE and vim-lsp. With the plugin, diagnostics areprovided by vim-lsp and ALE can handle all the errors. Please readvim-lsp-ale's documentationfor more details.

ALE runs its ownautocmdevents when a lint or fix cycle are started and stopped. There is also an eventthat runs when a linter job has been successfully started. These events can beused to call arbitrary functions during these respective parts of the ALE'soperation.

augroupYourGroupautocmd!autocmdUserALELintPrecallYourFunction()autocmdUserALELintPostcallYourFunction()autocmdUserALEJobStartedcallYourFunction()autocmdUserALEFixPrecallYourFunction()autocmdUserALEFixPostcallYourFunction()augroupEND

ALE offers some commands with<Plug> keybinds for moving between warnings anderrors quickly. You can map the keys Ctrl+j and Ctrl+k to moving between errorsfor example:

nmap<silent><C-k><Plug>(ale_previous_wrap)nmap<silent><C-j><Plug>(ale_next_wrap)

For more information, consult the online documentation with:help ale-navigation-commands.

ALE offers an optiong:ale_lint_on_save for enabling running the linters whenfiles are saved. This option is enabled by default. If you only wish to runlinters when files are saved, you can turn the other options off.

" Write this in your vimrc fileletg:ale_lint_on_text_changed='never'letg:ale_lint_on_insert_leave=0" You can disable this option too" if you don't want linters to run on opening a fileletg:ale_lint_on_enter=0

If for whatever reason you don't wish to run linters again when you save files,you can setg:ale_lint_on_save to0.

The quickfix list can be enabled by turning theg:ale_set_quickfix option on.If you wish to also disable the loclist, you can disable theg:ale_set_loclistoption.

" Write this in your vimrc fileletg:ale_set_loclist=0letg:ale_set_quickfix=1

If you wish to show Vim windows for the loclist or quickfix items when a filecontains warnings or errors,g:ale_open_list can be set to1.g:ale_keep_list_window_open can be set to1 if you wish to keep the windowopen even after errors disappear.

letg:ale_open_list=1" Set this if you want to." This can be useful if you are combining ALE with" some other plugin which sets quickfix errors, etc.letg:ale_keep_list_window_open=1

You can also setlet g:ale_list_vertical = 1 to open the windows verticallyinstead of the default horizontally.

First, install eslint and install stylelint withstylelint-processor-styled-components.

Supposing you have installed both tools correctly, configure your .jsx files sojsx is included in the filetype. You can use anautocmd for this.

augroupFiletypeGroupautocmd!auBufNewFile,BufRead*.jsxsetfiletype=javascript.jsxaugroupEND

Supposing the filetype has been set correctly, you can set the followingoptions in a jsx.vim ftplugin file.

" In ~/.vim/ftplugin/jsx.vim, or somewhere similar.letb:ale_linter_aliases= ['css','javascript']letb:ale_linters= ['stylelint','eslint']

Or if you want, you can configure the linters from your vimrc file.

" In ~/.vim/vimrc, or somewhere similar.letg:ale_linter_aliases= {'jsx': ['css','javascript']}letg:ale_linters= {'jsx': ['stylelint','eslint']}

ALE will alias thejsx filetype so it uses thecss filetype linters, anduse the original Array of selected linters forjsx from theg:ale_lintersobject. All available linters will be used for the filetypejavascript, andno linter will be run twice for the same file.

To check Vue files with ESLint, your ESLint project configuration file must beconfigured to use theVue plugin.After that, you need to configure ALE so it will run the JavaScript ESLintlinter on your files. The settings you need are similar to the settings neededfor checking JSX code with both stylelint and ESLint, in the previous section.

" In ~/.vim/ftplugin/vue.vim, or somewhere similar." Run both javascript and vue linters for vue files.letb:ale_linter_aliases= ['javascript','vue']" Select the eslint and vls linters.letb:ale_linters= ['eslint','vls']

Run:ALEInfo to see which linters are available after telling ALE to runJavaScript linters on Vue files. Not all linters support checking Vue files.

If you don't want to configure your linters in ftplugin files for some reason,you can configure them from your vimrc file instead.

" In ~/.vim/vimrc, or somewhere similar.letg:ale_linter_aliases= {'vue': ['vue','javascript']}letg:ale_linters= {'vue': ['eslint','vls']}

The structure of C and C++ projects varies wildly from project to project, withmany different build tools being used for building them, and many differentformats for project configuration files. ALE can run compilers easily, butALE cannot easily detect which compiler flags to use.

Some tools and build configurations can generatecompile_commands.jsonfiles. Thecppcheck,clangcheck,clangtidy andcquery linters can readthese files for automatically determining the appropriate compiler flags touse.

For linting with compilers likegcc andclang, and with other tools, youwill need to tell ALE which compiler flags to use yourself. You can usedifferent options for different projects with theg:ale_pattern_optionssetting. Consult the documentation for that setting for more information.b:ale_linters can be used to select which tools you want to run, say if youwant to use onlygcc for one project, and onlyclang for another.

ALE will attempt to parsecompile_commands.json files to discover compilerflags to use when linting code. See:help g:ale_c_parse_compile_commands formore information. See Clang's documentation forcompile_commands.json files.You should strongly consider generating them in your builds, which is easy to dowith CMake.

You can also configure ALE to automatically runmake -n to run dry runs onMakefiles to discover compiler flags. This can execute arbitrary code, so theoption is disabled by default. See:help g:ale_c_parse_makefile.

ALE supports running linters or fixers via Docker, virtual machines, or incombination with any remote machine with a different file system, so long as thetools are well-integrated with ALE, and ALE is properly configured to run thecorrect commands and map filename paths between different file systems. See:help ale-lint-other-machines for the full documentation on how to configureALE to support this.