Skip to content

Commit

Permalink
docs: add guide on handling unmatched formatters
Browse files Browse the repository at this point in the history
Fixes #496
  • Loading branch information
zimbatm committed Dec 17, 2024
1 parent 1ab9c08 commit 60d91b9
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 1 deletion.
3 changes: 2 additions & 1 deletion docs/content/.pages
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
nav:
- getting-started
- guides
- contributing
- reference
- reference
47 changes: 47 additions & 0 deletions docs/content/guides/unmatched-formatters.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Handling Unmatched Files

By default, treefmt lists all files that aren't matched by any formatter:

```console
$ treefmt
WARN no formatter for path: .gitignore
WARN no formatter for path: LICENSE
WARN no formatter for path: README.md
WARN no formatter for path: go.mod
WARN no formatter for path: go.sum
WARN no formatter for path: build/build.go
# ...
```

This helps you decide whether to add formatters for specific files or ignore them entirely.

## Customizing Notifications

### Reducing Log Verbosity
If you find the unmatched file warnings too noisy, you can lower the logging level in your config:

`treefmt.toml`:
```toml
on-unmatched = "debug"
```

To later find out what files are unmatched, you can override this setting via the command line:
```console
$ treefmt --on-unmatched warn
```

### Enforcing Strict Matching
Another stricter policy approach is to fail the run if any unmatched files are found.
This can be paired with an `excludes` list to ignore specific files:

`treefmt.toml`:
```toml
# Fail if any unmatched files are found
on-unmatched = "fatal"

# List files to explicitly ignore
excludes = [
"LICENCE",
"go.sum",
]
```

0 comments on commit 60d91b9

Please sign in to comment.