Home

Awesome

vim-autoformat

Format code with one button press (or automatically on save).

This plugin makes use of external formatting programs to achieve the most decent results. Check the list of formatprograms below to see which languages are supported by default. Most formatprograms will obey vim settings, such as textwidth and shiftwidth(). You can easily customize existing formatprogram definitions or add your own formatprogram. When no formatprogram exists (or no formatprogram is installed) for a certain filetype, vim-autoformat falls back by default to indenting, (using vim's auto indent functionality), retabbing and removing trailing whitespace.

Requirement

vim-autoformat requires vim to have python support (python 2 or python 3). You can check your vim has python support by running :echo has("python3") and :echo has("python2").

Neovim

Neovim does not come with python support by default, and additional setup is required.

First install pynvim

python3 -m pip install pynvim

And add the following configuration in your .vimrc

let g:python3_host_prog="/path/to/python/executable/"

How to install

Vundle

Put this in your .vimrc.

Plugin 'vim-autoformat/vim-autoformat'

Then restart vim and run :PluginInstall. Alternatively, you could run :source $MYVIMRC to reload your .vimrc without restarting vim. To update the plugin to the latest version, you can run :PluginUpdate.

Pathogen

Download the source and extract in your bundle directory. Updating has to be done manually, as far as I'm aware.

Other

It is highly recommended to use a plugin manager such as Vundle, since this makes it easy to update plugins or uninstall them. It also keeps your .vim directory clean. Still you can decide to download this repository as a zip file or whatever and extract it to your .vim folder.

How to use

First you should install an external program that can format code of the programming language you are using. This can either be one of the programs that are listed below as defaultprograms, or a custom program. For defaultprograms, vim-autoformat knows for which filetypes it can be used. For using a custom formatprogram, read the text below How can I change the behaviour of formatters, or add one myself? If the formatprogram you want to use is installed in one of the following ways, vim automatically detects it:

let g:formatterpath = ['/some/path/to/a/folder', '/home/superman/formatters']

Remember that when no formatprograms exists for a certain filetype, vim-autoformat falls back by default to indenting, retabbing and removing trailing whitespace. This will fix at least the most basic things, according to vim's indentfile for that filetype.

When you have installed the formatter you need, you can format the entire buffer with the command :Autoformat. You can provide the command with a file type such as :Autoformat json, otherwise the buffer's filetype will be used.

Some formatters allow you to format only a part of the file, for instance clang-format and autopep8. To use this, provide a range to the :Autoformat command, for instance by visually selecting a part of your file, and then executing :Autoformat. For convenience it is recommended that you assign a key for this, like so:

noremap <F3> :Autoformat<CR>

Or to have your code be formatted upon saving your file, you could use something like this:

au BufWrite * :Autoformat

You can also format the current line only (without having to make a visual selection) by executing :AutoformatLine.

To disable the fallback to vim's indent file, retabbing and removing trailing whitespace, set the following variables to 0.

let g:autoformat_autoindent = 0
let g:autoformat_retab = 0
let g:autoformat_remove_trailing_spaces = 0

To disable or re-enable these option for specific buffers, use the buffer local variants: b:autoformat_autoindent, b:autoformat_retab and b:autoformat_remove_trailing_spaces. So to disable autoindent for filetypes that have incompetent indent files, use

autocmd FileType vim,tex let b:autoformat_autoindent=0

You can manually autoindent, retab or remove trailing whitespace with the following respective commands.

gg=G
:retab
:RemoveTrailingSpaces

For each filetype, vim-autoformat has a list of applicable formatters. If you have multiple formatters installed that are supported for some filetype, vim-autoformat tries all formatters in this list of applicable formatters, until one succeeds. You can set this list manually in your vimrc (see section How can I change the behaviour of formatters, or add one myself?, or change the formatter with the highest priority by the commands :NextFormatter and :PreviousFormatter. To print the currently selected formatter use :CurrentFormatter. These latter commands are mostly useful for debugging purposes. If you have a composite filetype with dots (like django.python or php.wordpress), vim-autoformat first tries to detect and use formatters for the exact original filetype, and then tries the same for all supertypes occurring from left to right in the original filetype separated by dots (.).

Using multiple formatters for the same file

It is possible to apply multiple formatters for single file, for example, html can use special formatters for js/css etc. Support can be enabled via the g:run_all_formatters_<identifier> option.

In this case, formatters from g:formatdef_<identifier> will be applied to the file one by one. Fallback (vim) formatting isn't used if at least one formatter has finished sucessfully.

Sample config:

let g:formatters_vue = ['eslint_local', 'stylelint']
let g:run_all_formatters_vue = 1

Default formatprograms

Here is a list of formatprograms that are supported by default, and thus will be detected and used by vim when they are installed properly. They are defined in https://github.com/Chiel92/vim-autoformat/blob/master/plugin/defaults.vim. They are simply tried in the order they are listed until one succeeds.

Help, the formatter doesn't work as expected!

If you're struggling with getting a formatter to work, it may help to set vim-autoformat in verbose-mode. Vim-autoformat will then output errors on formatters that failed. The value of g:autoformat_verbosemode could set as 0, 1 or 2. which means: 0: no message output. 1: only error message output. 2: all message output.

let g:autoformat_verbosemode=1
" OR:
let verbose=1

To read all messages in a vim session type :messages. Since one cannot always easily copy the contents of messages (e.g. for posting it in an issue), vim-autoformats command :PutMessages may help. It puts the messages in the current buffer, allowing you to do whatever you want.

Reporting bugs

Please report bugs by creating an issue in this repository. When there are problems with getting a certain formatter to work, provide the output of verbose mode in the issue.

How can I change the behaviour of formatters, or add one myself?

If you need a formatter that is not among the defaults, or if you are not satisfied with the default formatting behaviour that is provided by vim-autoformat, you can define it yourself. The formatprogram must read the unformatted code from the standard input, and write the formatted code to the standard output.

Basic definitions

The formatprograms that available for a certain <filetype> are defined in g:formatters_<filetype>. This is a list containing string identifiers, which point to corresponding formatter definitions. The formatter definitions themselves are defined in g:formatdef_<identifier> as a string expression. Defining any of these variable manually in your .vimrc, will override the default value, if existing. For example, a complete definition in your .vimrc for C# files could look like this:

let g:formatdef_my_custom_cs = '"astyle --mode=cs --style=ansi -pcHs4"'
let g:formatters_cs = ['my_custom_cs']

In this example, my_custom_cs is the identifier for our formatter definition. The first line defines how to call the external formatter, while the second line tells vim-autoformat that this is the only formatter that we want to use for C# files. Please note the double quotes in g:formatdef_my_custom_cs. This allows you to define the arguments dynamically:

let g:formatdef_my_custom_cs = '"astyle --mode=cs --style=ansi -pcHs".&shiftwidth'
let g:formatters_cs = ['my_custom_cs']

Please notice that g:formatdef_my_custom_cs contains an expression that can be evaluated, as required. As you see, this allows us to dynamically define some parameters. In this example, the indent width that astyle will use, depends on the buffer local value of &shiftwidth, instead of being fixed at 4. So if you're editing a csharp file and change the shiftwidth (even at runtime), the g:formatdef_my_custom_cs will change correspondingly.

For the default formatprogram definitions, the options expandtab, shiftwidth and textwidth are taken into account whenever possible. This means that the formatting style will match your current vim settings as much as possible. You can have look look at the exact default definitions for more examples. They are defined in vim-autoformat/plugin/defaults.vim. As a small side note, in the actual defaults the function shiftwidth() is used instead of the property. This is because it falls back to the value of tabstop if shiftwidth is 0.

If you have a composite filetype with dots (like django.python or php.wordpress), vim-autoformat internally replaces the dots with underscores so you can specify formatters through g:formatters_django_python and so on.

To override these options for a local buffer, use the buffer local variants: b:formatters_<filetype> and b:formatdef_<identifier>. This can be useful, for example, when working with different projects with conflicting formatting rules, with each project having settings in its own vimrc or exrc file:

let b:formatdef_custom_c='"astyle --mode=c --suffix=none --options=/home/user/special_project/astylerc"'
let b:formatters_c = ['custom_c']

Ranged definitions

If your format program supports formatting specific ranges, you can provide a format definition which allows to make use of this. The first and last line of the current range can be retrieved by the variables a:firstline and a:lastline. They default to the first and last line of your file, if no range was explicitly specified. So, a ranged definition could look like this.

let g:formatdef_autopep8 = "'autopep8 - --range '.a:firstline.' '.a:lastline"
let g:formatters_python = ['autopep8']

This would allow the user to select a part of the file and execute :Autoformat, which would then only format the selected part.

Contributing

This project is community driven. I don't actively do development on vim-autoformat myself, as its current state fulfills my personal needs. However, I will review pull requests and keep an eye on the general sanity of the code.

If you have any improvements on this plugin or on this readme, if you have some formatter definition that can be added to the defaults, or if you experience problems, please open a pull request or an issue in this repository.

Major Change Log

October 2018

March 2016

June 2015

December 20 2013

March 27 2013

March 16 2013

March 13 2013

March 10 2013

March 9 2013