格式化给定的文件和模式。

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

如果任何文件是 -，那么输入将从 stdin 读取，输出将写入 stdout。

格式化选项

格式化程序将在当前目录中读取 .formatter.exs 文件以进行格式化程序配置。评估此文件应返回一个关键字列表。

以下是一个 .formatter.exs 文件的示例，它可以作为起点

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

除了 Code.format_string!/2 中列出的选项之外，.formatter.exs 文件还支持以下选项

• :inputs (路径和模式列表) - 指定此任务要使用的默认输入。例如，["mix.exs", "{config,lib,test}/**/*.{ex,exs}"]。模式将使用 Path.wildcard/2 展开。

• :plugins (模块列表) (自 v1.13.0 起) - 指定模块列表以自定义格式化程序的工作方式。有关更多信息，请参见下面的“插件”部分。

• :subdirectories (路径和模式列表) - 指定具有自己的格式化规则的子目录。每个子目录都应该有一个 .formatter.exs，用于配置如何格式化该子目录中的条目。.formatter.exs 之间的配置不会共享或继承。如果一个 .formatter.exs 将“lib/app”列为子目录，则 .formatter.exs 中的规则将不可用在 lib/app/.formatter.exs 中。请注意，父 .formatter.exs 不得在其 :inputs 配置中指定“lib/app”子目录内的文件。如果发生这种情况，哪个格式化程序配置将被选取的行为是不确定的。

• :import_deps (作为原子的依赖项列表) - 指定将导入其格式化程序配置的依赖项列表。有关更多信息，请参见下面的“导入依赖项配置”部分。

• :export (关键字列表) - 指定要导出的格式化程序配置。有关更多信息，请参见下面的“导入依赖项配置”部分。

特定于任务的选项

• --check-formatted - 检查文件是否已格式化。这在预提交钩子和 CI 脚本中很有用，如果你想拒绝带有未格式化代码的贡献。如果检查失败，格式化的内容不会写入磁盘。请记住，格式化的输出可能会在 Elixir 版本之间有所不同，因为改进和修复会应用于格式化程序。

• --no-exit - 仅在与 --check-formatted 一起使用时有效。如果你不希望此 Mix 任务失败（并返回一个非零退出代码），但仍然希望检查格式错误并将其打印到控制台，则传递此选项。

• --dry-run - 格式化后不会保存文件。

• --dot-formatter - 带有格式化程序配置的文件的路径。如果可用，则默认为 .formatter.exs。有关更多信息，请参见上面的“格式化选项”部分。

• --stdin-filename - stdin 上正在格式化的文件的路径。如果你使用插件来支持自定义文件类型，例如 .heex，这将很有用。如果不传递此标志，则假定通过 stdin 传递的代码是有效的 Elixir 代码。默认为“stdin.exs”。

何时格式化代码

我们建议开发人员直接在他们的编辑器中格式化代码，无论是自动保存文件还是通过显式命令或键盘绑定。如果你的选择编辑器中没有此选项，添加所需的集成通常是调用以下命令的问题

$ cd $project && mix format $file

其中 $file 指的是当前文件，$project 是你项目的根目录。

还可以通过将模式和文件的列表传递给 mix format 来格式化整个项目中的代码，如本任务文档顶部所示。此列表也可以在 .formatter.exs 文件中的 :inputs 键下设置。

插件

可以自定义格式化程序的行为方式。插件必须实现 Mix.Tasks.Format 行为。例如，假设你的项目以两种不同的方式使用 Markdown：通过自定义 ~M sigil 和通过具有 .md 和 .markdown 扩展名的文件。自定义插件将如下所示

defmodule MixMarkdownFormatter do
  @behaviour Mix.Tasks.Format

  def features(_opts) do
    [sigils: [:M], extensions: [".md", ".markdown"]]
  end

  def format(contents, opts) do
    # logic that formats markdown
  end
end

传递给 format/2 的 opts 包含所有格式化选项，并且是以下之一

• :sigil (原子) - 正在格式化的 sigil，例如 :M。

• :modifiers (字符列表) - sigil 修饰符列表。

• :extension (字符串) - 正在格式化的文件的扩展名，例如 ".md"。

现在，任何应用程序都可以按如下方式使用你的格式化程序

# .formatter.exs
[
  # Define the desired plugins
  plugins: [MixMarkdownFormatter, AnotherMarkdownFormatter],
  # Remember to update the inputs list to include the new extensions
  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}", "posts/*.{md,markdown}"]
]

请注意，在使用插件运行格式化程序时，你的代码将首先被编译。

此外，输入插件的顺序就是格式化顺序。因此，在上面的 .formatter.exs 中，MixMarkdownFormatter 将在 AnotherMarkdownFormatter 之前格式化 markdown 文件和 sigil。

导入依赖项配置

此任务支持从依赖项导入格式化程序配置。

想要导出格式化程序配置的依赖项需要在项目的根目录中有一个 .formatter.exs 文件。在此文件中，依赖项可以列出一个 :export 选项，其中包含要导出的配置。目前，:export 下只支持一个选项：:locals_without_parens（其值与 Code.format_string!/2 中 :locals_without_parens 的值具有相同的形状）。

在依赖项的 :export 选项中列出的 :locals_without_parens 下的函数可以通过在项目的格式化程序配置文件的 :import_deps 选项中列出该依赖项来导入。

例如，假设你有一个名为 my_app 的项目，它依赖于另一个名为 my_dep 的项目。 my_dep 想要导出一些配置，所以 my_dep/.formatter.exs 将如下所示

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

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

为了导入配置，my_app 的 .formatter.exs 将如下所示

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