{"id":13648583,"url":"https://github.com/nix-community/nixpkgs-fmt","last_synced_at":"2025-10-01T06:32:05.372Z","repository":{"id":40649434,"uuid":"184640864","full_name":"nix-community/nixpkgs-fmt","owner":"nix-community","description":"Nix code formatter for nixpkgs [maintainer=@zimbatm]","archived":true,"fork":false,"pushed_at":"2024-07-24T11:56:52.000Z","size":4012,"stargazers_count":582,"open_issues_count":35,"forks_count":32,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-10-29T17:21:01.632Z","etag":null,"topics":["cli","formatter","nix","nixpkgs","pre-commit-hook","rust-crate"],"latest_commit_sha":null,"homepage":"https://nix-community.github.io/nixpkgs-fmt/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nix-community.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"nix-community"}},"created_at":"2019-05-02T19:38:08.000Z","updated_at":"2024-09-29T20:31:57.000Z","dependencies_parsed_at":"2024-05-29T16:14:01.725Z","dependency_job_id":"08c3de73-675b-4d5e-b30a-b71d986bd757","html_url":"https://github.com/nix-community/nixpkgs-fmt","commit_stats":{"total_commits":388,"total_committers":29,"mean_commits":"13.379310344827585","dds":0.6365979381443299,"last_synced_commit":"bdb15b4c7e0cb49ae091dd43113d0a938afae02c"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnixpkgs-fmt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnixpkgs-fmt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnixpkgs-fmt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnixpkgs-fmt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nix-community","download_url":"https://codeload.github.com/nix-community/nixpkgs-fmt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234837075,"owners_count":18894530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","formatter","nix","nixpkgs","pre-commit-hook","rust-crate"],"created_at":"2024-08-02T01:04:22.114Z","updated_at":"2025-10-01T06:31:59.962Z","avatar_url":"https://github.com/nix-community.png","language":"Rust","funding_links":["https://opencollective.com/nix-community"],"categories":["Rust","Command-Line Tools"],"sub_categories":["Discovery"],"readme":"# nixpkgs-fmt - Nix code formatter for nixpkgs\n\n[![CI](https://github.com/nix-community/nixpkgs-fmt/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/nix-community/nixpkgs-fmt/actions/workflows/push.yml) [![built with nix](https://builtwithnix.org/badge.svg)](https://builtwithnix.org)\n\n**STATUS: archived. Replaced by [nixfmt](https://github.com/NixOS/nixfmt).**\n\nThis project's goal was to format the nix code in nixpkgs to increase the\nconsistency of the code found there. Ideally automatically with pre-commit\nhooks and later ofborg enforcing the format.\n\n## Demo\n\nYou can try nixpkgs-fmt in your browser. The page also provides a way for you\nto submit code samples if you find the output not satisfying:\nhttps://nix-community.github.io/nixpkgs-fmt/\n\n## Design decisions\n\nYou might ask yourself; why do we need yet another nix code formatter?\n\nThe main goal of nixpkgs-fmt is to provide some overall consistency in the\nnix code submitted to [nixpkgs](https://github.com/NixOS/nixpkgs), our main\npackage repository.\n\nAt this point it's important to understand that there are multiple possible\noutputs for a code formatter. Those outputs will depend on multiple\nconflicting desires and depending on how much weight is being put on each\nrequirement the output will change.\n\nFor nixpkgs-fmt we have a few of these:\n\n1. Minimize merge conflicts. nixpkgs is seen in a lot of pull-requests and we\n   want to avoid them getting unnecessarily stale.\n2. Only expand, don't collapse. It's up to the developer to choose if an\n   element should be on a single line or multiple lines.\n3. Respect the developer's expressivity. Empty lines can be useful as a way to\n   separate blocks of code.\n4. Only change the indent of one (+/-) per line. Not sure why but it seems\n   like a good thing.\n\nCorollary rules:\n\n* because of (1). The format is quite close to what exists in nixpkgs already.\n* because of (1). Don't align values vertically, a single line change can\n  introduce a very big diff.\n* because of (1). Avoid too many rules. More rules means more formatting\n  changes that create merge conflicts.\n* because of (2). Don't enforce line lengths. Line length limits also create\n  complicated heuristics.\n\nAt the time where we started this project none of the other formatters were\nweighted that way.\n\nTo implement this, we needed a whitespace and comment-preserving parser which\n[rnix](https://github.com/nix-community/rnix-parser) provides to us. Then create\nan engine that follows the AST and patches the tree with rewrite rules. The nice\nthing about this design is that it also works on incomplete or broken nix code.\nWe are able to format up to the part that is missing/broken, which makes it\ngreat for potential editor integration.\n\nMost of the other formatters out there take a pretty-printing approach where\nthe AST is parsed, and then a pretty-printer inspects and formats the AST back\nto code without taking spaces and newlines into account. The advantage is that\nit's initially easier to implement. The output is very strict and the same AST\nwill always give the same output. One disadvantage is that the pretty-printer\nneeds to handle all the possible combination of Nix code to make them look\ngood.\n\nWith nixpkgs-fmt the output will depend on how the code was formatted\ninitially. The developer still has some input on how they want to format their\ncode. If there is no rule for a complicated case, the code will be left alone.\nFor nixpkgs this approach will be preferable since it minimizes the diff.\n\nWell done for reading all of this, I hope this clarifies a bit why nixpkgs-fmt\nexists and what role it can play.\n\n## Usage\n\n\u003c!-- `$ nixpkgs-fmt --help 2\u003e\u00261 || true` --\u003e\n```\nnixpkgs-fmt 1.2.0\nFormat Nix code\n\nUSAGE:\n    nixpkgs-fmt [FLAGS] [OPTIONS] [FILE]...\n\nFLAGS:\n        --check      Only test if the formatter would produce differences\n        --explain    Show which rules are violated\n    -h, --help       Prints help information\n        --parse      Show syntax tree instead of reformatting\n    -V, --version    Prints version information\n\nOPTIONS:\n        --output-format \u003cFORMAT\u003e    Set output format of --parse [default: rnix]  [possible values: rnix, json]\n\nARGS:\n    \u003cFILE\u003e...    File to reformat in place. If no file is passed, read from stdin.\n```\n### Tree traversal\n\nWhen `nixpkgs-fmt` is given a folder as a file argument, it will traverse that\nusing the same [ignore crate](https://crates.io/crates/ignore) as ripgrep,\nusing 8 parallel threads.\n\nBy default it will automatically ignore files reading `.ignore`, `.gitignore`,\nand `.git/info/exclude` files in that order. If additional files need to be\nignored, it is also possible to add `--exclude \u003cglob\u003e` to the call.\n\n## Installation\n\nnixpkgs-fmt is available in nixpkgs master. `nix-env -i nixpkgs-fmt`.\n\nIt's also possible to install it directly from this repository:\n\n`nix-env -f https://github.com/nix-community/nixpkgs-fmt/archive/master.tar.gz -iA nixpkgs-fmt`\n\n### VSCode extensions\n\nThere are a few VSCode extensions that make using `nixpkgs-fmt` convenient. \nCheck out:\n\n- [B4dM4n.nixpkgs-fmt](https://marketplace.visualstudio.com/items?itemName=B4dM4n.nixpkgs-fmt)\n- [jnoortheen.nix-ide](https://marketplace.visualstudio.com/items?itemName=jnoortheen.nix-ide)\n\n### pre-commit hook\n\nThis project can also be installed as a [pre-commit](https://pre-commit.com/)\nhook.\n\nAdd to your project's `.pre-commit-config.yaml`:\n\n```yaml\n-   repo: https://github.com/nix-community/nixpkgs-fmt\n    rev: master\n    hooks:\n    -   id: nixpkgs-fmt\n```\n\nMake sure to have rust available in your environment.\n\nThen run `pre-commit install-hooks`\n\n## Development\n\nInstall Rust and Cargo or run `nix-shell` to load the project dependencies.\n\nInstall [pre-commit](https://pre-commit.com/) and run `pre-commit install` to\nsetup the git hooks on the repository. This will allow to keep the code nicely\nformatted over time.\n\nThen use `cargo run` to build and run the software.\n\n### Running Fuzzer\n\n```\n$ cargo install cargo-fuzz\n$ mkdir -p ./fuzz/corpus/fmt\n$ cp test_data/**.nix ./fuzz/corpus/fmt\n$ rustup run nightly -- cargo fuzz run fmt\n```\n\nor with nix:\n\n```\n$ nix-shell --run \"cargo fuzz run fmt\"\n```\n\n* `fmt` is the name of the target in `./fuzz/Cargo.toml`\n\nFuzzer will run indefinitely or until it finds a crash.\nThe crashing input is written to `fuzz/artifacts` directory.\nCommit this `crash-` file, and it will be automatically tested by a unit-test.\n\n## Documentation\n\n* [HOWTO write new rules](docs/howto_rules.md)\n* [HOWTO WASM](wasm/README.md)\n* [How we do releases](docs/releasing.md)\n\n## Related projects\n\nFeel free to submit your project!\n\n### Using nixpkgs-fmt\n\n* [Emacs integration, including minor mode for format-on-save](https://github.com/purcell/emacs-nixpkgs-fmt)\n* [rnix-lsp](https://github.com/nix-community/rnix-lsp) - A Lambda Server for Nix\n\n\n### Formatters\n\n* [alejandra](https://github.com/kamadorueda/alejandra) - Another rnix based formatter, using a rule based engine.\n* [canonix](https://github.com/hercules-ci/canonix/) - Nix formatter prototype written in Haskell using the tree-sitter-nix grammar.\n* [format-nix](https://github.com/justinwoo/format-nix/) - A nix formatter using tree-sitter-nix.\n* [nix-format](https://github.com/taktoa/nix-format) - Emacs-based Nix formatter.\n* [nix-lsp](https://gitlab.com/jD91mZM2/nix-lsp) - Nix language server using rnix.\n* [nixfmt](https://github.com/serokell/nixfmt) - A nix formatter written in Haskell.\n\n### Linters\n\n* [nix-linter](https://github.com/Synthetica9/nix-linter)\n\n### Parsers\n\n* [hnix](https://github.com/haskell-nix/hnix) - Haskell implementation of Nix including a parser. The parser is not comment-preserving.\n* [rnix](https://github.com/nix-community/rnix-parser) - Rust Nix parser based on [rowan](https://github.com/rust-analyzer/rowan)\n* [tree-sitter-nix](https://github.com/cstrahan/tree-sitter-nix) - Tree Sitter is a forgiving parser used by Atom for on-the-fly syntax highlighting and others. This is a implementation for Nix.\n\n## Discussions\n\n* [nixpkgs style guide](https://nixos.org/nixpkgs/manual/#sec-syntax)\n* [On Nix expression formatting](https://discourse.nixos.org/t/on-nix-expression-formatting/1521/14)\n* [[Job] Implement a `nix-fmt` formatter](https://discourse.nixos.org/t/job-implement-a-nix-fmt-formatter/2819/12)\n\n## Sponsors\n\nThis work has been sponsored by [NumTide](https://numtide.com).\n\n\u003cimg src=\"https://numtide.com/logo.png\" alt=\"NumTide Logo\" width=\"80\"\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnix-community%2Fnixpkgs-fmt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnix-community%2Fnixpkgs-fmt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnix-community%2Fnixpkgs-fmt/lists"}