Formats the given files and patterns.

mix format mix.exs "lib/**/*.{ex,exs}" "test/**/*.{ex,exs}"

If any of the files is -, then the output is read from stdin and written to stdout.

Formatting options

The formatter will read a .formatter.exs in the current directory for formatter configuration. Evaluating this file should return a keyword list.

Here is an example .formatter.exs that works as a starting point:

[
  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
]

Besides the options listed in Code.format_string!/2, the .formatter.exs supports the following options:

• :inputs (a list of paths and patterns) - specifies the default inputs to be used by this task. For example, ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"]. Patterns are expanded with Path.wildcard/2.

• :subdirectories (a list of paths and patterns) - specifies subdirectories that have their own formatting rules. Each subdirectory should have a .formatter.exs that configures how entries in that subdirectory should be formatted as. Configuration between .formatter.exs are not shared nor inherited. If a .formatter.exs lists "lib/app" as a subdirectory, the rules in .formatter.exs won't be available in lib/app/.formatter.exs. Note that the parent .formatter.exs must not specify files inside the "lib/app" subdirectory in its :inputs configuration. If this happens, the behaviour of which formatter configuration will be picked is unspecified.

• :import_deps (a list of dependencies as atoms) - specifies a list of dependencies whose formatter configuration will be imported. When specified, the formatter should run in the same directory as the mix.exs file that defines those dependencies. See the "Importing dependencies configuration" section below for more information.

• :export (a keyword list) - specifies formatter configuration to be exported. See the "Importing dependencies configuration" section below.

Task-specific options

• --check-formatted - checks that the file is already formatted. This is useful in pre-commit hooks and CI scripts if you want to reject contributions with unformatted code. However keep in mind that the formatted output may differ between Elixir versions as improvements and fixes are applied to the formatter.

• --check-equivalent - checks if the files after formatting have the same AST as before formatting. If the ASTs are not equivalent, it is a bug in the code formatter. This option is useful if you suspect you have ran into a formatter bug and you would like confirmation.

• --dry-run - does not save files after formatting.

• --dot-formatter - path to the file with formatter configuration. Defaults to .formatter.exs if one is available. See the ".formatter.exs" section for more information.

If any of the --check-* options are given and a check fails, the formatted contents won't be written to disk nor printed to standard output.

When to format code

We recommend developers to format code directly in their editors, either automatically when saving a file or via an explicit command or key binding. If such option is not yet available in your editor of choice, adding the required integration is usually a matter of invoking:

cd $project && mix format $file

where $file refers to the current file and $project is the root of your project.

It is also possible to format code across the whole project by passing a list of patterns and files to mix format, as shown at the top of this task documentation. This list can also be set in the .formatter.exs under the :inputs key.

Importing dependencies configuration

This task supports importing formatter configuration from dependencies.

A dependency that wants to export formatter configuration needs to have a .formatter.exs file at the root of the project. In this file, the dependency can export a :export option with configuration to export. For now, only one option is supported under :export: :locals_without_parens (whose value has the same shape as the value of the :locals_without_parens in Code.format_string!/2).

The functions listed under :locals_without_parens in the :export option of a dependency can be imported in a project by listing that dependency in the :import_deps option of the formatter configuration file of the project.

For example, consider I have a project my_app that depends on my_dep. my_dep wants to export some configuration, so my_dep/.formatter.exs would look like this:

# my_dep/.formatter.exs
[
  # Regular formatter configuration for my_dep
  # ...

  export: [
    locals_without_parens: [some_dsl_call: 2, some_dsl_call: 3]
  ]
]

In order to import configuration, my_app's .formatter.exs would look like this:

# my_app/.formatter.exs
[
  import_deps: [:my_dep]
]