Skip to content

Usage

treefmt has the following specification:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
The formatter multiplexer

Usage:
  treefmt <paths...> [flags]

Flags:
      --allow-missing-formatter   Do not exit with error if a configured formatter is missing. (env $TREEFMT_ALLOW_MISSING_FORMATTER)
      --ci                        Runs treefmt in a CI mode, enabling --no-cache, --fail-on-change and adjusting some other settings best suited to a CI use case. (env $TREEFMT_CI)
  -c, --clear-cache               Reset the evaluation cache. Use in case the cache is not precise enough. (env $TREEFMT_CLEAR_CACHE)
      --completion string         [bash|zsh|fish] Generate shell completion scripts for the specified shell.
      --config-file string        Load the config file from the given path (defaults to searching upwards for treefmt.toml or .treefmt.toml).
      --cpu-profile string        The file into which a cpu profile will be written. (env $TREEFMT_CPU_PROFILE)
      --excludes strings          Exclude files or directories matching the specified globs. (env $TREEFMT_EXCLUDES)
      --fail-on-change            Exit with error if any changes were made. Useful for CI. (env $TREEFMT_FAIL_ON_CHANGE)
  -f, --formatters strings        Specify formatters to apply. Defaults to all configured formatters. (env $TREEFMT_FORMATTERS)
  -h, --help                      help for treefmt
  -i, --init                      Create a treefmt.toml file in the current directory.
      --no-cache                  Ignore the evaluation cache entirely. Useful for CI. (env $TREEFMT_NO_CACHE)
  -u, --on-unmatched string       Log paths that did not match any formatters at the specified log level. Possible values are <debug|info|warn|error|fatal>. (env $TREEFMT_ON_UNMATCHED) (default "info")
  -q, --quiet                     Disable all logs except errors. (env $TREEFMT_QUIET)
      --stdin                     Format the context passed in via stdin.
      --tree-root string          The root directory from which treefmt will start walking the filesystem. Defaults to the root of the current git worktree. If not in a git repo, defaults to the directory containing the config file. (env $TREEFMT_TREE_ROOT)
      --tree-root-cmd string      Command to run to find the tree root. It is parsed using shlex, to allow quoting arguments that contain whitespace. If you wish to pass arguments containing quotes, you should use nested quotes e.g. "'" or '"'. (env $TREEFMT_TREE_ROOT_CMD)
      --tree-root-file string     File to search for to find the tree root. (env $TREEFMT_TREE_ROOT_FILE)
  -v, --verbose count             Set the verbosity of logs e.g. -vv. (env $TREEFMT_VERBOSE)
      --version                   version for treefmt
      --walk string               The method used to traverse the files within the tree root. Currently supports <auto|git|filesystem>. (env $TREEFMT_WALK) (default "auto")
  -C, --working-dir string        Run as if treefmt was started in the specified working directory instead of the current working directory. (env $TREEFMT_WORKING_DIR) (default ".")

Typically, you will execute treefmt from the root of your repository with no arguments:

1
2
3
4
❯ treefmt
traversed 106 files
emitted 9 files for processing
formatted 6 files (2 changed) in 184ms

Clear Cache

To force re-evaluation of the entire tree, you run treefmt with the -c or --clear-cache flag:

1
2
3
4
5
6
7
8
9
❯ treefmt -c
traversed 106 files
emitted 106 files for processing
formatted 56 files (0 changed) in 363ms

❯ treefmt --clear-cache
traversed 106 files
emitted 106 files for processing
formatted 56 files (0 changed) in 351ms

Change working directory

Similar to git, treefmt has an option to change working directory before executing:

1
2
3
4
❯ treefmt -C test/examples --allow-missing-formatter
traversed 106 files
emitted 56 files for processing
formatted 46 files (1 changed) in 406ms

Format files & directories

To format one or more specific files, you can pass them as arguments.

1
2
3
4
> treefmt default.nix walk/walk.go nix/devshells/renovate.nix
traversed 3 files
emitted 3 files for processing
formatted 3 files (0 changed) in 144ms

You can also pass directories:

1
2
3
4
> treefmt nix walk/cache
traversed 9 files
emitted 8 files for processing
formatted 7 files (0 changed) in 217ms

Note

When passing directories as arguments, treefmt will traverse them using the configured walk strategy.

Format stdin

Using the stdin option, treefmt can format content passed via stdin, forwarding its output to stdout:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
❯ cat default.nix | treefmt --stdin foo.nix
# This file provides backward compatibility to nix < 2.4 clients
{system ? builtins.currentSystem}: let
  lock = builtins.fromJSON (builtins.readFile ./flake.lock);

  inherit
    (lock.nodes.flake-compat.locked)
    owner
    repo
    rev
    narHash
    ;

  flake-compat = fetchTarball {
    url = "https://github.com/${owner}/${repo}/archive/${rev}.tar.gz";
    sha256 = narHash;
  };

  flake = import flake-compat {
    inherit system;
    src = ./.;
  };
in
  flake.defaultNix

Shell Completion

To generate completions for your preferred shell:

1
2
3
❯ treefmt --completion bash
❯ treefmt --completion fish
❯ treefmt --completion zsh

CI integration

We recommend using the CI option in continuous integration environments.

You can configure a treefmt job in a GitHub pipeline for Ubuntu with nix-shell like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
name: treefmt
on:
    pull_request:
    push:
        branches: main
jobs:
    formatter:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - uses: cachix/install-nix-action@v26
              with:
                  nix_path: nixpkgs=channel:nixos-unstable
            - uses: cachix/cachix-action@v14
              with:
                  name: nix-community
                  authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
            - name: treefmt
              run: nix-shell -p treefmt --run "treefmt --ci"