elm-format

elm-format is still in alpha. If you run into any problems, please report them.

The format produced by elm-format may change significantly before the 1.0.0 release. If this will cause problems for you, please refrain from using elm-format during the alpha- and beta-test periods.

elm-format formats Elm source code according to a standard set of rules. It is inspired by the popular gofmt.

The benefits of elm-format:

It makes code easier to write, because you never have to worry about minor formatting concerns while powering out new code.
It makes code easier to read, because there are no longer distracting minor stylistic differences between different code bases. As such, your brain can map more efficiently from source to mental model.
It makes code easier to maintain, because you can no longer have diffs related only to formatting; every diff necessarily involves a material change.
It saves your team time debating how to format things, because there is a standard tool that formats everything the same way.

Usage

elm-format Main.elm  # Format a single file
elm-format Main.elm --yes  # Overwrite the file without prompting
elm-format src/  # Format all *.elm files in a directory
elm-format --stdin  # Format input from stdin and write to stdout
elm-format --stdin --output Main.elm  # Format input from stdin and write to file
elm-format --help  # See other command line options

Installation

elm-format is still in alpha. If you run into any problems, please report them.

The format produced by elm-format may change significantly before the 1.0.0 release. If this will cause problems for you, please refrain from using elm-format during the alpha- and beta-test periods.

You will need to download the version appropriate for your OS, unzip it, and place elm-format or elm-format.exe (windows) on your PATH. Simpler installation options will be available once there is a stable release of elm-format.

If you need PGP signatures, see the releases page.

For Elm 0.17

(Using this version with Elm 0.16 files will migrate them to Elm 0.17 syntax.)

Mac: download
Linux: download
Windows: download

For Elm 0.16

Mac: download
Linux: download
Windows: download

Editor integration

Find your editor in the table below. The recommended plugin for each editor is indicated with 🏆 (trophy emoji).

Editor	Plugin	Installation	Formatting	Format on save	Configuration	Error handling
Atom	🏆 atom-elm-format	✅ 2 steps	⚠️ must use format-on-save or save file before formatting	✅	✅	⚠️ no installation instructions
Atom	atom-beautify	⚠️ 3 steps	✅	⚠️ requires configuration	✅	✅
Light Table	🏆 elm-light	⚠️ 3 steps	✅	⚠️ requires configuration	✅	⚠️ no installation instructions
Vim	🏆 elm-vim	❌ 6 steps	✅	⚠️ requires configuration	✅	❌ no error message
Emacs	🏆 elm-mode	❌ 4 steps	✅	⚠️ requires configuration	✅	⚠️ no installation instructions
Visual Studio Code	🏆 Elm Language Support	⚠️ 3 steps	❔ TBD	❌	❔ TBD	❔ TBD
Visual Studio Code	VSCode Elm Format	⚠️ 3 steps	❔ TBD	⚠️ requires configuration	❔ TBD	❔ TBD
Sublime Text	🏆 Elm Language Support	✅ 2 steps	❔ TBD	✅	❔ TBD	❔ TBD

Detailed instructions

If you can simplify or improve the installation instructions or add instructions for another editor, please make a pull request. The default behavior of elm-format-approved plugins is to format Elm files on save.

atom-elm-format installation

Install elm-format
Install atom-elm-format
```
apm install elm-format
```

or use the Atom package manager in Atom's settings

atom-beautify installation

Install elm-format
Install atom-beautify
```
apm install atom-beautify
```

or use the Atom package manager in Atom's settings

Use ^⌥B (CTRL-ALT-B) to format a file

elm-light installation

Install elm-format
Install the elm-light plugin using the Light Table plugin manager
Add the following to your user keymap:

[:editor.elm "ctrl-s" :save :elm-format :elm.lint]

This step needs improvement to be understandable by novice Light Table users: how does one edit the user keymap?

elm-mode installation

Install elm-format
If your Emacs has package.el (which is automatically the case for Emacs >= 24), you can install elm-mode from the package in MELPA:
1. Ensure that you have added the MELPA source in your ~/.emacs.d/init.el:
```
(require 'package)
(add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/"))
```
2. Install elm-mode (official instructions): Use M-x list-packages and choose elm-mode.
Set elm-format-on-save to t to apply elm-format on the current buffer on every save. (The setting can be changed via M-x customize-variable elm-format-on-save. Click button Toggle to change the setting and button State to activate the setting.)

elm-vim installation

Install elm-format

Install vim-plug (official instructions)

Download vim-plug:

curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
    https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

Make sure there is a section like this in your ~/.vimrc:

call plug#begin('~/.vim/plugged')
" ... any active plugins
call plug#end()

Install elm-vim (official instructions)
1. Add Plug 'elmcast/elm-vim' to the plug#begin plugin section in your ~/.vimrc
2. Start vim and run :PlugInstall
Add the following to your ~/.vimrc:

let g:elm_format_autosave = 1

Visual Studio Code installation

Install elm-format
Install Elm tools for VSCode
```
ext install elm
```
SHIFT-ALT-F will format the current file

VSCode Elm Format installation

Install elm-format
Install VSCode Elm Format
```
ext install elm-format
```
You can run elm-format by using the Elm: Format command
You can also run elm-format whenever you save the file by enabling the `formatOnSave' option

This step needs improvement to be understandable by novice Visual Studio Code users: how does one enable the formatOnSave option?

Sublime Text installation

Install elm-format
Install the Elm Language Support package.

Development info

Building from source

git clone https://github.com/avh4/elm-format.git
cd elm-format
cabal sandbox init
cabal install --only-dependencies --enable-tests
cabal build
./dist/build/elm-format-0.17/elm-format-0.17 --help

Running tests

brew install shellcheck
cabal configure --enable-tests
./tests/run-tests.sh

kant5t1km3/elm-format