2024-05-10 12:17:49 +03:00
---
outline: deep
---
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
# Usage
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
`treefmt` has the following specification:
2024-04-29 14:32:00 +03:00
```
2024-05-10 12:17:49 +03:00
Usage: treefmt [< paths > ...] [flags]
Arguments:
[< paths > ...] Paths to format. Defaults to formatting the whole tree.
Flags:
2024-05-31 17:00:46 +03:00
-h, --help Show context-sensitive help.
--allow-missing-formatter Do not exit with error if a configured formatter is missing.
-C, --working-directory="." Run as if treefmt was started in the specified working directory instead of the current working directory.
--no-cache Ignore the evaluation cache entirely. Useful for CI.
-c, --clear-cache Reset the evaluation cache. Use in case the cache is not precise enough.
--config-file=STRING Load the config file from the given path (defaults to searching upwards for treefmt.toml).
--fail-on-change Exit with error if any changes were made. Useful for CI.
-f, --formatters=FORMATTERS,... Specify formatters to apply. Defaults to all formatters.
--tree-root=STRING The root directory from which treefmt will start walking the filesystem (defaults to the directory containing the config file).
--tree-root-file=STRING File to search for to find the project root (if --tree-root is not passed).
--walk="auto" The method used to traverse the files within --tree-root. Currently supports 'auto', 'git' or 'filesystem'.
-v, --verbose Set the verbosity of logs e.g. -vv ($LOG_LEVEL).
-V, --version Print version.
-i, --init Create a new treefmt.toml.
-u, --on-unmatched=warn Log paths that did not match any formatters at the specified log level, with fatal exiting the process with an error. Possible values are < debug | info | warn | error | fatal > .
--stdin=STRING Format stdin, placing the output into the provided path. Formatters are matched based on the path's file extension.
--cpu-profile=STRING The file into which a cpu profile will be written.
2024-04-29 14:32:00 +03:00
```
2024-05-10 12:17:49 +03:00
## Arguments
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `[<paths> ...]`
2024-05-02 13:52:01 +03:00
2024-05-10 12:17:49 +03:00
Paths to format. Defaults to formatting the whole tree
2024-05-02 13:52:01 +03:00
2024-05-10 12:17:49 +03:00
## Flags
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `-h, --help`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Prints available flags and options
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `--allow-missing-formatter`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Do not exit with an error if some of the configured formatters are missing.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `-C, --working-directory="."`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Run as if `treefmt` was started in the specified working directory instead of the current working directory
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `--no-cache`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Tells `treefmt` to ignore the evaluation cache entirely.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
With this flag, you can avoid cache invalidation issues, if any. Typically, the machine that is running `treefmt` in
CI is starting with a fresh environment each time, so any calculated cache is lost.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
The `--no-cache` flag eliminates unnecessary work in CI.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `--config-file <config-file>`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Run with the specified config file.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `--fail-on-change`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Exit with error if any changes were made.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
This is useful for CI if you want to detect if someone forgot to format their code.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `-f, --formatters <formatters>...`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Specify formatters to apply. Defaults to all formatters.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `--tree-root="."`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
The root directory from which `treefmt` will start walking the filesystem.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `--walk <auto|git|filesystem>`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
The method used to traverse the files within `--tree-root` . Currently supports `auto` , `git` or `filesystem` .
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Default is `auto` , where we will detect if the `<tree-root>` is a git repository and use the `git` walker for
traversal. If not we will fall back to the `filesystem` walker.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `-v, --verbose`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Set the verbosity of logs e.g. `-vv` . Can also be set with an integer value in an env variable `$LOG_LEVEL` .
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Log verbosity is based off the number of 'v' used. With one `-v` , your logs will display `[INFO]` and `[ERROR]` messages,
while `-vv` will also show `[DEBUG]` messages.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `--init`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Create a new `treefmt.toml` .
2024-04-29 14:32:00 +03:00
2024-05-26 19:35:50 +03:00
### `-u --on-unmatched`
2024-05-29 12:30:13 +03:00
Log paths that did not match any formatters at the specified log level, with fatal exiting the process with an error. Possible values are < debug | info | warn | error | fatal > .
[default: warn]
2024-05-26 19:35:50 +03:00
2024-05-31 17:00:46 +03:00
### `--stdin=STRING`
2024-05-10 12:17:49 +03:00
2024-05-31 17:00:46 +03:00
Format stdin, placing the output into the provided path. Formatters are matched based on the path's file extension.
2024-05-26 19:35:50 +03:00
### `--cpu-profile`
The file into which a cpu profile will be written.
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
### `-V, --version`
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
Print version.
2024-04-29 14:32:00 +03:00
## CI integration
2024-05-10 12:17:49 +03:00
Typically, you would use `treefmt` in CI with the `--fail-on-change` and `--no-cache flags` .
2024-04-29 14:32:00 +03:00
2024-05-10 12:17:49 +03:00
You can configure a `treefmt` job in a GitHub pipeline for Ubuntu with `nix-shell` like this:
2024-04-29 14:32:00 +03:00
2024-05-01 15:54:06 +03:00
```yaml
2024-04-29 14:32:00 +03:00
name: treefmt
on:
2024-05-01 15:54:06 +03:00
pull_request:
push:
branches: main
2024-04-29 14:32:00 +03:00
jobs:
2024-05-01 15:54:06 +03:00
formatter:
runs-on: ubuntu-latest
steps:
2024-05-10 12:17:49 +03:00
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v26
2024-05-01 15:54:06 +03:00
with:
nix_path: nixpkgs=channel:nixos-unstable
2024-05-10 12:17:49 +03:00
- uses: cachix/cachix-action@v14
2024-05-01 15:54:06 +03:00
with:
name: nix-community
authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
- name: treefmt
2024-05-10 12:17:49 +03:00
run: nix-shell -p treefmt --run "treefmt --fail-on-change --no-cache"
2024-04-29 14:32:00 +03:00
```