2021-02-10 11:51:58 +03:00
< h1 align = "center" >
< br >
2021-03-02 14:29:31 +03:00
< img src = "docs/assets/logo.svg" alt = "logo" width = "200" >
2021-02-10 11:51:58 +03:00
< br >
2021-02-15 23:55:18 +03:00
treefmt - one CLI to format the code tree
2021-02-10 11:51:58 +03:00
< br >
< br >
< / h1 >
2021-01-18 18:03:58 +03:00
2021-02-17 21:17:02 +03:00
[![Support room on Matrix ](https://img.shields.io/matrix/treefmt:numtide.com.svg?label=%23treefmt%3Anumtide.com&logo=matrix&server_fqdn=matrix.numtide.com )](https://matrix.to/#/#treefmt:numtide.com)
2021-07-31 14:19:22 +03:00
**Status: beta**
2021-01-18 18:03:58 +03:00
2021-05-07 22:13:56 +03:00
When working on large code trees, it's common to have multiple code
formatters run against it. And have one script that loops over all of them.
`treefmt` makes that nicer.
2021-01-18 18:03:58 +03:00
2021-05-07 22:13:56 +03:00
- A unified CLI and output
- Run all the formatters in parallel.
- Cache which files have changed for super fast re-formatting.
Just type `treefmt` in any folder and it reformats the whole code tree.
2021-01-18 18:03:58 +03:00
## Design decisions
2021-02-27 15:32:17 +03:00
We assume that the project code is checked into source control. Therefore, the
2021-01-18 18:03:58 +03:00
default should be to write formatter changes back in place. Options like
2021-02-27 15:32:17 +03:00
`--dry-run` are not needed; the source control is relied upon to revert or
2021-02-18 13:35:03 +03:00
check for code changes.
2021-01-18 18:03:58 +03:00
2021-02-15 23:22:03 +03:00
`treefmt` is responsible for traversing the file-system and mapping files to
2021-01-18 18:03:58 +03:00
specific code formatters.
2021-02-18 14:41:47 +03:00
Only _one_ formatter per file. `treefmt` enforces that only one tool is
2021-02-27 15:32:17 +03:00
executed per file. Guaranteeing two tools to produce idempotent outputs is
quite tricky.
2021-01-18 18:03:58 +03:00
## Usage
2021-05-08 21:31:01 +03:00
`$ treefmt --help`
2022-12-01 20:30:10 +03:00
2021-01-18 18:03:58 +03:00
```
2022-12-01 20:22:02 +03:00
treefmt 0.5.0
2021-02-25 23:31:37 +03:00
✨ format all your language!
2021-02-18 14:03:26 +03:00
USAGE:
2022-12-01 20:22:02 +03:00
treefmt [FLAGS] [OPTIONS] [--] [paths]...
2021-02-18 14:03:26 +03:00
FLAGS:
2022-12-01 20:15:44 +03:00
--allow-missing-formatter Do not exit with error if a configured formatter is missing
2022-12-01 20:22:02 +03:00
--clear-cache Reset the evaluation cache. Use in case the cache is not precise enough
2022-12-01 20:15:44 +03:00
--fail-on-change Exit with error if any changes were made. Useful for CI
-h, --help Prints help information
--init Create a new treefmt.toml
2022-12-01 20:22:02 +03:00
--no-cache Ignore the evaluation cache entirely. Useful for CI
2022-12-01 20:15:44 +03:00
-q, --quiet No output printed to stderr
--stdin Format the content passed in stdin
-V, --version Prints version information
-v, --verbose Log verbosity is based off the number of v used
2021-02-18 14:03:26 +03:00
OPTIONS:
2022-12-01 20:22:02 +03:00
--config-file < config-file > Run with the specified config file, which is not required to be in the tree to
be formatted
-f, --formatters < formatters > ... Select formatters name to apply. Defaults to all formatters
--tree-root < tree-root > Set the path to the tree root directory. Defaults to the folder holding the
treefmt.toml file [env: PRJ_ROOT=]
-C < work-dir > Run as if treefmt was started in < work-dir > instead of the current working
directory [default: .]
2021-02-18 14:03:26 +03:00
2021-02-25 23:31:37 +03:00
ARGS:
2021-02-27 18:07:09 +03:00
< paths > ... Paths to format. Defaults to formatting the whole tree
2021-01-18 18:03:58 +03:00
```
## Configuration format
2021-03-02 14:29:31 +03:00
In order to use `treefmt` in the project, `treefmt.toml` should exists in the root folder. For example, we want to use [nixpkgs-fmt ](https://github.com/nix-community/nixpkgs-fmt ) on our Nix project and rustfmt on our Rust project, then the `treefmt.toml` will be written as follows:
2021-01-18 18:03:58 +03:00
2021-03-02 14:29:31 +03:00
```
2021-03-05 20:55:51 +03:00
[formatter.nix]
2021-03-02 14:29:31 +03:00
command = "nixpkgs-fmt"
2021-05-29 07:40:02 +03:00
includes = ["*.nix"]
2021-03-02 14:29:31 +03:00
[formatter.rust]
command = "rustfmt"
options = ["--edition", "2018"]
includes = ["*.rs"]
```
2021-02-18 13:39:24 +03:00
2022-03-18 19:52:33 +03:00
See the [wiki ](https://github.com/numtide/treefmt/wiki ) for more examples.
2021-01-18 18:03:58 +03:00
## Use cases
### CLI usage
2021-02-15 23:22:03 +03:00
As a developer, I want to run `treefmt` in any folder and it would
2021-01-18 18:03:58 +03:00
automatically format all of the code, configured for the project. I don't want
to remember what tool to use, or their magic incantation.
### Editor integration
Editors often want to be able to format a file, before it gets written to disk.
Ideally, the editor would pipe the code in, pass the filename, and get the
2021-02-18 14:41:47 +03:00
formatted code out. Eg: `cat ./my_file.sh | treefmt --stdin my_file.sh > formatted_file.sh`
2021-01-18 18:03:58 +03:00
### CI integration
2021-02-27 19:15:01 +03:00
The `--fail-on-change` flag can be used to exit with error if any files were
re-formatted.
2021-01-18 18:03:58 +03:00
2021-02-27 19:15:01 +03:00
Eg:
2021-01-18 18:03:58 +03:00
```sh
#!/usr/bin/env bash
set -euo pipefail
2021-02-27 19:15:01 +03:00
# Format all of the code and exit with error if there are any changes
treefmt --fail-on-change
2021-01-18 18:03:58 +03:00
```
## Interfaces
2021-02-18 13:35:03 +03:00
In order to keep the design of treefmt simple, we ask code formatters to
adhere to the following specification.
2021-01-18 18:03:58 +03:00
2021-03-05 12:38:52 +03:00
[treefmt formatter spec ](./docs/formatters-spec.md )
2021-01-18 18:03:58 +03:00
2021-02-18 13:35:03 +03:00
If they don't, the best is to create a wrapper script that transforms the
usage to match that spec.
2021-01-18 18:03:58 +03:00
## Related projects
2021-02-18 14:41:47 +03:00
- [EditorConfig ](https://editorconfig.org/ ): unifies file indentations
2021-01-18 18:03:58 +03:00
configuration on a per-project basis.
2021-02-18 14:41:47 +03:00
- [prettier ](https://prettier.io/ ): and opinionated code formatter for a
number of languages.
2021-03-17 16:59:29 +03:00
- [Super-Linter ](https://github.com/github/super-linter ): a project by GitHub
to lint all of the code.
2021-05-07 21:20:05 +03:00
- [pre-commit ](https://pre-commit.com/ ): a framework for managing and
maintaining multi-language pre-commit hooks.
2021-01-18 18:03:58 +03:00
## Contributing
All contributions are welcome! We try to keep the project simple and focused
2021-05-07 21:20:05 +03:00
so not everything will be accepted. Please refer to
[Contributing ](./docs/contributing.md ) guidelines for more information.
2021-02-17 21:17:02 +03:00
2021-01-18 18:03:58 +03:00
## License
2021-03-02 14:29:31 +03:00
Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed under the [MIT license ](LICENSE.md ), without any additional terms or conditions.