{"id":18465539,"url":"https://github.com/numtide/treefmt-nix","last_synced_at":"2025-05-15T16:07:14.842Z","repository":{"id":63633759,"uuid":"540363138","full_name":"numtide/treefmt-nix","owner":"numtide","description":"treefmt nix configuration","archived":false,"fork":false,"pushed_at":"2025-05-15T08:51:58.000Z","size":492,"stargazers_count":384,"open_issues_count":31,"forks_count":105,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-15T09:41:29.658Z","etag":null,"topics":["buildbot-numtide","flake-parts","nix","treefmt"],"latest_commit_sha":null,"homepage":"https://treefmt.com","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/numtide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"supported-programs.sh","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-23T09:13:45.000Z","updated_at":"2025-05-15T08:52:02.000Z","dependencies_parsed_at":"2023-02-18T07:01:11.463Z","dependency_job_id":"e1f2f24e-d154-48ca-977f-b8f77595579f","html_url":"https://github.com/numtide/treefmt-nix","commit_stats":{"total_commits":269,"total_committers":79,"mean_commits":"3.4050632911392404","dds":0.8252788104089219,"last_synced_commit":"5f5c2787576f3e39bbc2ebdbf8521b3177c5c19c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Ftreefmt-nix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Ftreefmt-nix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Ftreefmt-nix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Ftreefmt-nix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/numtide","download_url":"https://codeload.github.com/numtide/treefmt-nix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374475,"owners_count":22060611,"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":["buildbot-numtide","flake-parts","nix","treefmt"],"created_at":"2024-11-06T09:13:26.539Z","updated_at":"2025-05-15T16:07:14.836Z","avatar_url":"https://github.com/numtide.png","language":"Nix","funding_links":[],"categories":["nix","Flake Modules","Nix","Development"],"sub_categories":["Community Modules","Discovery"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# treefmt-nix\n\n\u003cimg src=\"https://avatars.githubusercontent.com/u/20373834\" height=\"150\"/\u003e\n\n**Fast and convenient multi-file formatting with Nix**\n\n_A \u003ca href=\"https://numtide.com/\"\u003enumtide\u003c/a\u003e project._\n\n\u003cp\u003e\n\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/Status-stable-green\"\u003e\n\u003ca href=\"https://app.element.io/#/room/#home:numtide.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Support-%23numtide-blue\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n[treefmt](https://numtide.github.io/treefmt) combines file formatters for\nmultiple programming languages so that you can format all your project files\nwith a single command. With `treefmt-nix` you can specify `treefmt` build\noptions, dependencies and config in one place, conveniently managed by\n[Nix](https://nixos.org/).\n\n`treefmt-nix` automatically installs and configures the desired formatters as\nwell as `treefmt` for you and integrates nicely into your Nix development\nenvironments. It comes with sane, pre-crafted\n[formatter-configs](https://github.com/numtide/treefmt-nix/tree/main/programs)\nmaintained by the community; each config corresponds to a section that you would\nnormally add to the `treefmt` config file `treefmt.toml`.\n\nTake a look at the already [supported formatters](#supported-programs) for\nPython, Rust, Go, Haskell and more.\n\n## Integration into Nix\n\n### Nix classic without flakes\n\nTo run `treefmt-nix` with nix-classic, import the repo using\n[`niv`](https://github.com/nmattia/niv):\n\n```\n$ niv add numtide/treefmt-nix\n```\n\nAlternatively, you can download the source and run `nix-build` in the project\nroot directory:\n\n```\n$ nix-build\n```\n\nThe command will return the helper functions which will be later used to produce\na derivation from the specified `treefmt-nix` configuration.\n\nAfter you installed treefmt-nix, specify the formatter configuration. For\ninstance, this one is for formatting terraform files:\n\n```nix\n# myfile.nix\n{ system ? builtins.currentSystem }:\nlet\n  nixpkgsSrc = builtins.fetchTarball \"https://github.com/NixOS/nixpkgs/archive/refs/heads/nixos-unstable.tar.gz\";\n  treefmt-nixSrc = builtins.fetchTarball \"https://github.com/numtide/treefmt-nix/archive/refs/heads/master.tar.gz\";\n  nixpkgs = import nixpkgsSrc { inherit system; };\n  treefmt-nix = import treefmt-nixSrc;\nin\ntreefmt-nix.mkWrapper nixpkgs {\n  # Used to find the project root\n  projectRootFile = \".git/config\";\n  # Enable the terraform formatter\n  programs.terraform.enable = true;\n  # Override the default package\n  programs.terraform.package = nixpkgs.terraform_1;\n  # Override the default settings generated by the above option\n  settings.formatter.terraform.excludes = [ \"hello.tf\" ];\n}\n```\n\nIt's a good practice to place the configuration file in the project root\ndirectory.\n\nNext, execute this command:\n\n```\n$ nix-build myfile.nix\n```\n\nThis command returns a derivation that contains a `treefmt` binary at\n`./result/bin/treefmt` in your current directory. The file is actually a symlink\nto the artifact in `/nix/store`.\n\n`treefmt.toml` in this case isn't generated: the binary is wrapped with the\nconfig.\n\n### Flakes\n\nRunning treefmt-nix with flakes isn't hard. The library is exposed as the `lib`\nattribute:\n\n```nix\n# flake.nix\n{\n  inputs.treefmt-nix.url = \"github:numtide/treefmt-nix\";\n\n  outputs = { self, nixpkgs, systems, treefmt-nix }:\n    let\n      # Small tool to iterate over each systems\n      eachSystem = f: nixpkgs.lib.genAttrs (import systems) (system: f nixpkgs.legacyPackages.${system});\n\n      # Eval the treefmt modules from ./treefmt.nix\n      treefmtEval = eachSystem (pkgs: treefmt-nix.lib.evalModule pkgs ./treefmt.nix);\n    in\n    {\n      # for `nix fmt`\n      formatter = eachSystem (pkgs: treefmtEval.${pkgs.system}.config.build.wrapper);\n      # for `nix flake check`\n      checks = eachSystem (pkgs: {\n        formatting = treefmtEval.${pkgs.system}.config.build.check self;\n      });\n    };\n}\n```\n\nAnd also add the `treefmt.nix` file (or put the content inline if you prefer):\n\n```nix\n# treefmt.nix\n{ pkgs, ... }:\n{\n  # Used to find the project root\n  projectRootFile = \"flake.nix\";\n  # Enable the terraform formatter\n  programs.terraform.enable = true;\n  # Override the default package\n  programs.terraform.package = pkgs.terraform_1;\n  # Override the default settings generated by the above option\n  settings.formatter.terraform.excludes = [ \"hello.tf\" ];\n}\n```\n\nThis file is also the place to define all the treefmt parameters like includes,\nexcludes and formatter options.\n\nAfter specifying the flake, run\n[`nix fmt`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-fmt.html):\n\n```\n$ nix fmt\n```\n\nNix-fmt is a tool to format all nix files in the project, but with the specified\nflake, it starts treefmt-nix and formats your project.\n\nYou can also run `nix flake check` (eg: in CI) to validate that the project's\ncode is properly formatted.\n\n### Flake-parts\n\nThis flake exposes a [flake-parts](https://flake.parts/) module as well. To use\nit:\n\n1. Add `inputs.treefmt-nix.flakeModule` to the `imports` list of your\n   `flake-parts` call.\n\n2. Add `treefmt = { .. }` (containing the configuration above) to your\n   `perSystem`.\n\nAs an example, see\n\u003chttps://github.com/nix-community/buildbot-nix/blob/2695e33353d7bffb2073dc6a1789502dd9e7b9fd/nix/treefmt/flake-module.nix\u003e\n\n## Configuration\n\nWhile dealing with `treefmt` outside of `nix`, the formatter configuration is\nspecified in a `toml` format. On the contrary, with `nix`, you write in with a\nnix syntax like this:\n\n```nix\n# Used to find the project root\nprojectRootFile = \".git/config\";\n# Enable the terraform formatter\nprograms.terraform.enable = true;\n# Override the default package\nprograms.terraform.package = nixpkgs.terraform_1;\n# Override the default settings generated by the above option\nsettings.formatter.terraform.excludes = [ \"hello.tf\" ];\n```\n\n**Options:**\n\n- `Project root file` is the git file of the project which you plan to format.\n- The option `programs.terraform.enable` enables the needed formatter. You can\n  specify as many formatter as you want. For instance:\n\n```\nprograms.terraform.enable = true;\nprograms.gofmt.enable = true;\n```\n\n- The option `programs.terraform.package` allows you to use a particular\n  build/version of the specified formatter.\n- By setting`settings.formatter.terraform.excludes` you can mark the files which\n  should be excluded from formatting. You can also specify other formatter\n  options or includes this way.\n\nFor detailed description of the options, refer to the `treefmt`\n[documentation](https://treefmt.com/latest/getting-started/configure/).\n\n## Project structure\n\nThis repo contains a top-level `default.nix` that returns the library helper\nfunctions.\n\n- `mkWrapper` is the main function which wraps treefmt with the needed\n  configuration.\n- `mkConfigFile`\n- `evalModule`\n- `all-modules`\n\n## Supported programs\n\n\u003c!-- `\u003e bash ./supported-programs.sh` --\u003e\n\n\u003c!-- BEGIN mdsh --\u003e\n`treefmt-nix` currently supports 103 formatters:\n\n* [actionlint](programs/actionlint.nix)\n* [alejandra](programs/alejandra.nix)\n* [asmfmt](programs/asmfmt.nix)\n* [beautysh](programs/beautysh.nix)\n* [biome](programs/biome.nix)\n* [black](programs/black.nix)\n* [buf](programs/buf.nix)\n* [buildifier](programs/buildifier.nix)\n* [cabal-fmt](programs/cabal-fmt.nix)\n* [clang-format](programs/clang-format.nix)\n* [cljfmt](programs/cljfmt.nix)\n* [cmake-format](programs/cmake-format.nix)\n* [csharpier](programs/csharpier.nix)\n* [cue](programs/cue.nix)\n* [d2](programs/d2.nix)\n* [dart-format](programs/dart-format.nix)\n* [deadnix](programs/deadnix.nix)\n* [deno](programs/deno.nix)\n* [dhall](programs/dhall.nix)\n* [dnscontrol](programs/dnscontrol.nix)\n* [dos2unix](programs/dos2unix.nix)\n* [dprint](programs/dprint.nix)\n* [efmt](programs/efmt.nix)\n* [elm-format](programs/elm-format.nix)\n* [erlfmt](programs/erlfmt.nix)\n* [fantomas](programs/fantomas.nix)\n* [fish_indent](programs/fish_indent.nix)\n* [fnlfmt](programs/fnlfmt.nix)\n* [formatjson5](programs/formatjson5.nix)\n* [fourmolu](programs/fourmolu.nix)\n* [fprettify](programs/fprettify.nix)\n* [gdformat](programs/gdformat.nix)\n* [genemichaels](programs/genemichaels.nix)\n* [gleam](programs/gleam.nix)\n* [gofmt](programs/gofmt.nix)\n* [gofumpt](programs/gofumpt.nix)\n* [goimports](programs/goimports.nix)\n* [golines](programs/golines.nix)\n* [google-java-format](programs/google-java-format.nix)\n* [hclfmt](programs/hclfmt.nix)\n* [hlint](programs/hlint.nix)\n* [isort](programs/isort.nix)\n* [jsonfmt](programs/jsonfmt.nix)\n* [jsonnet-lint](programs/jsonnet-lint.nix)\n* [jsonnetfmt](programs/jsonnetfmt.nix)\n* [just](programs/just.nix)\n* [keep-sorted](programs/keep-sorted.nix)\n* [ktfmt](programs/ktfmt.nix)\n* [ktlint](programs/ktlint.nix)\n* [latexindent](programs/latexindent.nix)\n* [leptosfmt](programs/leptosfmt.nix)\n* [mdformat](programs/mdformat.nix)\n* [mdsh](programs/mdsh.nix)\n* [meson](programs/meson.nix)\n* [mix-format](programs/mix-format.nix)\n* [muon](programs/muon.nix)\n* [mypy](programs/mypy.nix)\n* [nickel](programs/nickel.nix)\n* [nimpretty](programs/nimpretty.nix)\n* [nixfmt-classic](programs/nixfmt-classic.nix)\n* [nixfmt-rfc-style](programs/nixfmt-rfc-style.nix)\n* [nixfmt](programs/nixfmt.nix)\n* [nixpkgs-fmt](programs/nixpkgs-fmt.nix)\n* [nufmt](programs/nufmt.nix)\n* [ocamlformat](programs/ocamlformat.nix)\n* [odinfmt](programs/odinfmt.nix)\n* [opa](programs/opa.nix)\n* [ormolu](programs/ormolu.nix)\n* [oxipng](programs/oxipng.nix)\n* [packer](programs/packer.nix)\n* [perltidy](programs/perltidy.nix)\n* [php-cs-fixer](programs/php-cs-fixer.nix)\n* [pinact](programs/pinact.nix)\n* [prettier](programs/prettier.nix)\n* [protolint](programs/protolint.nix)\n* [purs-tidy](programs/purs-tidy.nix)\n* [rubocop](programs/rubocop.nix)\n* [ruff-check](programs/ruff-check.nix)\n* [ruff-format](programs/ruff-format.nix)\n* [rufo](programs/rufo.nix)\n* [rustfmt](programs/rustfmt.nix)\n* [scalafmt](programs/scalafmt.nix)\n* [shellcheck](programs/shellcheck.nix)\n* [shfmt](programs/shfmt.nix)\n* [sql-formatter](programs/sql-formatter.nix)\n* [sqlfluff-lint](programs/sqlfluff-lint.nix)\n* [sqlfluff](programs/sqlfluff.nix)\n* [sqruff](programs/sqruff.nix)\n* [statix](programs/statix.nix)\n* [stylish-haskell](programs/stylish-haskell.nix)\n* [stylua](programs/stylua.nix)\n* [swift-format](programs/swift-format.nix)\n* [taplo](programs/taplo.nix)\n* [templ](programs/templ.nix)\n* [terraform](programs/terraform.nix)\n* [texfmt](programs/texfmt.nix)\n* [toml-sort](programs/toml-sort.nix)\n* [typos](programs/typos.nix)\n* [typstfmt](programs/typstfmt.nix)\n* [typstyle](programs/typstyle.nix)\n* [yamlfmt](programs/yamlfmt.nix)\n* [zig](programs/zig.nix)\n* [zprint](programs/zprint.nix)\n\u003c!-- END mdsh --\u003e\n\nFor non-Nix users, you can also find the generated examples in the\n[./examples](./examples) folder.\n\n### Using a custom formatter\n\nIt is also possible to use custom formatters with `treefmt-nix`. For example,\nthe following custom formatter formats JSON files using `yq-go`:\n\n```nix\nsettings.formatter = {\n  \"yq-json\" = {\n    command = \"${pkgs.bash}/bin/bash\";\n    options = [\n      \"-euc\"\n      ''\n        for file in \"$@\"; do\n          ${lib.getExe yq-go} -i --output-format=json $file\n        done\n      ''\n      \"--\" # bash swallows the second argument when using -c\n    ];\n    includes = [ \"*.json\" ];\n  };\n};\n```\n\n### Adding new formatters\n\nPRs to add new formatters are welcome!\n\n- The formatter should conform to the\n  [formatter specifications](https://treefmt.com/latest/reference/formatter-spec/).\n- This is not the place to debate formatting preferences. Please pick defaults\n  that are standard in your community -- for instance, python is usually\n  indented with 4 spaces, so don't add a python formatter with 2 spaces as the\n  default.\n\nIn order to add a new formatter do the following things:\n\n1. Create a new entry in the `./programs/` folder.\n2. Consider adding yourself as the `meta.maintainer` (see below).\n3. Run `./examples.sh` to update the `./examples` folder.\n4. To test the program:\n\n   1. Extend the project's `./treefmt.nix` file (temporarily) to enable the new\n      formatter and configure it in whatever manner is appropriate.\n   2. Add a bunch of pertinent sources in this repo -- for instance, if the new\n      formatter is meant to format `*.foo` files, add a number of `*.foo` files,\n      some well-formatted (and therefore expected to be exempt from modification\n      by `treefmt`) and some badly-formatted.\n   3. Run `nix fmt`. Confirm that well-formatted files are unchanged and that\n      badly-formatted files are flagged as such. Re-run `nix fmt` and confirm\n      that no additional changes were made.\n   4. Add the formatter to this file [here](#supported-programs) by running:\n\n      ```bash\n      mdsh -i README.md -o README.md\n      ```\n\n      or with Nix\n\n      ```bash\n      nix run github:zimbatm/mdsh -- -i README.md -o README.md\n      ```\n\n   5. Once this is good, revert those changes.\n\n5. Submit the PR!\n\n### Definition of a `meta.maintainer`\n\nYou can register your desire to help with a specific formatter by adding your\nGitHub handle to the module's `meta.maintainers` list.\n\nThat mostly means, for the given formatter:\n\n- You get precedence if any decisions need to be made.\n- Getting pinged if any issue is being found.\n\n## Supported Nix versions\n\ntreefmt-nix works with all known Nix version.\n\nIf you rely on flakes and `nix fmt`, we recommend running Nix 2.25 or Lix 2.92\nor later. See https://github.com/NixOS/nix/pull/11438\n\n## Commercial support\n\nLooking for help or customization?\n\nGet in touch with Numtide to get a quote. We make it easy for companies to work\nwith Open Source projects: \u003chttps://numtide.com/contact\u003e\n\n## License\n\nAll the code and documentation is licensed with the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumtide%2Ftreefmt-nix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumtide%2Ftreefmt-nix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumtide%2Ftreefmt-nix/lists"}