treefmt-nix

使用 Nix 快速便捷地格式化多个文件

一个 numtide 项目。

treefmt 整合了多种编程语言的文件格式化工具，使您能够使用单个命令格式化项目中的所有文件。借助 treefmt-nix，您可以在一个地方指定 treefmt 构建选项、依赖项和配置，并通过 Nix 方便地管理。

treefmt-nix 会自动为您安装和配置所需的格式化工具以及 treefmt，并很好地集成到您的 Nix 开发环境中。它附带了由社区维护的、合理的、预先制作的 formatter-configs ；每个配置对应于您通常添加到 treefmt 配置文件 treefmt.toml 中的一个部分。

查看已经支持的格式化工具，包括 Python、Rust、Go、Haskell 等。

集成到 Nix

无 flakes 的传统 Nix

要在 nix-classic 中运行 treefmt-nix，请使用 niv 导入该仓库：

$ niv add numtide/treefmt-nix

或者，您可以下载源代码并在项目根目录中运行 nix-build：

$ nix-build

该命令将返回辅助函数，这些函数稍后用于从指定的 treefmt-nix 配置生成派生。

安装 treefmt-nix 后，指定格式化器配置。例如，此配置用于格式化 terraform 文件：

# myfile.nix
{ system ? builtins.currentSystem }:
let
  nixpkgsSrc = builtins.fetchTarball "https://github.com/NixOS/nixpkgs/archive/refs/heads/nixos-unstable.tar.gz";
  treefmt-nixSrc = builtins.fetchTarball "https://github.com/numtide/treefmt-nix/archive/refs/heads/master.tar.gz";
  nixpkgs = import nixpkgsSrc { inherit system; };
  treefmt-nix = import treefmt-nixSrc;
in
treefmt-nix.mkWrapper nixpkgs {
  # Used to find the project root
  projectRootFile = ".git/config";
  # Enable the terraform formatter
  programs.terraform.enable = true;
  # Override the default package
  programs.terraform.package = nixpkgs.terraform_1;
  # Override the default settings generated by the above option
  settings.formatter.terraform.excludes = [ "hello.tf" ];
}

将配置文件放置在项目根目录中是一个良好的实践。

接下来，执行此命令：

$ nix-build myfile.nix

此命令返回一个派生，其中包含位于当前目录中 ./result/bin/treefmt 的 treefmt 二进制文件。该文件实际上是指向 /nix/store 中产物的符号链接。

在此情况下，treefmt.toml 不会生成：该二进制文件已使用配置进行封装。

Flakes

使用 flakes 运行 treefmt-nix 并不困难。该库作为 lib 属性暴露：

# flake.nix
{
  inputs.treefmt-nix.url = "github:numtide/treefmt-nix";
  inputs.systems.url = "github:nix-systems/default";

  outputs = { self, nixpkgs, systems, treefmt-nix }:
    let
      # Small tool to iterate over each systems
      eachSystem = f: nixpkgs.lib.genAttrs (import systems) (system: f nixpkgs.legacyPackages.${system});

      # Eval the treefmt modules from ./treefmt.nix
      treefmtEval = eachSystem (pkgs: treefmt-nix.lib.evalModule pkgs ./treefmt.nix);
    in
    {
      # for `nix fmt`
      formatter = eachSystem (pkgs: treefmtEval.${pkgs.system}.config.build.wrapper);
      # for `nix flake check`
      checks = eachSystem (pkgs: {
        formatting = treefmtEval.${pkgs.system}.config.build.check self;
      });
    };
}

另外，请添加 treefmt.nix 文件（或者，如果您愿意，也可以将内容内联）：

# treefmt.nix
{ pkgs, ... }:
{
  # Used to find the project root
  projectRootFile = "flake.nix";
  # Enable the terraform formatter
  programs.terraform.enable = true;
  # Override the default package
  programs.terraform.package = pkgs.terraform_1;
  # Override the default settings generated by the above option
  settings.formatter.terraform.excludes = [ "hello.tf" ];
}

此文件也是定义所有 treefmt 参数（如 includes、excludes 和 formatter 选项）的地方。

指定 flake 后，运行 nix fmt:

$ nix fmt

Nix-fmt 是一个用于格式化项目中所有 nix 文件的工具，但在使用指定的 flake 时，它会启动 treefmt-nix 并格式化你的项目。

你也可以运行 nix flake check（例如：在 CI 中）来验证项目的代码是否已正确格式化。

Flake-parts

此 flake 还暴露了一个 flake-parts 模块。要使用它：

将 inputs.treefmt-nix.flakeModule 添加到你的 flake-parts 调用中的 imports 列表。
将 treefmt = { .. }（包含上述配置）添加到你的 perSystem。

示例请参见 https://github.com/nix-community/buildbot-nix/blob/2695e33353d7bffb2073dc6a1789502dd9e7b9fd/nix/treefmt/flake-module.nix

配置

在 nix 之外处理 treefmt 时，格式化器配置以 toml 格式指定。相反，使用 nix 时，你使用 nix 语法编写，如下所示：

# Used to find the project root
projectRootFile = ".git/config";
# Enable the terraform formatter
programs.terraform.enable = true;
# Override the default package
programs.terraform.package = nixpkgs.terraform_1;
# Override the default settings generated by the above option
settings.formatter.terraform.excludes = [ "hello.tf" ];

选项：

Project root file 是您计划格式化的项目的 git 文件。
选项 programs.terraform.enable 启用所需的格式化器。您可以指定任意数量的格式化器。例如：

programs.terraform.enable = true;
programs.gofmt.enable = true;

选项 programs.terraform.package 允许你使用指定格式化工具的特定构建/版本。
通过设置settings.formatter.terraform.excludes，你可以标记应排除在格式化之外的文件。你还可以通过此方式指定其他格式化工具选项或包含项。

有关选项的详细说明，请参阅 treefmt 文档。

项目结构

此仓库包含一个顶层 default.nix，用于返回库辅助函数。

mkWrapper 是主函数，它使用所需的配置来封装 treefmt。
mkConfigFile
evalModule
all-modules

支持的工具

treefmt-nix 目前支持 100 多种格式化工具：

对于非 Nix 用户，您还可以在 ./examples 文件夹中找到生成的示例。

使用自定义格式化器

使用 treefmt-nix 时，也可以使用自定义格式化器。例如，以下自定义格式化器使用 yq-go 格式化 JSON 文件：

settings.formatter = {
  "yq-json" = {
    command = "${pkgs.bash}/bin/bash";
    options = [
      "-euc"
      ''
        for file in "$@"; do
          ${lib.getExe yq-go} -i --output-format=json $file
        done
      ''
      "--" # bash swallows the second argument when using -c
    ];
    includes = [ "*.json" ];
  };
};

添加新的格式化器

欢迎提交用于添加新格式化器的 PR！

格式化器应符合格式化器规范。
这里不是讨论格式化偏好之处。请选择在你的社区中标准的默认值 —— 例如，python 通常使用 4 个空格缩进，因此不要添加一个以 2 个空格为默认值的 python 格式化器。

为了添加一个新的格式化器，请执行以下操作：

在 ./programs/ 文件夹中创建一个新的条目。
考虑将自己添加为 meta.maintainer（见下文）。
运行 ./examples.sh 以更新 ./examples 文件夹。
要测试该程序：
1. （临时）扩展项目的 ./treefmt.nix 文件以启用新的格式化器，并以适当的方式对其进行配置。
2. 在此仓库中添加一批相关的源文件 —— 例如，如果新的格式化器旨在格式化 *.foo 文件，则添加一些 *.foo 文件，其中一些格式良好（因此预期不会被 treefmt 修改），另一些格式不佳。
3. 运行 nix fmt。确认格式良好的文件未发生变化，并且格式不佳的文件被标记为如此。重新运行 nix fmt 并确认没有进行额外的更改。
4. 通过运行以下命令，在此文件的此处添加该格式化器：
```
mdsh -i README.md -o README.md
```

或使用 Nix

  ```bash
  nix run github:zimbatm/mdsh -- -i README.md -o README.md
  ```

5. 确认无误后，撤销这些更改。

提交 PR！

`meta.maintainer` 的定义

你可以通过将你的 GitHub 用户名添加到该模块的 meta.maintainers 列表中，来登记你希望协助特定格式化器的意愿。

这主要意味着，对于给定的格式化器：

如果需要做出任何决策，你拥有优先权。
如果发现任何问题，你会收到通知。

支持的 Nix 版本

treefmt-nix 支持所有已知的 Nix 版本。

如果你依赖 flakes 和 nix fmt，我们建议运行 Nix 2.25 或 Lix 2.92 或更高版本。参见 https://github.com/NixOS/nix/pull/11438

商业支持

需要帮助或定制服务？

联系 Numtide 获取报价。我们让企业轻松与开源项目合作：https://numtide.com/contact

许可证

所有代码和文档均采用 MIT 许可证授权。