docs: add README

Signed-off-by: Brian McGee <brian@bmcgee.ie>
2024-02-23 11:58:50 +00:00 · 2024-02-23 11:58:50 +00:00 · ac46faef61
commit ac46faef61
parent 5d341f929f
2 changed files with 326 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,132 @@
+<h1 align="center">
+  <br>
+  <img src="docs/assets/logo.svg" alt="logo" width="200">
+  <br>
+  treefmt — one CLI to format your repo
+  <br>
+  <br>
+</h1>
+
+[![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` applies all the needed formatters to your project with one command line.
+
+## Motivation
+
+Before making contributions to any project, it’s common to get your code formatted according to the project’s standards. This task seems trivial from the first sight — you can simply set up the required language formatter in your IDE. But contributing to multiple projects requires more effort: you need to change the code formatter configs each time you switch between projects, or call formatters manually.
+
+Formatting requires less effort if a universal formatter for multiple languages is in place, which is also project-specific.
+
+## About treefmt
+
+`treefmt` runs all your formatters with one command. It’s easy to configure and fast to execute.
+
+[![asciicast](https://asciinema.org/a/cwtaWUTdBa8qCKJVp40bTwxf0.svg)](https://asciinema.org/a/cwtaWUTdBa8qCKJVp40bTwxf0)
+
+Its main features are:
+
+- Providing a unified CLI and output: You don’t need to remember which formatters are required 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.
+- Caching the changed files: 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.
+
+Just type `treefmt` in any folder to reformat the whole code tree. All in all, you get a fast and simple formatting solution.
+
+## Installation
+
+You can install the tool by downloading the binary. Find the binaries for different architectures [here](https://github.com/numtide/treefmt/releases). Otherwise, you can install the package from the source code — either with [cargo](https://github.com/rust-lang/cargo), or with help of [nix](https://github.com/NixOS/nix). We describe the installation process in detail in the [docs](https://github.com/numtide/treefmt/wiki).
+
+## 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 your needs. You can generate it with:
+
+```
+$ treefmt --init
+```
+
+You can 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 special tool called [`treefmt-nix`](https://github.com/numtide/treefmt-nix) for using both `treefmt` and [`nix`](https://github.com/NixOS/nix).
+
+## Configuration
+
+Fomatters 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.<name>]
+command = "<formatter-command>"
+options = [“<formatter-option-1>”...]
+includes = ["<glob>"]
+```
+
+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:
+
+```
+[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://github.com/numtide/treefmt/wiki).
+
+If you are a Nix user, you might also be interested in [treefmt-nix](https://github.com/numtide/treefmt-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/blob/main/docs/formatters-spec.md). For instance, you can go for:
+
+- [clang-format](https://clang.llvm.org/docs/ClangFormat.html) for Java
+- gofmt for Golang
+- Prettier for JavaScript/HTML/CSS
+
+Find the full list of supported formatters [here](https://numtide.github.io/treefmt/formatters).
+
+## Upcoming features
+
+This project is still pretty new. Down the line we also want to add support for:
+
+- IDE integration
+- Pre-commit hooks
+- Effective support of multiple formatters
+
+## 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 [Contributing](./docs/contributing.md) guidelines for more information.
+
+## Commercial support
+
+Looking for help or customization?
+
+Get in touch with Numtide to get a quote. We make it easy for companies to
+work with Open Source projects: <https://numtide.com/contact>
+
+## 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.
--- a/docs/assets/logo.svg
+++ b/docs/assets/logo.svg
@ -0,0 +1,194 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+        xmlns:dc="http://purl.org/dc/elements/1.1/"
+        xmlns:cc="http://creativecommons.org/ns#"
+        xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+        xmlns:svg="http://www.w3.org/2000/svg"
+        xmlns="http://www.w3.org/2000/svg"
+        xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+        xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+        inkscape:export-ydpi="512"
+        inkscape:export-xdpi="512"
+        inkscape:export-filename="/home/basile/dev/treefmt.png"
+        sodipodi:docname="treefmt.svg"
+        inkscape:version="1.0 (4035a4fb49, 2020-05-01)"
+        id="svg16"
+        version="1.1"
+        viewBox="0 0 12.7 12.7"
+        height="48"
+        width="48">
+    <defs
+            id="defs10">
+        <inkscape:path-effect
+                hide_knots="false"
+                only_selected="false"
+                apply_with_radius="true"
+                apply_no_radius="true"
+                use_knot_distance="true"
+                flexible="false"
+                chamfer_steps="1"
+                radius="0.5"
+                mode="F"
+                method="auto"
+                unit="px"
+                satellites_param="F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1"
+                lpeversion="1"
+                is_visible="true"
+                id="path-effect1012"
+                effect="fillet_chamfer" />
+        <inkscape:path-effect
+                hide_knots="false"
+                only_selected="false"
+                apply_with_radius="true"
+                apply_no_radius="true"
+                use_knot_distance="true"
+                flexible="false"
+                chamfer_steps="1"
+                radius="0.5"
+                mode="F"
+                method="auto"
+                unit="px"
+                satellites_param="F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1"
+                lpeversion="1"
+                is_visible="true"
+                id="path-effect1010"
+                effect="fillet_chamfer" />
+        <inkscape:path-effect
+                hide_knots="false"
+                only_selected="false"
+                apply_with_radius="true"
+                apply_no_radius="true"
+                use_knot_distance="true"
+                flexible="false"
+                chamfer_steps="1"
+                radius="0.5"
+                mode="F"
+                method="auto"
+                unit="px"
+                satellites_param="F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1"
+                lpeversion="1"
+                is_visible="true"
+                id="path-effect989"
+                effect="fillet_chamfer" />
+    </defs>
+    <sodipodi:namedview
+            inkscape:window-maximized="1"
+            inkscape:window-y="340"
+            inkscape:window-x="1440"
+            inkscape:window-height="1373"
+            inkscape:window-width="2560"
+            units="px"
+            showgrid="false"
+            inkscape:document-rotation="0"
+            inkscape:current-layer="layer1"
+            inkscape:document-units="mm"
+            inkscape:cy="29.374509"
+            inkscape:cx="-10.431476"
+            inkscape:zoom="11.2"
+            inkscape:pageshadow="2"
+            inkscape:pageopacity="0.0"
+            borderopacity="1.0"
+            bordercolor="#666666"
+            pagecolor="#ffffff"
+            id="base">
+        <inkscape:grid
+                dotted="false"
+                id="grid902"
+                type="xygrid" />
+    </sodipodi:namedview>
+    <metadata
+            id="metadata13">
+        <rdf:RDF>
+            <cc:Work
+                    rdf:about="">
+                <dc:format>image/svg+xml</dc:format>
+                <dc:type
+                        rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+                <dc:title></dc:title>
+            </cc:Work>
+        </rdf:RDF>
+    </metadata>
+    <g
+            id="layer1"
+            inkscape:groupmode="layer"
+            inkscape:label="Layer 1">
+        <path
+                d="m 6.3370673,12.637056 c -0.5007028,0 -5.1699157,-2.6957712 -5.42026711,-3.1293926 C 0.66644877,9.074042 0.66644862,3.6824995 0.91680002,3.2488781 1.1671514,2.8152568 5.8363641,0.11948539 6.337067,0.11948538 c 0.5007028,-2e-8 5.169916,2.69577112 5.420267,3.12939252 0.250351,0.4336213 0.250352,5.8251638 0,6.2587852 -0.250351,0.4336214 -4.9195639,3.1293929 -5.4202667,3.1293929 z"
+                inkscape:randomized="0"
+                inkscape:rounded="0.08"
+                inkscape:flatsided="true"
+                sodipodi:arg2="2.0943951"
+                sodipodi:arg1="1.5707963"
+                sodipodi:r2="5.4202676"
+                sodipodi:r1="6.2587852"
+                sodipodi:cy="6.3782705"
+                sodipodi:cx="6.3370669"
+                sodipodi:sides="6"
+                id="path20"
+                style="fill:#729fcf;stroke-width:0.0142755"
+                sodipodi:type="star" />
+        <path
+                sodipodi:type="star"
+                style="fill:#888a85;stroke-width:0.0128537"
+                id="path20-3"
+                sodipodi:sides="6"
+                sodipodi:cx="6.3652418"
+                sodipodi:cy="6.3777179"
+                sodipodi:r1="5.6354737"
+                sodipodi:r2="4.8804641"
+                sodipodi:arg1="1.5707963"
+                sodipodi:arg2="2.0943951"
+                inkscape:flatsided="true"
+                inkscape:rounded="0.08"
+                inkscape:randomized="0"
+                d="m 6.3652422,12.013192 c -0.4508379,0 -4.6550446,-2.4273 -4.8804635,-2.817737 -0.225419,-0.3904371 -0.2254191,-5.2450367 -2e-7,-5.6354738 0.225419,-0.390437 4.4296255,-2.81773694 4.8804634,-2.81773696 0.4508379,-1e-8 4.6550441,2.42729966 4.8804631,2.81773676 0.225419,0.390437 0.225419,5.2450366 0,5.6354737 -0.225418,0.3904371 -4.4296249,2.8177373 -4.8804628,2.8177373 z" />
+        <path
+                sodipodi:type="rect"
+                d="m 4.6302084,3.8364582 5.0270831,0 A 0.13229167,0.13229167 45 0 1 9.7895832,3.9687499 V 4.4979165 A 0.13229167,0.13229167 135 0 1 9.6572915,4.6302082 l -5.0270831,0 A 0.13229167,0.13229167 45 0 1 4.4979167,4.4979165 V 3.9687499 A 0.13229167,0.13229167 135 0 1 4.6302084,3.8364582 Z"
+                inkscape:path-effect="#path-effect989"
+                y="3.8364582"
+                x="4.4979167"
+                height="0.79374999"
+                width="5.2916665"
+                id="rect898"
+                style="fill:#f57900;stroke-width:0.0121433" />
+        <circle
+                r="0.66145831"
+                style="fill:#73d216;stroke-width:0.0221209"
+                id="path860-3"
+                cx="2.778125"
+                cy="4.2333331" />
+        <circle
+                cy="6.4822917"
+                cx="4.6302085"
+                id="path860-3-5"
+                style="fill:#73d216;stroke-width:0.0221209"
+                r="0.66145831" />
+        <circle
+                r="0.66145831"
+                style="fill:#73d216;stroke-width:0.0221209"
+                id="path860-3-5-6"
+                cx="4.6302085"
+                cy="8.9958334" />
+        <path
+                sodipodi:type="rect"
+                d="M 6.4822916,6.0854168 H 9.6572915 A 0.13229167,0.13229167 45 0 1 9.7895832,6.2177085 V 6.7468751 A 0.13229167,0.13229167 135 0 1 9.6572915,6.8791668 H 6.4822916 A 0.13229167,0.13229167 45 0 1 6.3499999,6.7468751 V 6.2177085 A 0.13229167,0.13229167 135 0 1 6.4822916,6.0854168 Z"
+                inkscape:path-effect="#path-effect1010"
+                style="fill:#f57900;stroke-width:0.00979024"
+                id="rect898-2"
+                width="3.4395833"
+                height="0.79374999"
+                x="6.3499999"
+                y="6.0854168" />
+        <path
+                sodipodi:type="rect"
+                d="m 6.4822916,8.598959 3.1749999,0 A 0.13229167,0.13229167 45 0 1 9.7895832,8.7312506 V 9.2604173 A 0.13229167,0.13229167 135 0 1 9.6572915,9.392709 l -3.1749999,0 A 0.13229167,0.13229167 45 0 1 6.3499999,9.2604173 V 8.7312506 A 0.13229167,0.13229167 135 0 1 6.4822916,8.598959 Z"
+                inkscape:path-effect="#path-effect1012"
+                y="8.598959"
+                x="6.3499999"
+                height="0.79374999"
+                width="3.4395833"
+                id="rect898-2-9"
+                style="fill:#f57900;stroke-width:0.00979024" />
+    </g>
+</svg>