Neoformat
A (Neo)vim plugin for formatting code.
Neoformat uses a variety of formatters for many filetypes. Currently, Neoformat will run a formatter using the current buffer data, and on success it will update the current buffer with the formatted text. On a formatter failure, Neoformat will try the next formatter defined for the filetype.
By using getbufline()
to read from the current buffer instead of file,
Neoformat is able to format your buffer without you having to :w
your file first.
Also, by using setline()
, marks, jumps, etc. are all maintained after formatting.
Neoformat supports both sending buffer data to formatters via stdin, and also
writing buffer data to /tmp/
for formatters to read that do not support input
via stdin.
Basic Usage
Format the entire buffer, or visual selection of the buffer
:Neoformat
Or specify a certain formatter (must be defined for the current filetype)
:Neoformat jsbeautify
Or format a visual selection of code in a different filetype
Note: you must use a ! and pass the filetype of the selection
:Neoformat! python
You can also pass a formatter to use
:Neoformat! python yapf
Or perhaps run a formatter on save
augroup fmt
autocmd!
autocmd BufWritePre * undojoin | Neoformat
augroup END
The undojoin
command will put changes made by Neoformat into the same
undo-block
with the latest preceding change. See
Managing Undo History.
Install
The best way to install Neoformat is with your favorite plugin manager for Vim, such as vim-plug:
Plug 'sbdchd/neoformat'
Current Limitation(s)
If a formatter is either not configured to use stdin
, or is not able to read
from stdin
, then buffer data will be written to a file in /tmp/neoformat/
,
where the formatter will then read from
Config [Optional]
Define custom formatters.
Options:
name | description | default | optional / required |
---|---|---|---|
exe |
the name the formatter executable in the path | n/a | required |
args |
list of arguments | [] | optional |
replace |
overwrite the file, instead of updating the buffer | 0 | optional |
stdin |
send data to the stdin of the formatter | 0 | optional |
stderr |
capture stderr output from formatter | 0 | optional |
no_append |
do not append the path of the file to the formatter command, used when the path is in the middle of a command |
0 | optional |
env |
list of environment variable definitions to be prepended to the formatter command | [] | optional |
valid_exit_codes |
list of valid exit codes for formatters who do not respect common unix practices | [0] | optional |
try_node_exe |
attempt to find exe in a node_modules/.bin directory in the current working directory or one of its parents (requires setting g:neoformat_try_node_exe ) |
0 | optional |
Example:
let g:neoformat_python_autopep8 = {
\ 'exe': 'autopep8',
\ 'args': ['-s 4', '-E'],
\ 'replace': 1, " replace the file, instead of updating buffer (default: 0)
\ 'stdin': 1, " send data to stdin of formatter (default: 0)
\ 'env': ["DEBUG=1"], " prepend environment variables to formatter command
\ 'valid_exit_codes': [0, 23],
\ 'no_append': 1,
\ }
let g:neoformat_enabled_python = ['autopep8']
Configure enabled formatters.
let g:neoformat_enabled_python = ['autopep8', 'yapf', 'docformatter']
Have Neoformat use &formatprg as a formatter
let g:neoformat_try_formatprg = 1
Enable basic formatting when a filetype is not found. Disabled by default.
" Enable alignment
let g:neoformat_basic_format_align = 1
" Enable tab to spaces conversion
let g:neoformat_basic_format_retab = 1
" Enable trimmming of trailing whitespace
let g:neoformat_basic_format_trim = 1
Run all enabled formatters (by default Neoformat stops after the first formatter succeeds)
let g:neoformat_run_all_formatters = 1
Above options can be activated or deactivated per buffer. For example:
" runs all formatters for current buffer without tab to spaces conversion
let b:neoformat_run_all_formatters = 1
let b:neoformat_basic_format_retab = 0
Have Neoformat only msg when there is an error
let g:neoformat_only_msg_on_error = 1
When debugging, you can enable either of following variables for extra logging.
let g:neoformat_verbose = 1 " only affects the verbosity of Neoformat
" Or
let &verbose = 1 " also increases verbosity of the editor as a whole
Have Neoformat look for a formatter executable in the node_modules/.bin
directory in the current working directory or one of its parents (only applies
to formatters with try_node_exe
set to 1
):
let g:neoformat_try_node_exe = 1
Adding a New Formatter
Note: you should replace everything {{ }}
accordingly
-
Create a file in
autoload/neoformat/formatters/{{ filetype }}.vim
if it does not already exist for your filetype. -
Follow the following format
See Config above for options
function! neoformat#formatters#{{ filetype }}#enabled() abort
return ['{{ formatter name }}', '{{ other formatter name for filetype }}']
endfunction
function! neoformat#formatters#{{ filetype }}#{{ formatter name }}() abort
return {
\ 'exe': '{{ formatter name }}',
\ 'args': ['-s 4', '-q'],
\ 'stdin': 1
\ }
endfunction
function! neoformat#formatters#{{ filetype }}#{{ other formatter name }}() abort
return {'exe': {{ other formatter name }}
endfunction
Managing Undo History
If you use an autocmd
to run Neoformat on save, and you have your editor
configured to save automatically on CursorHold
then you might run into
problems reverting changes. Pressing u
will undo the last change made by
Neoformat instead of the change that you made yourself - and then Neoformat
will run again redoing the change that you just reverted. To avoid this
problem you can run Neoformat with the Vim undojoin
command to put changes
made by Neoformat into the same undo-block
with the preceding change. For
example:
augroup fmt
autocmd!
autocmd BufWritePre * undojoin | Neoformat
augroup END
When undojoin
is used this way pressing u
will "skip over" the Neoformat
changes - it will revert both the changes made by Neoformat and the change
that caused Neoformat to be invoked.
Supported Filetypes
- Arduino
- Assembly
- Astro
- Bazel
- Beancount
- Blade
- Bib
- C
- C#
- C++
- Cabal
- Caddyfile
- CMake
- Crystal
crystal tool format
(ships withcrystal
)
- CSS
css-beautify
(ships withjs-beautify
),prettydiff
,stylefmt
,stylelint
,csscomb
,prettierd
,prettier
- CSV
- Cue
- D
- D2
- Dart
- Dhall
- dune
- Ebuild
shfmt
let g:shfmt_opt="-ci"
- Elixir
- Elm
- Erlang
- Fennel
- Fish
- Fortran
- F#
- GDScript
- Gleam
- Go
- GLSL
- GN
- GraphQL
- Haskell
stylishhaskell
,hindent
,hfmt
,brittany
,sortimports
,floskell
ormolu
let g:ormolu_ghc_opt=["TypeApplications", "RankNTypes"]
- You must use formatter's name without "
-
"" right let g:neoformat_enabled_haskell = ['sortimports', 'stylishhaskell'] " wrong let g:neoformat_enabled_haskell = ['sort-imports', 'stylish-haskell']
- HCL
- Toml
- Puppet
- PureScript
- HTML
html-beautify
(ships withjs-beautify
),prettierd
,prettier
,prettydiff
- HTMLDjango
- Jade
- Java
- JavaScript
- JSON
- JSONC (JSON with comments)
- Kotlin
- LaTeX
latexindent
let g:latexindent_opt="-m"
- Less
- Lua
- Markdown
- Matlab
- Nginx
- Nickel
- Nim
nimpretty
(ships withnim
)
- Nix
- Objective-C
- OCaml
- OpenSCAD
- Pandoc Markdown
- Pawn
- Perl
- PHP
- PowerShell
- Prisma
- Proto
- Pug (formally Jade)
- Python
- R
- Reason
- Rego
- Ruby
- Rust
- Sass
- Sbt
- Scala
- SCSS
- Shell
shfmt
let g:shfmt_opt="-ci" ```, [`topiary`](https://topiary.tweag.io)
- Solidity
- SQL
sqlfmt
,sqlformat
(ships with sqlparse),pg_format
(ships with pgFormatter),sleek
- Starlark
- SugarSS
stylelint
- Svelte
- Swift
- Terraform
- TypeScript
- V
v fmt
(ships withv
)
- VALA
- Vue
- XHTML
- XML
- YAML
- zig
- zsh
shfmt
let g:shfmt_opt="-ci"