Repository files navigation

treefmt

The formatter multiplexer

Anumtide project.

treefmt streamlines the process of applying formatters to your project, making it a breeze with just one command line.

Modern code repositories are rarely written in a single language. They often contain a mix of languages, each with its own formatting requirements.

While working for our customers, we noticed that projects each tended to re-implement the same formatter multiplexing logic. A script that invokes all the formatters.

What if that script was a single command?

What if that single command would handle all the formatters in parallel? And only format files that have changed since the previous run?

That's what treefmt is about.

treefmt runs all your formatters with one command. It’s easy to configure and fast to execute.

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 astandardized output.
• Running all the formatters in parallel
  • 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, regardless of whether or notthey have changed.
  • treefmt tracks file changes, and only attempts to format files which have changed.

To reformat the whole source tree, just typetreefmt in any folder. This is a fast and simple formatting solution.

You can installtreefmt by downloading the binary. Find the binaries for different architectureshere.Otherwise, you can install the package from source code — either withGo, or with the help ofnix.

We describe the installation process in detail in thedocs.

In order to usetreefmt in your project, make sure the config filetreefmt.toml is present in the root folder andis edited to suit your needs.

You can generate it with:

$ treefmt --init

You can then runtreefmt in your project root folder like this:

$ treefmt

To explore the tool’s flags and options, type:

$treefmt --help

Additionally, there's a wrapper calledtreefmt-nix for usingtreefmt withnix.

Formatters are specified in the config filetreefmt.toml, which is usually located in the project root folder. Thegeneric way to specify a formatter is like this:

[formatter.<name>]command = "<formatter-command>"options = ["<formatter-option-1>"...]includes = ["<glob>"]

For example, if you want to usenixpkgs-fmt on your Nix project and rustfmt on your Rust project, thentreefmt.toml will look as follows:

[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 thedocs.

If you are a Nix user, you might also be interested intreefmt-nix to use Nix to configure and bring informatters.

treefmt works with any formatter that adheres to thefollowing specification.

For instance, you can go for:

• clang-format for C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C#
• gofmt for Golang
• Prettier for JavaScript/HTML/CSS

Find the full list of supported formattershere.

treefmt currently has support for vscode via an extension:

• treefmt-vscode |GitHub repo

This project is still pretty new. Down the line we also want to add support for:

• More IDE integration
• Pre-commit hooks

• EditorConfig: unifies file indentations configuration on a per-project basis.
• prettier: an opinionated code formatter for a number of languages.
• Super-Linter: a project by GitHub to lint all of your code.
• pre-commit: a framework for managing and maintaining multi-language pre-commit hooks.

All contributions are welcome! We try to keep the project simple and focused. Please refer to theContributingguidelines for more information.

Looking for help or customization?

Get in touch withNumtide to get a quote. We make it easy for companies to work with OpenSource projects:https://numtide.com/contact

Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion will be licensed under theMIT license without any additional terms or conditions.