nixpkgs-fmt - Nix 代码格式化工具，用于 nixpkgs

状态：beta

此项目的目标是格式化 nixpkgs 中的 nix 代码，以增加该处代码的一致性。理想情况下，通过预提交钩子和后续的 ofborg 强制执行格式化。

演示

您可以在浏览器中尝试 nixpkgs-fmt。页面还提供了您提交代码样本的方法，如果您发现输出不满意：https://nix-community.github.io/nixpkgs-fmt/

设计决策

您可能会问自己；为什么还需要另一个 nix 代码格式化工具？

nixpkgs-fmt 的主要目标是提供一些总体一致性，以用于提交给我们的主要包仓库 nixpkgs 的 nix 代码。

此时，重要的是要理解，代码格式化工具可能有多种可能的输出。这些输出将取决于多种冲突的愿望，并且根据对每个要求的重视程度，输出将发生变化。

对于 nixpkgs-fmt，我们有以下几个目标

1. 最小化合并冲突。nixpkgs 在很多拉取请求中被看到，我们希望避免它们不必要地过时。
2. 仅展开，不折叠。是否将元素放在单行或多行取决于开发者。
3. 尊重开发者的表现力。空行可以作为分离代码块的一种方式。
4. 每行只更改一个 (+/-) 的缩进。不确定为什么，但似乎是个好主意。

推论规则

• 由于（1），格式与 nixpkgs 中已有的格式非常接近。
• 由于（1），不要垂直对齐值，单行更改可以引入非常大的差异。
• 因为（1）。避免太多规则。更多的规则意味着更多的格式更改，这会导致合并冲突。
• 因为（2）。不要强制行长度。行长度限制也会产生复杂的启发式方法。

在我们开始这个项目的时候，其他格式化工具并没有采取这种加权方式。

为了实现这一点，我们需要一个空格和注释保留的解析器，它为我们提供了rnix。然后创建一个遵循AST并使用重写规则修补树的引擎。这种设计的好处是它也可以处理不完整或损坏的nix代码。我们能够格式化到缺失/损坏的部分，这使得它非常适合潜在编辑器的集成。

大多数其他格式化工具都采用了一个非常打印的方法，其中AST被解析，然后非常打印器检查并格式化AST回代码，而不考虑空格和新行。优点是它最初更容易实现。输出非常严格，相同的AST总会产生相同的输出。一个缺点是，非常打印器需要处理所有可能的Nix代码组合，使其看起来很好。

使用nixpkgs-fmt，输出将取决于代码最初是如何格式化的。开发者仍然可以决定他们想要如何格式化他们的代码。如果没有复杂的规则，代码将被保留。对于nixpkgs来说，这种做法将是首选的，因为它最小化了diff。

恭喜你阅读了所有这些，希望这能稍微澄清nixpkgs-fmt存在的原因及其所扮演的角色。

用法

$nixpkgs-fmt --帮助 2>&1 || 真

nixpkgs-fmt 0.9.0
Format Nix code

USAGE:
    nixpkgs-fmt [FLAGS] [FILE]...

FLAGS:
        --check            Only test if the formatter would produce differences
        --explain          Show which rules are violated
    -h, --help             Prints help information
        --output-format    Output syntax tree in JSON format
        --parse            Show syntax tree instead of reformatting
    -V, --version          Prints version information

ARGS:
    <FILE>...    File to reformat in place. If no file is passed, read from stdin.

树遍历

当给nixpkgs-fmt一个文件夹作为文件参数时，它将使用与ripgrep相同的ignore crate遍历该文件夹，使用8个并行线程。

默认情况下，它将自动忽略读取.ignore、.gitignore和.git/info/exclude文件的文件，顺序如下。如果需要忽略其他文件，也可以在调用中添加--exclude <glob>。

安装

nixpkgs-fmt可在nixpkgs master中找到。 nix-env --fmt。

也可以直接从该存储库安装它

nix-env-f https://github.com/nix-community/nixpkgs-fmt/archive/master.tar.gz -i

pre-commit钩子

此项目也可以作为pre-commit钩子安装。

将其添加到项目的.pre-commit-config.yaml中

-   repo: https://github.com/nix-community/nixpkgs-fmt
    rev: master
    hooks:
    -   id: nixpkgs-fmt

请确保您的环境中可用rust。

然后运行pre-commit install-hooks

开发

安装Rust和Cargo或运行nix-shell以加载项目依赖项。

安装pre-commit并运行pre-commit install以在存储库上设置git钩子。这将允许随着时间的推移保持代码格式良好。

然后使用cargo run来构建和运行软件。

运行Fuzzer

$ cargo install cargo-fuzz
$ mkdir -p ./fuzz/corpus/fmt
$ cp test_data/**.nix ./fuzz/corpus/fmt
$ rustup run nightly -- cargo fuzz run fmt

或者用nix

$ nix-shell --run "cargo fuzz run fmt"

• fmt是./fuzz/Cargo.toml中的目标名称

模糊测试器将无限期运行，或者直到它找到崩溃为止。崩溃的输入将被写入 fuzz/artifacts 目录。提交此 crash- 文件，它将被自动通过单元测试进行测试。

文档

• 如何编写新的规则
• 如何使用 WASM
• 我们的发布方式

相关项目

请随时提交您的项目！

使用 nixpkgs-fmt

• Emacs 集成，包括格式化保存的辅助模式
• rnix-lsp - Nix 的 Lambda 服务器

格式化工具

• canonix - 使用 tree-sitter-nix 语法编写的 Nix 格式化原型（Haskell 语言）。
• format-nix - 使用 tree-sitter-nix 的 Nix 格式化工具。
• nix-format - 基于 Emacs 的 Nix 格式化工具。
• nix-lsp - 使用 rnix 的 Nix 语言服务器。
• nixfmt - 使用 Haskell 编写的 Nix 格式化工具。

代码检查工具

• nix-linter

解析器

• hnix - 包含解析器的 Nix 的 Haskell 实现。解析器不保留注释。
• rnix - 基于 rowan 的 Rust Nix 解析器。
• tree-sitter-nix - Tree Sitter 是一个宽容的解析器，由 Atom 用于实时语法高亮和其他用途。这是 Nix 的实现。

讨论

• nixpkgs 风格指南
• 关于 Nix 表达式格式化
• [工作] 实现 nix-fmt 格式化工具

赞助商

此工作由 NumTide 赞助。