treefmt

When multiple formatters match a single file based on includes and excludes rules, treefmt follows these steps:

1. Sorting: The list of applicable formatters is sorted first by priority (lower numbers have higher precedence) and secondly by formatter name (lexicographically).
2. Execution: treefmt guarantees that only one formatter will be operating on a given file at any point in time.
3. Batching: Files are grouped into batches based on their unique sequence of formatters. Once a batch is full, the files are passed to the formatters in the sorted sequence.

This ensures that formatting is deterministic and that priority settings correctly control the order of operations for files that match multiple formatters.

treefmt uses a variant of Unix glob patterns for includes and excludes settings. It supports standard selectors like * and ?.

Examples:

• *.go: Matches all files ending in .go.
• vendor/*: Matches all files under the vendor directory recursively.

treefmt behavior is controlled via three mechanisms, which follow a specific order of precedence (highest to lowest):

1. Process flags and arguments
2. Environment variables
3. TOML-based configuration file

Note that not all options support all three mechanisms; some may only be available as flags, while others support all three.

You can download the latest pre-compiled treefmt binaries from the official GitHub releases page.

https://github.com/numtide/treefmt/releases

By default, treefmt emits WARN messages for every file that does not match a configured formatter. To reduce noise in your output, you can set the on-unmatched configuration key to debug in your treefmt.toml file.

If you need to temporarily see which files are unmatched during a run, you can override this setting using the --on-unmatched CLI flag.

# treefmt.toml
on-unmatched = "debug"

$ treefmt --on-unmatched warn

To start using treefmt in a new project, generate a default treefmt.toml configuration file by running the --init flag. This file should be located in your project's root folder.

$ treefmt --init

To improve your CLI experience, you can generate completion scripts for your shell using the --completion flag.

❯ treefmt --completion bash
❯ treefmt --completion fish
❯ treefmt --completion zsh

To force treefmt to re-evaluate every file in the tree instead of using cached results, use the -c or --clear-cache flag.

❯ treefmt -c
# or
❯ treefmt --clear-cache

You can pipe content into treefmt using the --stdin flag. When using --stdin, you must provide a filename (e.g., foo.nix) so treefmt knows which formatter to apply to the incoming stream. The formatted content will be sent to stdout.

❯ cat default.nix | treefmt --stdin foo.nix

You can pass specific file paths or directory paths as arguments to treefmt. When passing directories, treefmt will traverse them using the configured walk strategy.

# Format specific files
> treefmt default.nix walk/walk.go nix/devshells/renovate.nix

# Format directories
> treefmt nix walk/cache