Skip to content

Configure

treefmt's behaviour can be influenced in one of three ways:

  1. Process flags and arguments
  2. Environment variables
  3. A TOML based config file

There is an order of precedence between these mechanisms as listed above, with process flags having the highest precedence and values in the configuration file having the lowest.

Note

Some options can only be configured as process flags, others may support process flags and environment variables, and others still may support all three mechanisms.

Config File

The treefmt configuration file is a mixture of global options and formatter sections.

It should be named treefmt.toml or .treefmt.toml, and typically resides at the root of a repository.

When executing treefmt within a subdirectory, treefmt will search upwards in the directory structure, looking for treefmt.toml or .treefmt.toml. You can change this behaviour using the config-file options

Tip

When starting a new project you can generate an initial config file using treefmt --init

treefmt.toml
 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
# The formatter multiplexer - https://github.com/numtide/treefmt

# Do not exit with error if a configured formatter is missing
# Env $TREEFMT_ALLOW_MISSING_FORMATTER
# allow-missing-formatter = true

# The file into which a cpu profile will be written
# Env $TREEFMT_CPU_PROFILE
# cpu-profile = ./cpu.pprof

# Exclude files or directories matching the specified globs
# Env $TREEFMT_EXCLUDES
# excludes = ["*.md", "*.gif"]

# Exit with error if any changes were made during execution
# Useful for CI
# Env $TREEFMT_FAIL_ON_CHANGE
# fail-on-change = true

# A list of formatters to apply
# Defaults to all configured formatters
# Env $TREEFMT_FORMATTERS
# formatters = ["gofmt", "prettier"]

# 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
# on-unmatched = "info"

# The root directory from which treefmt will start walking the filesystem
# Defaults to the directory containing the config file
# Env $TREEFMT_TREE_ROOT
# tree-root = "/tmp/foo"

# File to search for to find the tree root (if tree-root is not set)
# Env $TREEFMT_TREE_ROOT_FILE
# tree-root-file = ".git/config"

# Set the verbosity of logs
# 0 = warn, 1 = info, 2 = debug
# Env $TREEFMT_VERBOSE
# verbose = 2

# The method used to traverse the files within the tree root
# Currently, we support 'auto', 'git' or 'filesystem'
# Env $TREEFMT_WALK
# walk = "filesystem"

[formatter.mylanguage]
# Command to execute
command = "command-to-run"
# Command-line arguments for the command
options = []
# Glob pattern of files to include
includes = [ "*.<language-extension>" ]
# Glob patterns of files to exclude
excludes = []
# Controls the order of application when multiple formatters match the same file
# Lower the number, the higher the precedence
# Default is 0
priority = 0

Global Options

allow-missing-formatter

Do not exit with error if a configured formatter is missing.

1
treefmt --allow-missing-formatter true

1
TREEFMT_ALLOW_MISSING_FORMATTER=true treefmt

1
allow-missing-formatter = true

ci

Runs treefmt in a CI mode, enabling no-cache, fail-on-change and adjusting some other settings best suited to a continuous integration environment.

1
treefmt --ci

1
TREEFMT_CI=true treefmt

clear-cache

Reset the evaluation cache. Use in case the cache is not precise enough.

1
2
treefmt -c
treefmt --clear-cache

1
TREEFMT_CLEAR_CACHE=true treefmt

config-file

1
treefmt --config-file /tmp/treefmt.toml

1
TREEFMT_CONFIG=/tmp/treefmt.toml treefmt

cpu-profile

The file into which a pprof cpu profile will be written.

1
treefmt --cpu-profile ./cpu.pprof

1
TREEFMT_CPU_PROFILE=./cpu.pprof treefmt

1
cpu-profile = "./cpu.pprof"

excludes

An optional list of glob patterns used to exclude files from all formatters.

1
treefmt --excludes *.toml,*.php,README

1
TREEFMT_EXCLUDES="*.toml,*.php,README" treefmt

1
excludes = ["*.toml", "*.php", "README"]

fail-on-change

Exit with error if any changes were made during execution.

1
treefmt --fail-on-change true

1
TREEFMT_FAIL_ON_CHANGE=true treefmt

1
fail-on-change = true

formatters

A list of formatters to apply. Defaults to all configured formatters.

1
2
treefmt -f go,toml,haskell
treefmt --formatters go,toml,haskell

1
TREEFMT_FORMATTERS=go,toml,haskell treefmt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
formatters = ["go", "toml", "haskell"]

[formatter.go]
...

[formatter.toml]
...

[formatter.haskell]
...

[formatter.ruby]
...

[formatter.shellcheck]
...

no-cache

Ignore the evaluation cache entirely. Useful for CI.

1
treefmt --no-cache

1
TREEFMT_NO_CACHE=true treefmt

on-unmatched

Log paths that did not match any formatters at the specified log level. Possible values are <debug|info|warn|error|fatal>.

Warning

If you select fatal, the process will exit immediately with a non-zero exit.

1
2
treefmt -u debug
treefmt --on-unmatched debug

1
TREEFMT_ON_UNMACTHED=info treefmt

1
on-unmatched = "debug"

stdin

Format the context passed in via stdin.

Note

You must provide a single path argument, the value of which is used to match against the configured formatters.

1
cat ../test.go | treefmt --stdin foo.go

tree-root

The root directory from which treefmt will start walking the filesystem. Defaults to the directory containing the config file.

1
treefmt --tree-root /tmp/foo

1
TREEFMT_TREE_ROOT=/tmp/foo treefmt

1
tree-root = "/tmp/foo"

tree-root-file

File to search for to find the tree root (if tree-root is not set)

1
treefmt --tree-root-file .git/config

1
TREEFMT_TREE_ROOT_FILE=.git/config treefmt

1
tree-root-file = ".git/config"

verbose

Set the verbosity level of logs:

  • 0 => warn
  • 1 => info
  • 2 => debug

The number of v's passed matches the level set.

1
treefmt -vv

1
TREEFMT_VERBOSE=1 treefmt

1
verbose = 2

walk

The method used to traverse the files within the tree root. Currently, we support 'auto', 'git' or 'filesystem'

1
treefmt --walk filesystem

1
TREEFMT_WALK=filesystem treefmt

1
walk = "filesystem"

working-dir

Run as if treefmt was started in the specified working directory instead of the current working directory.

1
2
treefmt -C /tmp/foo
treefmt --working-dir /tmp/foo

1
TREEFMT_WORKING_DIR=/tmp/foo treefmt

Formatter Options

Formatters are configured using a table entry in treefmt.toml of the form [formatter.<name>]:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[formatter.alejandra]
command = "alejandra"
includes = ["*.nix"]
excludes = ["examples/nix/sources.nix"]
priority = 1

[formatter.deadnix]
command = "deadnix"
options = ["-e"]
includes = ["*.nix"]
priority = 2

command

The command to invoke when applying the formatter.

options

An optional list of args to be passed to command.

includes

A list of glob patterns used to determine whether the formatter should be applied against a given path.

excludes

An optional list of glob patterns used to exclude certain files from this formatter.

priority

Influences the order of execution. Greater precedence is given to lower numbers, with the default being 0.

Same file, multiple formatters?

For each file, treefmt determines a list of formatters based on the configured includes / excludes rules. This list is then sorted, first by priority (lower the value, higher the precedence) and secondly by formatter name (lexicographically).

The resultant sequence of formatters is used to create a batch key, and similarly matched files get added to that batch until it is full, at which point the files are passed to each formatter in turn.

This means that treefmt guarantees only one formatter will be operating on a given file at any point in time. Another consequence is that formatting is deterministic for a given file and a given treefmt configuration.

By setting the priority fields appropriately, you can control the order in which those formatters are applied for any files they both happen to match on.

Glob patterns format

This is a variant of the Unix glob pattern. It supports all the usual selectors such as * and ?.

Examples

  • *.go - match all files in the project that end with a ".go" file extension.
  • vendor/* - match all files under the vendor folder, recursively.

Supported Formatters

Any formatter that follows the spec is supported out of the box.

Already 60+ formatters are supported.

To find examples, take a look at https://github.com/numtide/treefmt-nix/tree/main/examples.

If you are a Nix user, you might also like https://github.com/numtide/treefmt-nix, which uses Nix to pull in the right formatter package and seamlessly integrates both together.