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:
|
|
|
|
-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="./treefmt.toml" The config file to use.
|
|
|
|
--fail-on-change Exit with error if any changes were made. Useful for CI.
|
|
|
|
--formatters=FORMATTERS,... Specify formatters to apply. Defaults to all formatters.
|
|
|
|
--tree-root="." The root directory from which treefmt will start walking the filesystem.
|
|
|
|
--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.
|
|
|
|
--stdin Format the context passed in via stdin.
|
|
|
|
--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-10 12:17:49 +03:00
|
|
|
### `--stdin`
|
|
|
|
|
|
|
|
Format the content passed in via stdin.
|
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
|
|
|
```
|