From f5c81e64ecd923d9b6f1281f2a33210f5aed44f3 Mon Sep 17 00:00:00 2001 From: Brian McGee Date: Fri, 3 May 2024 14:08:00 +0100 Subject: [PATCH] doc: initial port of README Signed-off-by: Brian McGee --- README.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7497710 --- /dev/null +++ b/README.md @@ -0,0 +1,155 @@ +

+
+ logo +
+ treefmt — one CLI to format your repo +
+
+

+ +[![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) + +**Status: beta** + +`treefmt` streamlines the process of applying formatters to your project, making it a breeze with just one command line. + +## Motivation + +It’s common to format code according to the project’s standards before making contributions to any project. This task +seems trivial at first sight — you can set up the required language formatter in your IDE. + +However, contributing to multiple projects requires more effort: you must change your formatter configurations each +time you switch between projects or call them manually. + +Formatting requires less effort if a universal formatter for multiple languages, which is also project-specific, is in +place. + +## About treefmt + +`treefmt` runs all your formatters with one command. It’s easy to configure and fast to execute. + +![Treefmt Init](./docs/public/init.gif) + +Its main features are: + +- **Providing a unified CLI and output** + - You don’t need to remember which formatters are necessary for each project. + Once you specify the formatters in the config file, you can trigger all of them with one command and get a + standardized output. +- **Running all the formatters in parallel** + - A standard script loops over your folders and runs each formatter + consequentially. In contrast, `treefmt` runs formatters in parallel. This way, the formatting job takes less time. +- **Tracking file changes** + - When formatters are run in a script, they process all the files they encounter, no matter + whether the code has changed. This unnecessary work can be eliminated if only the changed files are formatted. + `treefmt` caches the changed files and marks them for re-formatting. + +To reformat the whole source tree, just type `treefmt` in any folder. This is a fast and simple formatting solution. + +## Installation + +You can install `treefmt` by downloading the binary. Find the binaries for different architectures [here](https://github.com/numtide/treefmt.go/releases). +Otherwise, you can install the package from source code — either with [Go](https://go.dev/), or with the help of [nix](https://github.com/NixOS/nix). + +We describe the installation process in detail in the [docs](https://numtide.github.io/treefmt.go/). + +## Usage + +In order to use `treefmt` in your project, make sure the config file `treefmt.toml` is present in the root folder and +is edited to suit your needs. + +You can generate it with: + +``` +$ treefmt --init +``` + +You can then run `treefmt` in your project root folder like this: + +``` +$ treefmt +``` + +To explore the tool’s flags and options, type: + +```console +$ treefmt --help +``` + +Additionally, there's a wrapper called [`treefmt-nix`](https://github.com/numtide/treefmt.go-nix) for using `treefmt` with [`nix`](https://github.com/NixOS/nix). + +## Configuration + +Formatters are specified in the config file `treefmt.toml`, which is usually located in the project root folder. The +generic way to specify a formatter is like this: + +``` +[formatter.] +command = "" +options = [""...] +includes = [""] +``` + +For example, if you want to use [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt) on your Nix project and rustfmt on your Rust project, then +`treefmt.toml` will look as follows: + +```toml +[formatter.nix] +command = "nixpkgs-fmt" +includes = ["*.nix"] + +[formatter.rust] +command = "rustfmt" +options = ["--edition", "2018"] +includes = ["*.rs"] +``` + +Before specifying the formatter in the config, make sure it’s installed. + +To find and share existing formatter recipes, take a look at the [docs](https://numtide.github.io/treefmt.go/). + +If you are a Nix user, you might also be interested in [treefmt-nix](https://github.com/numtide/treefmt.go-nix) to use Nix to configure and bring in +formatters. + +## Compatibility + +`Treefmt` works with any formatter that adheres to the [following specification](https://github.com/numtide/treefmt.go/blob/main/docs/formatters-spec.md). + +For instance, you can go for: + +- [clang-format](https://clang.llvm.org/docs/ClangFormat.html) for C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# +- gofmt for Golang +- Prettier for JavaScript/HTML/CSS + +Find the full list of supported formatters [here](https://numtide.github.io/treefmt.go/formatters). + +## Upcoming features + +This project is still pretty new. Down the line we also want to add support for: + +- IDE integration +- Pre-commit hooks + +## Related projects + +- [EditorConfig](https://editorconfig.org/): unifies file indentations configuration on a per-project basis. +- [prettier](https://prettier.io/): an opinionated code formatter for a number of languages. +- [Super-Linter](https://github.com/github/super-linter): a project by GitHub to lint all of your code. +- [pre-commit](https://pre-commit.com/): a framework for managing and maintaining multi-language pre-commit hooks. + +## Contributing + +All contributions are welcome! We try to keep the project simple and focused. Please refer to the [Contributing](./docs/contributing.md) +guidelines for more information. + +## Commercial support + +Looking for help or customization? + +Get in touch with [Numtide](https://numtide.com/) to get a quote. We make it easy for companies to work with Open +Source projects: + +## License + +Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion will be licensed under the +[MIT license](LICENSE.md) without any additional terms or conditions.