Awesome
format-all for Emacs
NOTE: The package is actively maintained but due to lack of time, complex tasks are done at a slow pace. Simple tasks like adding or fixing formatter definitions are often done immediately. For faster progress, additional maintainers are welcome.
What does it do
Lets you auto-format source code in many languages using the same command for all languages, instead of learning a different Emacs package and formatting command for each language.
Just do M-x format-all-region-or-buffer
and it will try its best
to do the right thing. To auto-format code on save, use the minor mode
format-all-mode
. Please see the documentation for that function for
instructions.
Supported languages
- Angular (prettier)
- Assembly (asmfmt)
- ATS (atsfmt)
- Awk (gawk)
- AZSL (clang-format)
- Bazel Starlark (buildifier)
- Beancount (bean-format)
- BibTeX (Emacs)
- C/C++/Objective-C (clang-format, astyle)
- C# (clang-format, astyle, csharpier)
- Cabal (cabal-fmt)
- Caddyfile (caddy-fmt)
- Clojure/ClojureScript (cljfmt, zprint)
- CMake (cmake-format)
- Crystal (crystal tool format)
- CSS/Less/SCSS (prettier, prettierd)
- Cuda (clang-format)
- D (dfmt)
- Dart (dartfmt, dart-format)
- Dhall (dhall format)
- Dockerfile (dockfmt)
- Elixir (mix format)
- Elm (elm-format)
- Emacs Lisp (Emacs)
- Erb (erb-format)
- Erlang (efmt)
- F# (fantomas)
- Fish Shell (fish_indent)
- Fortran Free Form (fprettify)
- Gleam (gleam format)
- GLSL (clang-format)
- Go (gofmt, goimports)
- GraphQL (prettier, prettierd)
- Haskell (brittany, fourmolu, hindent, ormolu, stylish-haskell)
- HCL (hclfmt)
- HLSL (clang-format)
- HTML/XHTML/XML (tidy)
- Hy (Emacs)
- Java (astyle, clang-format, google-java-format)
- JavaScript/JSON/JSX (prettier, standard, prettierd, deno)
- Jsonnet (jsonnetfmt)
- Kotlin (ktlint)
- LaTeX (latexindent, auctex)
- Ledger (ledger-mode)
- Lua (lua-fmt, stylua, prettier plugin)
- Markdown (prettier, prettierd, deno)
- Meson (muon fmt)
- Nginx (nginxfmt)
- Nix (nixpkgs-fmt, nixfmt, alejandra)
- OCaml (ocp-indent, ocamlformat)
- Perl (perltidy)
- PHP (prettier plugin)
- Protocol Buffers (clang-format)
- PureScript (purty, purescript-tidy)
- Python (black, isort, ruff format, yapf)
- R (styler)
- Racket (raco fmt)
- Reason (bsrefmt)
- ReScript (rescript format)
- Ruby (rubocop, rufo, standardrb, stree (syntax_tree))
- Rust (rustfmt)
- Scala (scalafmt)
- Shell script (beautysh, shfmt)
- Snakemake (snakefmt)
- Solidity (prettier plugin)
- SQL (pgformatter, sqlformat)
- Svelte (prettier plugin)
- Swift (swiftformat)
- Terraform (terraform fmt)
- TOML (prettier plugin, taplo fmt)
- TypeScript/TSX (prettier, ts-standard, prettierd, deno)
- V (v fmt)
- Vue (prettier, prettierd)
- Verilog (iStyle, Verible)
- YAML (prettier, prettierd)
- Zig (zig)
How to install
From MELPA
You will need to install external programs to do the formatting. If
format-all-buffer
can't find the right program, it will try to tell
you how to install it.
If you have installed a formatter but Emacs cannot find it, Emacs may
be using a PATH
different from your shell. The path searched by
Emacs is in the exec-path
variable. You can easily make it match
your shell's PATH
using the
exec-path-from-shell
package from MELPA.
How to customize
M-x customize-group format-all
has a few basic settings.
However, the main thing you probably want to set is
format-all-formatters
. That variable is buffer-local, and can be
made project-local by setting it in a .dir-locals.el
file in a
project's directory. That file can be committed to version control to
share it with the whole project.
To enable format on save for most programming language buffers:
(add-hook 'prog-mode-hook 'format-all-mode)
.
To control displaying the formatting errors buffer when
formatting fails or has warnings, customize the variable
format-all-show-errors
. Set it to one of these - 'always
(shows
errors buffer regardless),'warnings
(shows errors buffer for
both errors and warnings), 'errors
(only show errors buffer
when there are errors) or 'never
(never show errors buffer).
The command format-all-ensure-formatter
will ensure that a default
formatter is selected in case you don't have one set; you can
customize the default formatter for each language. To ensure a
formatter is set whenever you enable format-all-mode
, you can use:
(add-hook 'format-all-mode-hook 'format-all-ensure-formatter)
.
Additionally, many of the external formatters support configuration files in the source code directory to control their formatting. Please see the documentation for each formatter.
Examples
Simple example
(setq format-all-formatters
'(("Shell" (shfmt "-i" "4" "-ci"))))
Setting default formatters with use-package
(use-package format-all
:commands format-all-mode
:hook (prog-mode . format-all-mode)
:config
(setq-default format-all-formatters
'(("C" (astyle "--mode=c"))
("Shell" (shfmt "-i" "4" "-ci")))))
This config will assure that:
format-all
will be loaded afterformat-all-mode
commandformat-all-mode
will be executed each time you enter a mode that emacs recognized as designed for programing- only after
format-all
is loaded it will setformat-all-formatters
globally for all buffers
Alternatively you can replace :config
with :init
and setq-default
with setq
. It will also work but will be less efficient.
Setting the default formatter for each mode
This approach allows you to split your default formatters accross many places in your config.
(add-hook 'java-mode-hook
(lambda ()
(setq format-all-formatters
'(("Java" (astyle "--mode=java"))))))
If you want to optimize your config to defer setting variables, you may
remove the :config
section from use-package
snippet and use this variant
(eval-after-load 'format-all
'(add-hook 'java-mode-hook
(lambda ()
(setq format-all-formatters
'(("Java" (astyle "--mode=java")))))))
sqlformat
The formatter sqlformat
confuses many people. It does not to do any
formatting by default. When you run it, nothing seems to happen.
This appears to be a deliberate design decision. Please contact the
maintainer of sqlformat
if you would like it to change.
You can add your own command line flags using a hook. The following
example sets the -r
option.
(add-hook 'sql-mode-hook
(lambda ()
(setq format-all-formatters
'(("SQL" (sqlformat "-r"))))))
How to add new languages
New external formatters can be added easily if they can read code from standard input and format it to standard output. Feel free to submit a pull request or ask for help in GitHub issues.
How to report bugs
GitHub issues are preferred. Email is also ok.
Feature requests are welcome. If you are interested in doing anything beyond adding new formatters in the current framework, please discuss in issues before writing code.
Roadmap
atom-beautify sports a very impressive set of formatters. We should aspire to that level of coverage for Emacs.
Unibeautify is a project to provide one shell command to run all beautifiers. atom-beautify will be rewritten to be based on it. Perhaps we should be too, once it stabilizes.