diff --git a/README.md b/README.md index 7497710..32ef9fc 100644 --- a/README.md +++ b/README.md @@ -34,24 +34,24 @@ 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 + - 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. + - A standard script loops over your folders and runs each formatter sequentially. + - 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. + - When formatters are run in a script, they process all the files they encounter, regardless of whether or not + they have changed. + - `treefmt` tracks file changes, and only attempts to format files which have changed. -To reformat the whole source tree, just type `treefmt` in any folder. This is a fast and simple formatting solution. +> 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). +Otherwise, you can install the package from source code — either with [Go], or with the help of [nix]. -We describe the installation process in detail in the [docs](https://numtide.github.io/treefmt.go/). +We describe the installation process in detail in the [docs]. ## Usage @@ -90,7 +90,7 @@ 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 +For example, if you want to use [nixpkgs-fmt] on your Nix project and rustfmt on your Rust project, then `treefmt.toml` will look as follows: ```toml @@ -106,7 +106,7 @@ 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/). +To find and share existing formatter recipes, take a look at the [docs]. 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. @@ -117,7 +117,7 @@ formatters. 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# +- [clang-format] for C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# - gofmt for Golang - Prettier for JavaScript/HTML/CSS @@ -142,6 +142,29 @@ This project is still pretty new. Down the line we also want to add support for: 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. +## Moving from Rust To Go + +You may be familiar with [Version 1], which is written in [Rust]. So, why re-write it in [Go]? + +Ultimately, `treefmt` is spending most of it's time shelling out calls to the underlying formatters. This process is +just as fast/performant in [Go] as it is in [Rust]. + +The remaining tasks are processing some cli args and parsing a config file. Do we really need something as _heavy duty_ +as [Rust] for that? + +Despite all this, you can make good, sane arguments for continuing with [Version 1] in [Rust] instead of a re-write. +So here's a _bad argument_. + +[Brian] wanted to improve performance by moving away from a [Toml] cache file, introduce pipelines for applying multiple +formatters against the same file set, and add an extensible approach for how `treefmt` walks file systems. He knows [Go] +much better than [Rust]. + +[zimbatm] thought it was a good idea too. + +So here we are :shrug:. + +![Just Use Go](./docs/public/just-use-go.png) + ## Commercial support Looking for help or customization? @@ -153,3 +176,14 @@ Source projects: 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. + +[Brian]: https://github.com/brianmcgee +[zimbatm]: https://github.com/zimbatm +[Version 1]: https://github.com/numtide/treefmt +[Rust]: https://www.rust-lang.org/ +[Go]: https://go.dev/ +[Toml]: https://toml.io/en/ +[docs]: https://numtide.github.io/treefmt.go/ +[nix]: https://github.com/NixOS/nix +[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt +[clang-format]: https://clang.llvm.org/docs/ClangFormat.html diff --git a/docs/public/just-use-go.png b/docs/public/just-use-go.png new file mode 100644 index 0000000..bfb521e Binary files /dev/null and b/docs/public/just-use-go.png differ