mirror of
https://github.com/numtide/treefmt.git
synced 2024-09-11 17:07:44 +03:00
This was incorrectly ported from Rust to Go. When provided, `treefmt` will take the contents of stdin and place them into the file provided with the `--stdin` flag, then format it according to the configured formatters. If the file doesn't exist it is created. If it exists, it is first truncated and then populated with stdin. Signed-off-by: Brian McGee <brian@bmcgee.ie>
145 lines
5.1 KiB
Markdown
145 lines
5.1 KiB
Markdown
---
|
|
outline: deep
|
|
---
|
|
|
|
# Usage
|
|
|
|
`treefmt` has the following specification:
|
|
|
|
```
|
|
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=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.
|
|
```
|
|
|
|
## Arguments
|
|
|
|
### `[<paths> ...]`
|
|
|
|
Paths to format. Defaults to formatting the whole tree
|
|
|
|
## Flags
|
|
|
|
### `-h, --help`
|
|
|
|
Prints available flags and options
|
|
|
|
### `--allow-missing-formatter`
|
|
|
|
Do not exit with an error if some of the configured formatters are missing.
|
|
|
|
### `-C, --working-directory="."`
|
|
|
|
Run as if `treefmt` was started in the specified working directory instead of the current working directory
|
|
|
|
### `--no-cache`
|
|
|
|
Tells `treefmt` to ignore the evaluation cache entirely.
|
|
|
|
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.
|
|
|
|
The `--no-cache` flag eliminates unnecessary work in CI.
|
|
|
|
### `--config-file <config-file>`
|
|
|
|
Run with the specified config file.
|
|
|
|
### `--fail-on-change`
|
|
|
|
Exit with error if any changes were made.
|
|
|
|
This is useful for CI if you want to detect if someone forgot to format their code.
|
|
|
|
### `-f, --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|git|filesystem>`
|
|
|
|
The method used to traverse the files within `--tree-root`. Currently supports `auto`, `git` or `filesystem`.
|
|
|
|
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.
|
|
|
|
### `-v, --verbose`
|
|
|
|
Set the verbosity of logs e.g. `-vv`. Can also be set with an integer value in an env variable `$LOG_LEVEL`.
|
|
|
|
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.
|
|
|
|
### `--init`
|
|
|
|
Create a new `treefmt.toml`.
|
|
|
|
### `-u --on-unmatched`
|
|
|
|
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]
|
|
|
|
### `--stdin=STRING`
|
|
|
|
Format stdin, placing the output into the provided path. Formatters are matched based on the path's file extension.
|
|
|
|
### `--cpu-profile`
|
|
|
|
The file into which a cpu profile will be written.
|
|
|
|
### `-V, --version`
|
|
|
|
Print version.
|
|
|
|
## CI integration
|
|
|
|
Typically, you would use `treefmt` in CI with the `--fail-on-change` and `--no-cache flags`.
|
|
|
|
You can configure a `treefmt` job in a GitHub pipeline for Ubuntu with `nix-shell` like this:
|
|
|
|
```yaml
|
|
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 --fail-on-change --no-cache"
|
|
```
|