diff --git a/formatters-spec/index.html b/formatters-spec/index.html
index 85d4e6a..ffddd52 100644
--- a/formatters-spec/index.html
+++ b/formatters-spec/index.html
@@ -535,17 +535,44 @@
@@ -634,17 +661,44 @@
@@ -668,7 +722,12 @@
In order to keep the design of treefmt simple, we support only formatters which adhere to a certain standard. This document outlines this standard. If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification.
-Command-line interface
+In this design, we rely on treefmt to do the tree traversal, and only invoke
+the code formatter on the selected files.
+Rules
+In order for the formatter to comply to this spec, it MUST follow the
+following rules:
+1. Files passed as arguments
In order to be integrated to treefmt's workflow, the formatter's CLI must adhere to the following specification:
<command> [options] [...<files>]
Example:
$ rustfmt --edition 2018 src/main.rs src/lib.rs
Whenever a formatter is invoked with a list of files, it should processes only the specified files. Files that are not passed should never be formatted.
-If, and only if, a file has changed, the formatter will write the new content in place of the original one.
-Other requirements
-You must ensure that the formatter you're planning to use:
-
-- Preserves code validity: This is a strong contract; the syntax and semantics must never be broken by the formatter.
-- Is idempotent: if it is run twice on a file, the file should not change on the second invocation.
-
-treefmt guarantees that the formatter won't traverse the file system if a list of files is passed to it.
+It SHOULD processes only the specified files. Files that are not passed SHOULD never be formatted.
+2. Write to changed files
+Whenever there is a change to the code formatting, the code formatter MUST
+write to the changes back to the original location.
+If there is no changes to the original file, the formatter MUST NOT write to
+the original location.
+3. Idempotent
+The code formatter SHOULD be indempotent. Meaning that it produces stable
+outputs.
+4. Reliable
+We expect the formatter to be reliable and not break the semantic of the
+formatted files.
diff --git a/search/search_index.json b/search/search_index.json
index 442e26e..52a299b 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"About the project treefmt is a formatting tool that saves you time: it provides developers with a universal way to trigger all formatters needed for the project in one place. Background Typically, each project has its own code standards enforced by the project's owner. Any code contributions must match that given standard, i.e. be formatted in a specific manner. At first glance, the task of code formatting may seem trivial: the formatter can be automatically triggered when you save a file in your IDE. Indeed, formatting doesn't take much effort if you're working on a single project long term: setting up the formatters in your IDE won't take much of your time, and then you're ready to go. Contrary to that, if you're working on multiple projects at the same time, you may have to update your formatter configs in the IDE each time you switch between the projects. This is because formatter settings aren't project-specific --- they are set up globally for all projects. Alternatively, you can trigger formatters manually, one-by-one or in a script. Actually, for bigger projects, it's common to have a script that runs over your project's directories and calls formatters consequently. But it takes time to iterate through all the files. All the solutions take up a significant amount of time which a developer could spend doing the actual work. They also require you to remember which formatters and options are used by each project you are working on. treefmt solves these issues. Why treefmt? treefmt 's configuration is project-specific, so you don't need to re-configure formatters each time you switch between projects, like you have to when working with formatters in the IDE. Contrary to calling formatters from the command line, there's no need to remember all the specific formatters required for each project. Once you set up the config, you can run the tool in any of your project's folders without any additional flags or options. Typically, formatters have different ways to say there was a specific error. With treefmt , you get a standardized output which is easier to understand than the variegated outputs of different formatters, so it takes less time to grasp what's wrong. In addition, treefmt works faster than the custom script solution because the changed files are cached and the formatters run only against them. Moreover, formatters are run in parallel, which makes the tool even faster. The difference may not be significant for smaller projects, but it gets quite visible as the project grows. For instance, take the caching optimization. It takes 9 seconds to traverse a project of 1507 files and no changes without caching: traversed 1507 files matched 828 files to formatters left with 828 files after cache of whom 0 files were re-formatted all of this in 9s ...while it takes 124 milliseconds to traverse the same project with caching: traversed 1507 files matched 828 files to formatters left with 0 files after cache of whom 0 files were re-formatted all of this in 124ms The tool can be invoked manually or integrated into your CI. There's currently no integration with IDEs, but the feature is coming soon. What we still need help with IDE integration: Most of developers are used to formatting a file upon save in the IDE. So far, you can't use treefmt for this purpose, but we're working on it \ud83d\ude00 Pre-commit hook: It's good to have your code checked for adherence to the project's standards before commit. treefmt pre-commit hook won't let you commit if you have formatting issues. Support of multiple formatters for one language: In the current version, we advise you to avoid using multiple formatters for one and the same file type. This is because formatters are run in parallel and therefore may encounter issues while processing files. We are going to fix this issue soon, since there are cases when you may need more than one formatter per language. As a next step, learn how to install and use treefmt .","title":"Home"},{"location":"#about-the-project","text":"treefmt is a formatting tool that saves you time: it provides developers with a universal way to trigger all formatters needed for the project in one place.","title":"About the project"},{"location":"#background","text":"Typically, each project has its own code standards enforced by the project's owner. Any code contributions must match that given standard, i.e. be formatted in a specific manner. At first glance, the task of code formatting may seem trivial: the formatter can be automatically triggered when you save a file in your IDE. Indeed, formatting doesn't take much effort if you're working on a single project long term: setting up the formatters in your IDE won't take much of your time, and then you're ready to go. Contrary to that, if you're working on multiple projects at the same time, you may have to update your formatter configs in the IDE each time you switch between the projects. This is because formatter settings aren't project-specific --- they are set up globally for all projects. Alternatively, you can trigger formatters manually, one-by-one or in a script. Actually, for bigger projects, it's common to have a script that runs over your project's directories and calls formatters consequently. But it takes time to iterate through all the files. All the solutions take up a significant amount of time which a developer could spend doing the actual work. They also require you to remember which formatters and options are used by each project you are working on. treefmt solves these issues.","title":"Background"},{"location":"#why-treefmt","text":"treefmt 's configuration is project-specific, so you don't need to re-configure formatters each time you switch between projects, like you have to when working with formatters in the IDE. Contrary to calling formatters from the command line, there's no need to remember all the specific formatters required for each project. Once you set up the config, you can run the tool in any of your project's folders without any additional flags or options. Typically, formatters have different ways to say there was a specific error. With treefmt , you get a standardized output which is easier to understand than the variegated outputs of different formatters, so it takes less time to grasp what's wrong. In addition, treefmt works faster than the custom script solution because the changed files are cached and the formatters run only against them. Moreover, formatters are run in parallel, which makes the tool even faster. The difference may not be significant for smaller projects, but it gets quite visible as the project grows. For instance, take the caching optimization. It takes 9 seconds to traverse a project of 1507 files and no changes without caching: traversed 1507 files matched 828 files to formatters left with 828 files after cache of whom 0 files were re-formatted all of this in 9s ...while it takes 124 milliseconds to traverse the same project with caching: traversed 1507 files matched 828 files to formatters left with 0 files after cache of whom 0 files were re-formatted all of this in 124ms The tool can be invoked manually or integrated into your CI. There's currently no integration with IDEs, but the feature is coming soon.","title":"Why treefmt?"},{"location":"#what-we-still-need-help-with","text":"IDE integration: Most of developers are used to formatting a file upon save in the IDE. So far, you can't use treefmt for this purpose, but we're working on it \ud83d\ude00 Pre-commit hook: It's good to have your code checked for adherence to the project's standards before commit. treefmt pre-commit hook won't let you commit if you have formatting issues. Support of multiple formatters for one language: In the current version, we advise you to avoid using multiple formatters for one and the same file type. This is because formatters are run in parallel and therefore may encounter issues while processing files. We are going to fix this issue soon, since there are cases when you may need more than one formatter per language. As a next step, learn how to install and use treefmt .","title":"What we still need help with"},{"location":"contributing/","text":"Contribution guidelines This file contains instructions that will help you make a contribution. Licensing The treefmt binaries and this user guide are licensed under the MIT license . Before you contribute Here you can take a look at the existing issues . Feel free to contribute, but make sure you have a GitHub account first :) . If you're new to open source, please read GitHub's guide on How to Contribute to Open Source . It's a quick read, and it's a great way to introduce yourself to how things work behind the scenes in open-source projects. Before sending a pull request, make sure that you've read all the guidelines. If you don't understand something, please state your question clearly in an issue or ask the community on the treefmt matrix server . Creating an issue If you need to create an issue, make sure to clearly describe it, including: The steps to reproduce it if it's a bug The version of treefmt used The database driver and version The database version The cache database is stored in a toml file the ~/.cache/treefmt directory. Making changes If you want to introduce changes to the project, please follow these steps: Fork the repository on GitHub Create a branch on your fork. Don't commit directly to main Add the necessary tests for your changes Run treefmt in the source directory before you commit your changes Push your changes to the branch in your repository fork Submit a pull request to the original repository Make sure you based your commits on logical and atomic units! Examples of git history Git history that we want to have: Git history that we are trying to avoid: Git history that we want to have * e3ed88b (HEAD -> contribution-guide, upstream/main, origin/main, origin/HEAD, main) Merge pull request #470 from zimbatm/fix_lru_cache |\\ | * 1ab7d9f Use rayon for multithreading command |/ * e9c5bb4 Merge pull request #468 from zimbatm/multithread |\\ | * de2d6cf Add lint property for Formatter struct | * cd2ed17 Fix impl on Formatter get_command() function |/ * 028c344 Merge pull request #465 from rayon/0.15.0-release |\\ | * 7b619d6 0.15.0 release |/ * acdf7df Merge pull request #463 from zimbatm/support-multi-part-namespaces Git history that we are trying to avoid: * 4c8aca8 Merge pull request #120 from zimbatm/add-rayon |\\ | * fc2b449 use rayon for engine now | * 2304683 add rayon config | * 5285bd3 bump base image to F30 * | 4d0fbe2 Merge pull request #114 from rizary/create_method_create_release |\\ \\ | * | 36a9396 test changed | * | 22f681d method create release for github created * | | 2ef4ea1 Merge pull request #119 from rizary/config.rs |\\ \\ \\ | |/ / |/| | | * | 5f1b8f0 unused functions removed * | | a93c361 Merge pull request #117 from zimbatm/add-getreleases-to-abstract |\\ \\ \\ | |/ / |/| | | * | 0a97236 add get_releses for Cargo | * | 55e4c57 add get_releases/get_release into engine.rs |/ / * | badeddd Merge pull request #101 from zimbatm/extreme-cachin Additionally, it's always good to work on improving documentation and adding examples. Thank you for considering contributing to treefmt .","title":"Contributing"},{"location":"contributing/#contribution-guidelines","text":"This file contains instructions that will help you make a contribution.","title":"Contribution guidelines"},{"location":"contributing/#licensing","text":"The treefmt binaries and this user guide are licensed under the MIT license .","title":"Licensing"},{"location":"contributing/#before-you-contribute","text":"Here you can take a look at the existing issues . Feel free to contribute, but make sure you have a GitHub account first :) . If you're new to open source, please read GitHub's guide on How to Contribute to Open Source . It's a quick read, and it's a great way to introduce yourself to how things work behind the scenes in open-source projects. Before sending a pull request, make sure that you've read all the guidelines. If you don't understand something, please state your question clearly in an issue or ask the community on the treefmt matrix server .","title":"Before you contribute"},{"location":"contributing/#creating-an-issue","text":"If you need to create an issue, make sure to clearly describe it, including: The steps to reproduce it if it's a bug The version of treefmt used The database driver and version The database version The cache database is stored in a toml file the ~/.cache/treefmt directory.","title":"Creating an issue"},{"location":"contributing/#making-changes","text":"If you want to introduce changes to the project, please follow these steps: Fork the repository on GitHub Create a branch on your fork. Don't commit directly to main Add the necessary tests for your changes Run treefmt in the source directory before you commit your changes Push your changes to the branch in your repository fork Submit a pull request to the original repository Make sure you based your commits on logical and atomic units!","title":"Making changes"},{"location":"contributing/#examples-of-git-history","text":"Git history that we want to have: Git history that we are trying to avoid: Git history that we want to have * e3ed88b (HEAD -> contribution-guide, upstream/main, origin/main, origin/HEAD, main) Merge pull request #470 from zimbatm/fix_lru_cache |\\ | * 1ab7d9f Use rayon for multithreading command |/ * e9c5bb4 Merge pull request #468 from zimbatm/multithread |\\ | * de2d6cf Add lint property for Formatter struct | * cd2ed17 Fix impl on Formatter get_command() function |/ * 028c344 Merge pull request #465 from rayon/0.15.0-release |\\ | * 7b619d6 0.15.0 release |/ * acdf7df Merge pull request #463 from zimbatm/support-multi-part-namespaces Git history that we are trying to avoid: * 4c8aca8 Merge pull request #120 from zimbatm/add-rayon |\\ | * fc2b449 use rayon for engine now | * 2304683 add rayon config | * 5285bd3 bump base image to F30 * | 4d0fbe2 Merge pull request #114 from rizary/create_method_create_release |\\ \\ | * | 36a9396 test changed | * | 22f681d method create release for github created * | | 2ef4ea1 Merge pull request #119 from rizary/config.rs |\\ \\ \\ | |/ / |/| | | * | 5f1b8f0 unused functions removed * | | a93c361 Merge pull request #117 from zimbatm/add-getreleases-to-abstract |\\ \\ \\ | |/ / |/| | | * | 0a97236 add get_releses for Cargo | * | 55e4c57 add get_releases/get_release into engine.rs |/ / * | badeddd Merge pull request #101 from zimbatm/extreme-cachin Additionally, it's always good to work on improving documentation and adding examples. Thank you for considering contributing to treefmt .","title":"Examples of git history"},{"location":"faq/","text":"FAQ How does treefmt function? Treefmt traverses all your project's folders, maps files to specific code formatters, and formats the code accordingly. Other tools also traverse the filesystem, but not necessarily starting from the root of the project. Contrary to other formatters, treefmt doesn't preview the changes before writing them to a file. If you want to view the changes, you can always check the diff in your version control (we assume that your project is checked into a version control system). You can also rely on version control if errors were introduced into your code as a result of disruptions in the formatter's work. How is the cache organized? At this moment, the cache is represented by a flat TOML file where file paths are mapped to mtimes . The file is located in: ~/.cache/treefmt/.toml However, we are planning to move the hash file to the destination project's root directory. At the end of each tool run, the cache file gets overwritten with the last formatting time entries. In this way, we can can compare the last change time of the file to the last formatting time, and figure out which files need re-formatting.","title":"FAQ"},{"location":"faq/#faq","text":"","title":"FAQ"},{"location":"faq/#how-does-treefmt-function","text":"Treefmt traverses all your project's folders, maps files to specific code formatters, and formats the code accordingly. Other tools also traverse the filesystem, but not necessarily starting from the root of the project. Contrary to other formatters, treefmt doesn't preview the changes before writing them to a file. If you want to view the changes, you can always check the diff in your version control (we assume that your project is checked into a version control system). You can also rely on version control if errors were introduced into your code as a result of disruptions in the formatter's work.","title":"How does treefmt function?"},{"location":"faq/#how-is-the-cache-organized","text":"At this moment, the cache is represented by a flat TOML file where file paths are mapped to mtimes . The file is located in: ~/.cache/treefmt/.toml However, we are planning to move the hash file to the destination project's root directory. At the end of each tool run, the cache file gets overwritten with the last formatting time entries. In this way, we can can compare the last change time of the file to the last formatting time, and figure out which files need re-formatting.","title":"How is the cache organized?"},{"location":"formatters-spec/","text":"Formatter specification In order to keep the design of treefmt simple, we support only formatters which adhere to a certain standard. This document outlines this standard. If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification. Command-line interface In order to be integrated to treefmt 's workflow, the formatter's CLI must adhere to the following specification: [options] [...] Where: is the name of the formatting tool. [options] is any number of flags and options that the formatter accepts. [...] is one or more files given to the formatter for processing. Example: $ rustfmt --edition 2018 src/main.rs src/lib.rs Whenever a formatter is invoked with a list of files, it should processes only the specified files. Files that are not passed should never be formatted. If, and only if, a file has changed, the formatter will write the new content in place of the original one. Other requirements You must ensure that the formatter you're planning to use: Preserves code validity: This is a strong contract; the syntax and semantics must never be broken by the formatter. Is idempotent: if it is run twice on a file, the file should not change on the second invocation. treefmt guarantees that the formatter won't traverse the file system if a list of files is passed to it.","title":"Formatter Specification"},{"location":"formatters-spec/#formatter-specification","text":"In order to keep the design of treefmt simple, we support only formatters which adhere to a certain standard. This document outlines this standard. If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification.","title":"Formatter specification"},{"location":"formatters-spec/#command-line-interface","text":"In order to be integrated to treefmt 's workflow, the formatter's CLI must adhere to the following specification: [options] [...] Where: is the name of the formatting tool. [options] is any number of flags and options that the formatter accepts. [...] is one or more files given to the formatter for processing. Example: $ rustfmt --edition 2018 src/main.rs src/lib.rs Whenever a formatter is invoked with a list of files, it should processes only the specified files. Files that are not passed should never be formatted. If, and only if, a file has changed, the formatter will write the new content in place of the original one.","title":"Command-line interface"},{"location":"formatters-spec/#other-requirements","text":"You must ensure that the formatter you're planning to use: Preserves code validity: This is a strong contract; the syntax and semantics must never be broken by the formatter. Is idempotent: if it is run twice on a file, the file should not change on the second invocation. treefmt guarantees that the formatter won't traverse the file system if a list of files is passed to it.","title":"Other requirements"},{"location":"formatters/","text":"Known formatters Here is a list of all the formatters we tested. Feel free to send a PR to add other ones! Contents Single-language formatters: Cabal cabal-fmt Elm elm-format Golang gofmt gofumpt Haskell hlint ormolu stylish-haskell Lua StyLua Nix alejandra nixpkgs-fmt OCaml ocamlformat PureScript purs-tidy Python black Ruby rufo Rust rustfmt Scala scalafmt Shell shellcheck shfmt Terraform terraform fmt Multilanguage formatters: clang-format Prettier Cabal cabal-fmt command = \"cabal-fmt\" options = [\"--inplace\"] includes = [\"*.cabal\"] Elm elm-format command = \"elm-format\" options = [\"--yes\"] includes = [\"*.elm\"] Golang gofmt command = \"gofmt\" options = [\"-w\"] includes = [\"*.go\"] gofumpt command = \"gofumpt\" includes = [\"*.go\"] Haskell hlint command = \"hlint\" includes = [ \"*.hs\" ] Ormolu Make sure to use ormolu 0.1.4.0+ as older versions don't adhere to the spec. command = \"ormolu\" options = [ \"--ghc-opt\", \"-XBangPatterns\", \"--ghc-opt\", \"-XPatternSynonyms\", \"--ghc-opt\", \"-XTypeApplications\", \"--mode\", \"inplace\", \"--check-idempotence\", ] includes = [\"*.hs\"] stylish-haskell command = \"stylish-haskell\" options = [ \"--inplace\" ] includes = [ \"*.hs\" ] Lua StyLua command = \"stylua\" includes = [\"*.lua\"] Nix Alejandra command = \"alejandra\" includes = [\"*.nix\"] nixpkgs-fmt command = \"nixpkgs-fmt\" includes = [\"*.nix\"] OCaml ocamlformat command = \"ocamlformat\" options = [\"-i\"] includes = [\"*.ml\", \"*.mli\"] PureScript purs-tidy command = \"purs-tidy\" includes = [\"*.purs\"] Python black command = \"black\" includes = [\"*.py\"] Ruby rufo Rufo is an opinionated ruby formatter. By default it exits with status 3 on file change so you have to pass the -x option. command = \"rufo\" options = [\"-x\"] includes = [\"*.rb\"] Rust cargo fmt is not supported as it doesn't follow the spec. It doesn't allow to pass arbitrary files to be formatter, an ability which treefmt relies on. Use rustfmt instead (which is what cargo fmt uses under the hood). rustfmt command = \"rustfmt\" options = [\"--edition\", \"2018\"] includes = [\"*.rs\"] Scala scalafmt command = \"scalafmt\" includes = [\"*.scala\"] Shell shellcheck command = \"shellcheck\" includes = [\"*.sh\"] shfmt command = \"shfmt\" options = [ \"-i\", \"2\", # indent 2 \"-s\", # simplify the code \"-w\", # write back to the file ] includes = [\"*.sh\"] Terraform terraform Make sure to use terraform 1.3.0 or later versions, as earlier versions format only one file at a time. See the details here . command = \"terraform\" options = [\"fmt\"] includes = [\"*.tf\"] Multi-language formatters clang-format A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code. command = \"clang-format\" options = [ \"-i\" ] includes = [ \"*.c\", \"*.cpp\", \"*.cc\", \"*.h\", \"*.hpp\" ] Note: This example focuses on C/C++ but can be modified to be used with other languages. Prettier An opinionated code formatter that supports many languages. command = \"prettier\" options = [\"--write\"] includes = [ \"*.css\", \"*.html\", \"*.js\", \"*.json\", \"*.jsx\", \"*.md\", \"*.mdx\", \"*.scss\", \"*.ts\", \"*.yaml\", ]","title":"Known Formatters"},{"location":"formatters/#known-formatters","text":"Here is a list of all the formatters we tested. Feel free to send a PR to add other ones!","title":"Known formatters"},{"location":"formatters/#contents","text":"Single-language formatters: Cabal cabal-fmt Elm elm-format Golang gofmt gofumpt Haskell hlint ormolu stylish-haskell Lua StyLua Nix alejandra nixpkgs-fmt OCaml ocamlformat PureScript purs-tidy Python black Ruby rufo Rust rustfmt Scala scalafmt Shell shellcheck shfmt Terraform terraform fmt Multilanguage formatters: clang-format Prettier","title":"Contents"},{"location":"formatters/#cabal","text":"","title":"Cabal"},{"location":"formatters/#cabal-fmt","text":"command = \"cabal-fmt\" options = [\"--inplace\"] includes = [\"*.cabal\"]","title":"cabal-fmt"},{"location":"formatters/#elm","text":"","title":"Elm"},{"location":"formatters/#elm-format","text":"command = \"elm-format\" options = [\"--yes\"] includes = [\"*.elm\"]","title":"elm-format"},{"location":"formatters/#golang","text":"","title":"Golang"},{"location":"formatters/#gofmt","text":"command = \"gofmt\" options = [\"-w\"] includes = [\"*.go\"]","title":"gofmt"},{"location":"formatters/#gofumpt","text":"command = \"gofumpt\" includes = [\"*.go\"]","title":"gofumpt"},{"location":"formatters/#haskell","text":"","title":"Haskell"},{"location":"formatters/#hlint","text":"command = \"hlint\" includes = [ \"*.hs\" ]","title":"hlint"},{"location":"formatters/#ormolu","text":"Make sure to use ormolu 0.1.4.0+ as older versions don't adhere to the spec. command = \"ormolu\" options = [ \"--ghc-opt\", \"-XBangPatterns\", \"--ghc-opt\", \"-XPatternSynonyms\", \"--ghc-opt\", \"-XTypeApplications\", \"--mode\", \"inplace\", \"--check-idempotence\", ] includes = [\"*.hs\"]","title":"Ormolu"},{"location":"formatters/#stylish-haskell","text":"command = \"stylish-haskell\" options = [ \"--inplace\" ] includes = [ \"*.hs\" ]","title":"stylish-haskell"},{"location":"formatters/#lua","text":"","title":"Lua"},{"location":"formatters/#stylua","text":"command = \"stylua\" includes = [\"*.lua\"]","title":"StyLua"},{"location":"formatters/#nix","text":"","title":"Nix"},{"location":"formatters/#alejandra","text":"command = \"alejandra\" includes = [\"*.nix\"]","title":"Alejandra"},{"location":"formatters/#nixpkgs-fmt","text":"command = \"nixpkgs-fmt\" includes = [\"*.nix\"]","title":"nixpkgs-fmt"},{"location":"formatters/#ocaml","text":"","title":"OCaml"},{"location":"formatters/#ocamlformat","text":"command = \"ocamlformat\" options = [\"-i\"] includes = [\"*.ml\", \"*.mli\"]","title":"ocamlformat"},{"location":"formatters/#purescript","text":"","title":"PureScript"},{"location":"formatters/#purs-tidy","text":"command = \"purs-tidy\" includes = [\"*.purs\"]","title":"purs-tidy"},{"location":"formatters/#python","text":"","title":"Python"},{"location":"formatters/#black","text":"command = \"black\" includes = [\"*.py\"]","title":"black"},{"location":"formatters/#ruby","text":"","title":"Ruby"},{"location":"formatters/#rufo","text":"Rufo is an opinionated ruby formatter. By default it exits with status 3 on file change so you have to pass the -x option. command = \"rufo\" options = [\"-x\"] includes = [\"*.rb\"]","title":"rufo"},{"location":"formatters/#rust","text":"cargo fmt is not supported as it doesn't follow the spec. It doesn't allow to pass arbitrary files to be formatter, an ability which treefmt relies on. Use rustfmt instead (which is what cargo fmt uses under the hood).","title":"Rust"},{"location":"formatters/#rustfmt","text":"command = \"rustfmt\" options = [\"--edition\", \"2018\"] includes = [\"*.rs\"]","title":"rustfmt"},{"location":"formatters/#scala","text":"","title":"Scala"},{"location":"formatters/#scalafmt","text":"command = \"scalafmt\" includes = [\"*.scala\"]","title":"scalafmt"},{"location":"formatters/#shell","text":"","title":"Shell"},{"location":"formatters/#shellcheck","text":"command = \"shellcheck\" includes = [\"*.sh\"]","title":"shellcheck"},{"location":"formatters/#shfmt","text":"command = \"shfmt\" options = [ \"-i\", \"2\", # indent 2 \"-s\", # simplify the code \"-w\", # write back to the file ] includes = [\"*.sh\"]","title":"shfmt"},{"location":"formatters/#terraform","text":"","title":"Terraform"},{"location":"formatters/#terraform_1","text":"Make sure to use terraform 1.3.0 or later versions, as earlier versions format only one file at a time. See the details here . command = \"terraform\" options = [\"fmt\"] includes = [\"*.tf\"]","title":"terraform"},{"location":"formatters/#multi-language-formatters","text":"","title":"Multi-language formatters"},{"location":"formatters/#clang-format","text":"A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code. command = \"clang-format\" options = [ \"-i\" ] includes = [ \"*.c\", \"*.cpp\", \"*.cc\", \"*.h\", \"*.hpp\" ] Note: This example focuses on C/C++ but can be modified to be used with other languages.","title":"clang-format"},{"location":"formatters/#prettier","text":"An opinionated code formatter that supports many languages. command = \"prettier\" options = [\"--write\"] includes = [ \"*.css\", \"*.html\", \"*.js\", \"*.json\", \"*.jsx\", \"*.md\", \"*.mdx\", \"*.scss\", \"*.ts\", \"*.yaml\", ]","title":"Prettier"},{"location":"index-formatters/","text":"Formatters In order to catch up with all the formatters available for different programming languages, we created two files as our guideline: Formatter Specifications \u2014 Guidelines for formatter creators to have a smooth integration with treefmt Formatter Example \u2014 List of the available formatters with the corresponding configs that can be inserted into treefmt.toml","title":"About"},{"location":"index-formatters/#formatters","text":"In order to catch up with all the formatters available for different programming languages, we created two files as our guideline: Formatter Specifications \u2014 Guidelines for formatter creators to have a smooth integration with treefmt Formatter Example \u2014 List of the available formatters with the corresponding configs that can be inserted into treefmt.toml","title":"Formatters"},{"location":"installation/","text":"Installation There are two options to install treefmt : by downloading the latest binary, or by compiling and building the tool from source. Installing with a binary file You can find the list of the latest binaries here . Building from source There are several ways to build treefmt from source. Your choice will depend on whether you're a nix user. Non-Nix User To try the project without building it, run: $ cargo run -- --help The command will output the manual. You can run the tool in this manner with any other flag or option to format your project. To build a binary, you need to have rust installed. You can install it with rustup . Now, if you want to build the project, switch to the project root folder and run: $ cargo build After the successful execution of the cargo build command, you will find the treefmt binary in the target folder. Nix User Nix is a package manager foundational for NixOS. You can use it in NixOS and in any other OS equally. If you're using both treefmt and nix , you can go for treefmt-nix , a special tool that makes installation and configuration of treefmt with nix easier. Non-flake user Here you also have two options: you can install treefmt with plain nix-build , or with nix-shell. To build the package with nix-build, just run: $ nix-build -A treefmt Nix-flake user If you want to use this repository with flakes, please enable the flakes feature first. To run the project with flakes without building it, you can execute the following command in the root folder: $ nix run . -- --help To build the project, run the following command in the root folder: $ nix build The treefmt binary will be available in the result folder.","title":"Installation"},{"location":"installation/#installation","text":"There are two options to install treefmt : by downloading the latest binary, or by compiling and building the tool from source.","title":"Installation"},{"location":"installation/#installing-with-a-binary-file","text":"You can find the list of the latest binaries here .","title":"Installing with a binary file"},{"location":"installation/#building-from-source","text":"There are several ways to build treefmt from source. Your choice will depend on whether you're a nix user.","title":"Building from source"},{"location":"installation/#non-nix-user","text":"To try the project without building it, run: $ cargo run -- --help The command will output the manual. You can run the tool in this manner with any other flag or option to format your project. To build a binary, you need to have rust installed. You can install it with rustup . Now, if you want to build the project, switch to the project root folder and run: $ cargo build After the successful execution of the cargo build command, you will find the treefmt binary in the target folder.","title":"Non-Nix User"},{"location":"installation/#nix-user","text":"Nix is a package manager foundational for NixOS. You can use it in NixOS and in any other OS equally. If you're using both treefmt and nix , you can go for treefmt-nix , a special tool that makes installation and configuration of treefmt with nix easier. Non-flake user Here you also have two options: you can install treefmt with plain nix-build , or with nix-shell. To build the package with nix-build, just run: $ nix-build -A treefmt Nix-flake user If you want to use this repository with flakes, please enable the flakes feature first. To run the project with flakes without building it, you can execute the following command in the root folder: $ nix run . -- --help To build the project, run the following command in the root folder: $ nix build The treefmt binary will be available in the result folder.","title":"Nix User"},{"location":"integrations/","text":"Integrations add your project here. Here is a list of projects that integrate with treefmt. the vim null-ls plugin See https://github.com/jose-elias-alvarez/null-ls.nvim/pull/1512 for usage.","title":"Integrations"},{"location":"integrations/#integrations","text":"add your project here. Here is a list of projects that integrate with treefmt.","title":"Integrations"},{"location":"integrations/#the-vim-null-ls-plugin","text":"See https://github.com/jose-elias-alvarez/null-ls.nvim/pull/1512 for usage.","title":"the vim null-ls plugin"},{"location":"quickstart/","text":"Quickstart To run treefmt in your project, please follow these steps: Install the tool. Install the needed formatters. Run treefmt --init . This will generate the basic configuration file treefmt.toml containing the formatting rules. Edit the configuration (see here how). Run treefmt with the needed flags and options. You can check the supported options by executing treefmt --help . In the following sections we will guide you through installing and configuring treefmt in detail.","title":"About"},{"location":"quickstart/#quickstart","text":"To run treefmt in your project, please follow these steps: Install the tool. Install the needed formatters. Run treefmt --init . This will generate the basic configuration file treefmt.toml containing the formatting rules. Edit the configuration (see here how). Run treefmt with the needed flags and options. You can check the supported options by executing treefmt --help . In the following sections we will guide you through installing and configuring treefmt in detail.","title":"Quickstart"},{"location":"treefmt-configuration/","text":"Configuration treefmt can only be run in the presence of treefmt.toml where files are mapped to specific code formatters. Usually the config file sits in the project root folder. If you're running treefmt in one of the project's folders, then treefmt will look for the config in the parent folders up until the project's root. However, you can place the config anywhere in your project's file tree and specify the path in the the ---config-file flag. The typical section of treefmt.toml looks like this: [formatter.] command = \"\" options = [\"\"...] includes = [\"\"] ...where name is just an identifier. [formatter.elm] command = \"elm-format\" options = [\"--yes\"] includes = [\"*.elm\"] Make sure you installed all the formatters specified in the config before running treefmt . If you don't want to install all formatters, you can still run treefmt by specifying the flag --allow-missing-formatter . This will make the program not error out if the needed formatter is missing. Configuration format [formatter.] This section describes the integration between a single formatter and treefmt. \"Name\" here is a unique ID of your formatter in the config file. It doesn't have to match the formatter name. command : A list of arguments to be executed. This will be concatenated with the options attribute during invocation. The first argument is the name of the executable to run. options : A list of extra arguments to add to the command. These are typically project-specific arguments. includes : A list of glob patterns to match file names, including extensions and paths, used to select specific files for formatting. Typically, only file extensions are specified to pick all files written in a specific language. For instance,[ \"*.sh\" ] selects shell script files. But sometimes, you may need to specify a full file name, like [ \"Makefile\" ], or a pattern picking files in a specific folder, like [ \"/home/user/project/*\" ]. excludes : A list of glob patterns to exclude from formatting. If any of these patterns match, the file will be excluded from formatting by a particular formatter. [global] This section describes the configuration properties that apply to every formatter. excludes : A list of glob patterns to deny. If any of these patterns match, the file won't be formatted. This list is appended to the individual formatter's excludes lists.","title":"Configuration"},{"location":"treefmt-configuration/#configuration","text":"treefmt can only be run in the presence of treefmt.toml where files are mapped to specific code formatters. Usually the config file sits in the project root folder. If you're running treefmt in one of the project's folders, then treefmt will look for the config in the parent folders up until the project's root. However, you can place the config anywhere in your project's file tree and specify the path in the the ---config-file flag. The typical section of treefmt.toml looks like this: [formatter.] command = \"\" options = [\"\"...] includes = [\"\"] ...where name is just an identifier. [formatter.elm] command = \"elm-format\" options = [\"--yes\"] includes = [\"*.elm\"] Make sure you installed all the formatters specified in the config before running treefmt . If you don't want to install all formatters, you can still run treefmt by specifying the flag --allow-missing-formatter . This will make the program not error out if the needed formatter is missing.","title":"Configuration"},{"location":"treefmt-configuration/#configuration-format","text":"","title":"Configuration format"},{"location":"treefmt-configuration/#formattername","text":"This section describes the integration between a single formatter and treefmt. \"Name\" here is a unique ID of your formatter in the config file. It doesn't have to match the formatter name. command : A list of arguments to be executed. This will be concatenated with the options attribute during invocation. The first argument is the name of the executable to run. options : A list of extra arguments to add to the command. These are typically project-specific arguments. includes : A list of glob patterns to match file names, including extensions and paths, used to select specific files for formatting. Typically, only file extensions are specified to pick all files written in a specific language. For instance,[ \"*.sh\" ] selects shell script files. But sometimes, you may need to specify a full file name, like [ \"Makefile\" ], or a pattern picking files in a specific folder, like [ \"/home/user/project/*\" ]. excludes : A list of glob patterns to exclude from formatting. If any of these patterns match, the file will be excluded from formatting by a particular formatter.","title":"[formatter.<name>]"},{"location":"treefmt-configuration/#global","text":"This section describes the configuration properties that apply to every formatter. excludes : A list of glob patterns to deny. If any of these patterns match, the file won't be formatted. This list is appended to the individual formatter's excludes lists.","title":"[global]"},{"location":"usage/","text":"Usage You can run treefmt by executing: $ treefmt or, if it's not in your $PATH : $ ./treefmt Treefmt has the following specification: treefmt [FLAGS] [OPTIONS] [--] [paths]... Flags --allow-missing-formatter Do not exit with an error if some of the configured formatters are missing. --clear-cache Reset the evaluation cache. Invalidation should happen automatically if the formatting tool has been updated, or if the files to format have changed. If cache wasn't properly invalidated, you can use this flag to clear the cache. --fail-on-change Exit with error if some files require re-formatting. This is useful for your CI if you want to detect if the contributed code was forgotten to be formatted. -h, --help Prints available flags and options --init Creates a new config file treefmt.toml . --no-cache Tells treefmt to ignore the evaluation cache entirely. With this flag, you can avoid cache invalidation issues, if any. Typically, the machine that is running treefmt in the CI is starting with a fresh environment each time, so any calculated cache is lost. The --no-cache flag eliminates unnecessary work in the CI. -q, --quiet Don't print output to stderr. --stdin Format the content passed in stdin. -V, --version Print version information. -v, --verbose Change the log verbosity. Log verbosity is based off the number of 'v' used. With one -v , your logs will display [INFO] and [ERROR] messages, while -vv will also show [DEBUG] messages. --config-file Run with the specified config file which is not in the project tree. -f, --formatters ... Only apply selected formatters. Defaults to all formatters. --tree-root Set the path to the tree root directory where treefmt will look for the files to format. Defaults to the folder holding the treefmt.toml file. It\u2019s mostly useful in combination with \u2014config-file to specify the project root which won\u2019t coincide with the directory holding treefmt.toml . -C Run as if treefmt was started in instead of the current working directory (default: .). Equivalent to cd ; treefmt . Arguments ... Paths to format. Defaults to formatting the whole tree CI integration Typically, you would use treefmt in the CI with the --fail-on-change and --no-cache flags . Find the explanations above. You can you set a treefmt job in the GitHub pipeline for Ubuntu with nix-shell like this: name: treefmt on: pull_request: push: branches: main jobs: formatter: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - uses: cachix/install-nix-action@v12 with: nix_path: nixpkgs=channel:nixos-unstable - uses: cachix/cachix-action@v10 with: name: nix-community authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}' - name: treefmt run: nix-shell --run \"treefmt --fail-on-change --no-cache\"","title":"Usage"},{"location":"usage/#usage","text":"You can run treefmt by executing: $ treefmt or, if it's not in your $PATH : $ ./treefmt Treefmt has the following specification: treefmt [FLAGS] [OPTIONS] [--] [paths]...","title":"Usage"},{"location":"usage/#flags","text":"--allow-missing-formatter Do not exit with an error if some of the configured formatters are missing. --clear-cache Reset the evaluation cache. Invalidation should happen automatically if the formatting tool has been updated, or if the files to format have changed. If cache wasn't properly invalidated, you can use this flag to clear the cache. --fail-on-change Exit with error if some files require re-formatting. This is useful for your CI if you want to detect if the contributed code was forgotten to be formatted. -h, --help Prints available flags and options --init Creates a new config file treefmt.toml . --no-cache Tells treefmt to ignore the evaluation cache entirely. With this flag, you can avoid cache invalidation issues, if any. Typically, the machine that is running treefmt in the CI is starting with a fresh environment each time, so any calculated cache is lost. The --no-cache flag eliminates unnecessary work in the CI. -q, --quiet Don't print output to stderr. --stdin Format the content passed in stdin. -V, --version Print version information. -v, --verbose Change the log verbosity. Log verbosity is based off the number of 'v' used. With one -v , your logs will display [INFO] and [ERROR] messages, while -vv will also show [DEBUG] messages. --config-file Run with the specified config file which is not in the project tree. -f, --formatters ... Only apply selected formatters. Defaults to all formatters. --tree-root Set the path to the tree root directory where treefmt will look for the files to format. Defaults to the folder holding the treefmt.toml file. It\u2019s mostly useful in combination with \u2014config-file to specify the project root which won\u2019t coincide with the directory holding treefmt.toml . -C Run as if treefmt was started in instead of the current working directory (default: .). Equivalent to cd ; treefmt .","title":"Flags"},{"location":"usage/#arguments","text":"... Paths to format. Defaults to formatting the whole tree","title":"Arguments"},{"location":"usage/#ci-integration","text":"Typically, you would use treefmt in the CI with the --fail-on-change and --no-cache flags . Find the explanations above. You can you set a treefmt job in the GitHub pipeline for Ubuntu with nix-shell like this: name: treefmt on: pull_request: push: branches: main jobs: formatter: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - uses: cachix/install-nix-action@v12 with: nix_path: nixpkgs=channel:nixos-unstable - uses: cachix/cachix-action@v10 with: name: nix-community authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}' - name: treefmt run: nix-shell --run \"treefmt --fail-on-change --no-cache\"","title":"CI integration"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"About the project treefmt is a formatting tool that saves you time: it provides developers with a universal way to trigger all formatters needed for the project in one place. Background Typically, each project has its own code standards enforced by the project's owner. Any code contributions must match that given standard, i.e. be formatted in a specific manner. At first glance, the task of code formatting may seem trivial: the formatter can be automatically triggered when you save a file in your IDE. Indeed, formatting doesn't take much effort if you're working on a single project long term: setting up the formatters in your IDE won't take much of your time, and then you're ready to go. Contrary to that, if you're working on multiple projects at the same time, you may have to update your formatter configs in the IDE each time you switch between the projects. This is because formatter settings aren't project-specific --- they are set up globally for all projects. Alternatively, you can trigger formatters manually, one-by-one or in a script. Actually, for bigger projects, it's common to have a script that runs over your project's directories and calls formatters consequently. But it takes time to iterate through all the files. All the solutions take up a significant amount of time which a developer could spend doing the actual work. They also require you to remember which formatters and options are used by each project you are working on. treefmt solves these issues. Why treefmt? treefmt 's configuration is project-specific, so you don't need to re-configure formatters each time you switch between projects, like you have to when working with formatters in the IDE. Contrary to calling formatters from the command line, there's no need to remember all the specific formatters required for each project. Once you set up the config, you can run the tool in any of your project's folders without any additional flags or options. Typically, formatters have different ways to say there was a specific error. With treefmt , you get a standardized output which is easier to understand than the variegated outputs of different formatters, so it takes less time to grasp what's wrong. In addition, treefmt works faster than the custom script solution because the changed files are cached and the formatters run only against them. Moreover, formatters are run in parallel, which makes the tool even faster. The difference may not be significant for smaller projects, but it gets quite visible as the project grows. For instance, take the caching optimization. It takes 9 seconds to traverse a project of 1507 files and no changes without caching: traversed 1507 files matched 828 files to formatters left with 828 files after cache of whom 0 files were re-formatted all of this in 9s ...while it takes 124 milliseconds to traverse the same project with caching: traversed 1507 files matched 828 files to formatters left with 0 files after cache of whom 0 files were re-formatted all of this in 124ms The tool can be invoked manually or integrated into your CI. There's currently no integration with IDEs, but the feature is coming soon. What we still need help with IDE integration: Most of developers are used to formatting a file upon save in the IDE. So far, you can't use treefmt for this purpose, but we're working on it \ud83d\ude00 Pre-commit hook: It's good to have your code checked for adherence to the project's standards before commit. treefmt pre-commit hook won't let you commit if you have formatting issues. Support of multiple formatters for one language: In the current version, we advise you to avoid using multiple formatters for one and the same file type. This is because formatters are run in parallel and therefore may encounter issues while processing files. We are going to fix this issue soon, since there are cases when you may need more than one formatter per language. As a next step, learn how to install and use treefmt .","title":"Home"},{"location":"#about-the-project","text":"treefmt is a formatting tool that saves you time: it provides developers with a universal way to trigger all formatters needed for the project in one place.","title":"About the project"},{"location":"#background","text":"Typically, each project has its own code standards enforced by the project's owner. Any code contributions must match that given standard, i.e. be formatted in a specific manner. At first glance, the task of code formatting may seem trivial: the formatter can be automatically triggered when you save a file in your IDE. Indeed, formatting doesn't take much effort if you're working on a single project long term: setting up the formatters in your IDE won't take much of your time, and then you're ready to go. Contrary to that, if you're working on multiple projects at the same time, you may have to update your formatter configs in the IDE each time you switch between the projects. This is because formatter settings aren't project-specific --- they are set up globally for all projects. Alternatively, you can trigger formatters manually, one-by-one or in a script. Actually, for bigger projects, it's common to have a script that runs over your project's directories and calls formatters consequently. But it takes time to iterate through all the files. All the solutions take up a significant amount of time which a developer could spend doing the actual work. They also require you to remember which formatters and options are used by each project you are working on. treefmt solves these issues.","title":"Background"},{"location":"#why-treefmt","text":"treefmt 's configuration is project-specific, so you don't need to re-configure formatters each time you switch between projects, like you have to when working with formatters in the IDE. Contrary to calling formatters from the command line, there's no need to remember all the specific formatters required for each project. Once you set up the config, you can run the tool in any of your project's folders without any additional flags or options. Typically, formatters have different ways to say there was a specific error. With treefmt , you get a standardized output which is easier to understand than the variegated outputs of different formatters, so it takes less time to grasp what's wrong. In addition, treefmt works faster than the custom script solution because the changed files are cached and the formatters run only against them. Moreover, formatters are run in parallel, which makes the tool even faster. The difference may not be significant for smaller projects, but it gets quite visible as the project grows. For instance, take the caching optimization. It takes 9 seconds to traverse a project of 1507 files and no changes without caching: traversed 1507 files matched 828 files to formatters left with 828 files after cache of whom 0 files were re-formatted all of this in 9s ...while it takes 124 milliseconds to traverse the same project with caching: traversed 1507 files matched 828 files to formatters left with 0 files after cache of whom 0 files were re-formatted all of this in 124ms The tool can be invoked manually or integrated into your CI. There's currently no integration with IDEs, but the feature is coming soon.","title":"Why treefmt?"},{"location":"#what-we-still-need-help-with","text":"IDE integration: Most of developers are used to formatting a file upon save in the IDE. So far, you can't use treefmt for this purpose, but we're working on it \ud83d\ude00 Pre-commit hook: It's good to have your code checked for adherence to the project's standards before commit. treefmt pre-commit hook won't let you commit if you have formatting issues. Support of multiple formatters for one language: In the current version, we advise you to avoid using multiple formatters for one and the same file type. This is because formatters are run in parallel and therefore may encounter issues while processing files. We are going to fix this issue soon, since there are cases when you may need more than one formatter per language. As a next step, learn how to install and use treefmt .","title":"What we still need help with"},{"location":"contributing/","text":"Contribution guidelines This file contains instructions that will help you make a contribution. Licensing The treefmt binaries and this user guide are licensed under the MIT license . Before you contribute Here you can take a look at the existing issues . Feel free to contribute, but make sure you have a GitHub account first :) . If you're new to open source, please read GitHub's guide on How to Contribute to Open Source . It's a quick read, and it's a great way to introduce yourself to how things work behind the scenes in open-source projects. Before sending a pull request, make sure that you've read all the guidelines. If you don't understand something, please state your question clearly in an issue or ask the community on the treefmt matrix server . Creating an issue If you need to create an issue, make sure to clearly describe it, including: The steps to reproduce it if it's a bug The version of treefmt used The database driver and version The database version The cache database is stored in a toml file the ~/.cache/treefmt directory. Making changes If you want to introduce changes to the project, please follow these steps: Fork the repository on GitHub Create a branch on your fork. Don't commit directly to main Add the necessary tests for your changes Run treefmt in the source directory before you commit your changes Push your changes to the branch in your repository fork Submit a pull request to the original repository Make sure you based your commits on logical and atomic units! Examples of git history Git history that we want to have: Git history that we are trying to avoid: Git history that we want to have * e3ed88b (HEAD -> contribution-guide, upstream/main, origin/main, origin/HEAD, main) Merge pull request #470 from zimbatm/fix_lru_cache |\\ | * 1ab7d9f Use rayon for multithreading command |/ * e9c5bb4 Merge pull request #468 from zimbatm/multithread |\\ | * de2d6cf Add lint property for Formatter struct | * cd2ed17 Fix impl on Formatter get_command() function |/ * 028c344 Merge pull request #465 from rayon/0.15.0-release |\\ | * 7b619d6 0.15.0 release |/ * acdf7df Merge pull request #463 from zimbatm/support-multi-part-namespaces Git history that we are trying to avoid: * 4c8aca8 Merge pull request #120 from zimbatm/add-rayon |\\ | * fc2b449 use rayon for engine now | * 2304683 add rayon config | * 5285bd3 bump base image to F30 * | 4d0fbe2 Merge pull request #114 from rizary/create_method_create_release |\\ \\ | * | 36a9396 test changed | * | 22f681d method create release for github created * | | 2ef4ea1 Merge pull request #119 from rizary/config.rs |\\ \\ \\ | |/ / |/| | | * | 5f1b8f0 unused functions removed * | | a93c361 Merge pull request #117 from zimbatm/add-getreleases-to-abstract |\\ \\ \\ | |/ / |/| | | * | 0a97236 add get_releses for Cargo | * | 55e4c57 add get_releases/get_release into engine.rs |/ / * | badeddd Merge pull request #101 from zimbatm/extreme-cachin Additionally, it's always good to work on improving documentation and adding examples. Thank you for considering contributing to treefmt .","title":"Contributing"},{"location":"contributing/#contribution-guidelines","text":"This file contains instructions that will help you make a contribution.","title":"Contribution guidelines"},{"location":"contributing/#licensing","text":"The treefmt binaries and this user guide are licensed under the MIT license .","title":"Licensing"},{"location":"contributing/#before-you-contribute","text":"Here you can take a look at the existing issues . Feel free to contribute, but make sure you have a GitHub account first :) . If you're new to open source, please read GitHub's guide on How to Contribute to Open Source . It's a quick read, and it's a great way to introduce yourself to how things work behind the scenes in open-source projects. Before sending a pull request, make sure that you've read all the guidelines. If you don't understand something, please state your question clearly in an issue or ask the community on the treefmt matrix server .","title":"Before you contribute"},{"location":"contributing/#creating-an-issue","text":"If you need to create an issue, make sure to clearly describe it, including: The steps to reproduce it if it's a bug The version of treefmt used The database driver and version The database version The cache database is stored in a toml file the ~/.cache/treefmt directory.","title":"Creating an issue"},{"location":"contributing/#making-changes","text":"If you want to introduce changes to the project, please follow these steps: Fork the repository on GitHub Create a branch on your fork. Don't commit directly to main Add the necessary tests for your changes Run treefmt in the source directory before you commit your changes Push your changes to the branch in your repository fork Submit a pull request to the original repository Make sure you based your commits on logical and atomic units!","title":"Making changes"},{"location":"contributing/#examples-of-git-history","text":"Git history that we want to have: Git history that we are trying to avoid: Git history that we want to have * e3ed88b (HEAD -> contribution-guide, upstream/main, origin/main, origin/HEAD, main) Merge pull request #470 from zimbatm/fix_lru_cache |\\ | * 1ab7d9f Use rayon for multithreading command |/ * e9c5bb4 Merge pull request #468 from zimbatm/multithread |\\ | * de2d6cf Add lint property for Formatter struct | * cd2ed17 Fix impl on Formatter get_command() function |/ * 028c344 Merge pull request #465 from rayon/0.15.0-release |\\ | * 7b619d6 0.15.0 release |/ * acdf7df Merge pull request #463 from zimbatm/support-multi-part-namespaces Git history that we are trying to avoid: * 4c8aca8 Merge pull request #120 from zimbatm/add-rayon |\\ | * fc2b449 use rayon for engine now | * 2304683 add rayon config | * 5285bd3 bump base image to F30 * | 4d0fbe2 Merge pull request #114 from rizary/create_method_create_release |\\ \\ | * | 36a9396 test changed | * | 22f681d method create release for github created * | | 2ef4ea1 Merge pull request #119 from rizary/config.rs |\\ \\ \\ | |/ / |/| | | * | 5f1b8f0 unused functions removed * | | a93c361 Merge pull request #117 from zimbatm/add-getreleases-to-abstract |\\ \\ \\ | |/ / |/| | | * | 0a97236 add get_releses for Cargo | * | 55e4c57 add get_releases/get_release into engine.rs |/ / * | badeddd Merge pull request #101 from zimbatm/extreme-cachin Additionally, it's always good to work on improving documentation and adding examples. Thank you for considering contributing to treefmt .","title":"Examples of git history"},{"location":"faq/","text":"FAQ How does treefmt function? Treefmt traverses all your project's folders, maps files to specific code formatters, and formats the code accordingly. Other tools also traverse the filesystem, but not necessarily starting from the root of the project. Contrary to other formatters, treefmt doesn't preview the changes before writing them to a file. If you want to view the changes, you can always check the diff in your version control (we assume that your project is checked into a version control system). You can also rely on version control if errors were introduced into your code as a result of disruptions in the formatter's work. How is the cache organized? At this moment, the cache is represented by a flat TOML file where file paths are mapped to mtimes . The file is located in: ~/.cache/treefmt/.toml However, we are planning to move the hash file to the destination project's root directory. At the end of each tool run, the cache file gets overwritten with the last formatting time entries. In this way, we can can compare the last change time of the file to the last formatting time, and figure out which files need re-formatting.","title":"FAQ"},{"location":"faq/#faq","text":"","title":"FAQ"},{"location":"faq/#how-does-treefmt-function","text":"Treefmt traverses all your project's folders, maps files to specific code formatters, and formats the code accordingly. Other tools also traverse the filesystem, but not necessarily starting from the root of the project. Contrary to other formatters, treefmt doesn't preview the changes before writing them to a file. If you want to view the changes, you can always check the diff in your version control (we assume that your project is checked into a version control system). You can also rely on version control if errors were introduced into your code as a result of disruptions in the formatter's work.","title":"How does treefmt function?"},{"location":"faq/#how-is-the-cache-organized","text":"At this moment, the cache is represented by a flat TOML file where file paths are mapped to mtimes . The file is located in: ~/.cache/treefmt/.toml However, we are planning to move the hash file to the destination project's root directory. At the end of each tool run, the cache file gets overwritten with the last formatting time entries. In this way, we can can compare the last change time of the file to the last formatting time, and figure out which files need re-formatting.","title":"How is the cache organized?"},{"location":"formatters-spec/","text":"Formatter specification In order to keep the design of treefmt simple, we support only formatters which adhere to a certain standard. This document outlines this standard. If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification. In this design, we rely on treefmt to do the tree traversal, and only invoke the code formatter on the selected files. Rules In order for the formatter to comply to this spec, it MUST follow the following rules: 1. Files passed as arguments In order to be integrated to treefmt 's workflow, the formatter's CLI must adhere to the following specification: [options] [...] Where: is the name of the formatting tool. [options] is any number of flags and options that the formatter accepts. [...] is one or more files given to the formatter for processing. Example: $ rustfmt --edition 2018 src/main.rs src/lib.rs It SHOULD processes only the specified files. Files that are not passed SHOULD never be formatted. 2. Write to changed files Whenever there is a change to the code formatting, the code formatter MUST write to the changes back to the original location. If there is no changes to the original file, the formatter MUST NOT write to the original location. 3. Idempotent The code formatter SHOULD be indempotent. Meaning that it produces stable outputs. 4. Reliable We expect the formatter to be reliable and not break the semantic of the formatted files.","title":"Formatter Specification"},{"location":"formatters-spec/#formatter-specification","text":"In order to keep the design of treefmt simple, we support only formatters which adhere to a certain standard. This document outlines this standard. If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification. In this design, we rely on treefmt to do the tree traversal, and only invoke the code formatter on the selected files.","title":"Formatter specification"},{"location":"formatters-spec/#rules","text":"In order for the formatter to comply to this spec, it MUST follow the following rules:","title":"Rules"},{"location":"formatters-spec/#1-files-passed-as-arguments","text":"In order to be integrated to treefmt 's workflow, the formatter's CLI must adhere to the following specification: [options] [...] Where: is the name of the formatting tool. [options] is any number of flags and options that the formatter accepts. [...] is one or more files given to the formatter for processing. Example: $ rustfmt --edition 2018 src/main.rs src/lib.rs It SHOULD processes only the specified files. Files that are not passed SHOULD never be formatted.","title":"1. Files passed as arguments"},{"location":"formatters-spec/#2-write-to-changed-files","text":"Whenever there is a change to the code formatting, the code formatter MUST write to the changes back to the original location. If there is no changes to the original file, the formatter MUST NOT write to the original location.","title":"2. Write to changed files"},{"location":"formatters-spec/#3-idempotent","text":"The code formatter SHOULD be indempotent. Meaning that it produces stable outputs.","title":"3. Idempotent"},{"location":"formatters-spec/#4-reliable","text":"We expect the formatter to be reliable and not break the semantic of the formatted files.","title":"4. Reliable"},{"location":"formatters/","text":"Known formatters Here is a list of all the formatters we tested. Feel free to send a PR to add other ones! Contents Single-language formatters: Cabal cabal-fmt Elm elm-format Golang gofmt gofumpt Haskell hlint ormolu stylish-haskell Lua StyLua Nix alejandra nixpkgs-fmt OCaml ocamlformat PureScript purs-tidy Python black Ruby rufo Rust rustfmt Scala scalafmt Shell shellcheck shfmt Terraform terraform fmt Multilanguage formatters: clang-format Prettier Cabal cabal-fmt command = \"cabal-fmt\" options = [\"--inplace\"] includes = [\"*.cabal\"] Elm elm-format command = \"elm-format\" options = [\"--yes\"] includes = [\"*.elm\"] Golang gofmt command = \"gofmt\" options = [\"-w\"] includes = [\"*.go\"] gofumpt command = \"gofumpt\" includes = [\"*.go\"] Haskell hlint command = \"hlint\" includes = [ \"*.hs\" ] Ormolu Make sure to use ormolu 0.1.4.0+ as older versions don't adhere to the spec. command = \"ormolu\" options = [ \"--ghc-opt\", \"-XBangPatterns\", \"--ghc-opt\", \"-XPatternSynonyms\", \"--ghc-opt\", \"-XTypeApplications\", \"--mode\", \"inplace\", \"--check-idempotence\", ] includes = [\"*.hs\"] stylish-haskell command = \"stylish-haskell\" options = [ \"--inplace\" ] includes = [ \"*.hs\" ] Lua StyLua command = \"stylua\" includes = [\"*.lua\"] Nix Alejandra command = \"alejandra\" includes = [\"*.nix\"] nixpkgs-fmt command = \"nixpkgs-fmt\" includes = [\"*.nix\"] OCaml ocamlformat command = \"ocamlformat\" options = [\"-i\"] includes = [\"*.ml\", \"*.mli\"] PureScript purs-tidy command = \"purs-tidy\" includes = [\"*.purs\"] Python black command = \"black\" includes = [\"*.py\"] Ruby rufo Rufo is an opinionated ruby formatter. By default it exits with status 3 on file change so you have to pass the -x option. command = \"rufo\" options = [\"-x\"] includes = [\"*.rb\"] Rust cargo fmt is not supported as it doesn't follow the spec. It doesn't allow to pass arbitrary files to be formatter, an ability which treefmt relies on. Use rustfmt instead (which is what cargo fmt uses under the hood). rustfmt command = \"rustfmt\" options = [\"--edition\", \"2018\"] includes = [\"*.rs\"] Scala scalafmt command = \"scalafmt\" includes = [\"*.scala\"] Shell shellcheck command = \"shellcheck\" includes = [\"*.sh\"] shfmt command = \"shfmt\" options = [ \"-i\", \"2\", # indent 2 \"-s\", # simplify the code \"-w\", # write back to the file ] includes = [\"*.sh\"] Terraform terraform Make sure to use terraform 1.3.0 or later versions, as earlier versions format only one file at a time. See the details here . command = \"terraform\" options = [\"fmt\"] includes = [\"*.tf\"] Multi-language formatters clang-format A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code. command = \"clang-format\" options = [ \"-i\" ] includes = [ \"*.c\", \"*.cpp\", \"*.cc\", \"*.h\", \"*.hpp\" ] Note: This example focuses on C/C++ but can be modified to be used with other languages. Prettier An opinionated code formatter that supports many languages. command = \"prettier\" options = [\"--write\"] includes = [ \"*.css\", \"*.html\", \"*.js\", \"*.json\", \"*.jsx\", \"*.md\", \"*.mdx\", \"*.scss\", \"*.ts\", \"*.yaml\", ]","title":"Known Formatters"},{"location":"formatters/#known-formatters","text":"Here is a list of all the formatters we tested. Feel free to send a PR to add other ones!","title":"Known formatters"},{"location":"formatters/#contents","text":"Single-language formatters: Cabal cabal-fmt Elm elm-format Golang gofmt gofumpt Haskell hlint ormolu stylish-haskell Lua StyLua Nix alejandra nixpkgs-fmt OCaml ocamlformat PureScript purs-tidy Python black Ruby rufo Rust rustfmt Scala scalafmt Shell shellcheck shfmt Terraform terraform fmt Multilanguage formatters: clang-format Prettier","title":"Contents"},{"location":"formatters/#cabal","text":"","title":"Cabal"},{"location":"formatters/#cabal-fmt","text":"command = \"cabal-fmt\" options = [\"--inplace\"] includes = [\"*.cabal\"]","title":"cabal-fmt"},{"location":"formatters/#elm","text":"","title":"Elm"},{"location":"formatters/#elm-format","text":"command = \"elm-format\" options = [\"--yes\"] includes = [\"*.elm\"]","title":"elm-format"},{"location":"formatters/#golang","text":"","title":"Golang"},{"location":"formatters/#gofmt","text":"command = \"gofmt\" options = [\"-w\"] includes = [\"*.go\"]","title":"gofmt"},{"location":"formatters/#gofumpt","text":"command = \"gofumpt\" includes = [\"*.go\"]","title":"gofumpt"},{"location":"formatters/#haskell","text":"","title":"Haskell"},{"location":"formatters/#hlint","text":"command = \"hlint\" includes = [ \"*.hs\" ]","title":"hlint"},{"location":"formatters/#ormolu","text":"Make sure to use ormolu 0.1.4.0+ as older versions don't adhere to the spec. command = \"ormolu\" options = [ \"--ghc-opt\", \"-XBangPatterns\", \"--ghc-opt\", \"-XPatternSynonyms\", \"--ghc-opt\", \"-XTypeApplications\", \"--mode\", \"inplace\", \"--check-idempotence\", ] includes = [\"*.hs\"]","title":"Ormolu"},{"location":"formatters/#stylish-haskell","text":"command = \"stylish-haskell\" options = [ \"--inplace\" ] includes = [ \"*.hs\" ]","title":"stylish-haskell"},{"location":"formatters/#lua","text":"","title":"Lua"},{"location":"formatters/#stylua","text":"command = \"stylua\" includes = [\"*.lua\"]","title":"StyLua"},{"location":"formatters/#nix","text":"","title":"Nix"},{"location":"formatters/#alejandra","text":"command = \"alejandra\" includes = [\"*.nix\"]","title":"Alejandra"},{"location":"formatters/#nixpkgs-fmt","text":"command = \"nixpkgs-fmt\" includes = [\"*.nix\"]","title":"nixpkgs-fmt"},{"location":"formatters/#ocaml","text":"","title":"OCaml"},{"location":"formatters/#ocamlformat","text":"command = \"ocamlformat\" options = [\"-i\"] includes = [\"*.ml\", \"*.mli\"]","title":"ocamlformat"},{"location":"formatters/#purescript","text":"","title":"PureScript"},{"location":"formatters/#purs-tidy","text":"command = \"purs-tidy\" includes = [\"*.purs\"]","title":"purs-tidy"},{"location":"formatters/#python","text":"","title":"Python"},{"location":"formatters/#black","text":"command = \"black\" includes = [\"*.py\"]","title":"black"},{"location":"formatters/#ruby","text":"","title":"Ruby"},{"location":"formatters/#rufo","text":"Rufo is an opinionated ruby formatter. By default it exits with status 3 on file change so you have to pass the -x option. command = \"rufo\" options = [\"-x\"] includes = [\"*.rb\"]","title":"rufo"},{"location":"formatters/#rust","text":"cargo fmt is not supported as it doesn't follow the spec. It doesn't allow to pass arbitrary files to be formatter, an ability which treefmt relies on. Use rustfmt instead (which is what cargo fmt uses under the hood).","title":"Rust"},{"location":"formatters/#rustfmt","text":"command = \"rustfmt\" options = [\"--edition\", \"2018\"] includes = [\"*.rs\"]","title":"rustfmt"},{"location":"formatters/#scala","text":"","title":"Scala"},{"location":"formatters/#scalafmt","text":"command = \"scalafmt\" includes = [\"*.scala\"]","title":"scalafmt"},{"location":"formatters/#shell","text":"","title":"Shell"},{"location":"formatters/#shellcheck","text":"command = \"shellcheck\" includes = [\"*.sh\"]","title":"shellcheck"},{"location":"formatters/#shfmt","text":"command = \"shfmt\" options = [ \"-i\", \"2\", # indent 2 \"-s\", # simplify the code \"-w\", # write back to the file ] includes = [\"*.sh\"]","title":"shfmt"},{"location":"formatters/#terraform","text":"","title":"Terraform"},{"location":"formatters/#terraform_1","text":"Make sure to use terraform 1.3.0 or later versions, as earlier versions format only one file at a time. See the details here . command = \"terraform\" options = [\"fmt\"] includes = [\"*.tf\"]","title":"terraform"},{"location":"formatters/#multi-language-formatters","text":"","title":"Multi-language formatters"},{"location":"formatters/#clang-format","text":"A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code. command = \"clang-format\" options = [ \"-i\" ] includes = [ \"*.c\", \"*.cpp\", \"*.cc\", \"*.h\", \"*.hpp\" ] Note: This example focuses on C/C++ but can be modified to be used with other languages.","title":"clang-format"},{"location":"formatters/#prettier","text":"An opinionated code formatter that supports many languages. command = \"prettier\" options = [\"--write\"] includes = [ \"*.css\", \"*.html\", \"*.js\", \"*.json\", \"*.jsx\", \"*.md\", \"*.mdx\", \"*.scss\", \"*.ts\", \"*.yaml\", ]","title":"Prettier"},{"location":"index-formatters/","text":"Formatters In order to catch up with all the formatters available for different programming languages, we created two files as our guideline: Formatter Specifications \u2014 Guidelines for formatter creators to have a smooth integration with treefmt Formatter Example \u2014 List of the available formatters with the corresponding configs that can be inserted into treefmt.toml","title":"About"},{"location":"index-formatters/#formatters","text":"In order to catch up with all the formatters available for different programming languages, we created two files as our guideline: Formatter Specifications \u2014 Guidelines for formatter creators to have a smooth integration with treefmt Formatter Example \u2014 List of the available formatters with the corresponding configs that can be inserted into treefmt.toml","title":"Formatters"},{"location":"installation/","text":"Installation There are two options to install treefmt : by downloading the latest binary, or by compiling and building the tool from source. Installing with a binary file You can find the list of the latest binaries here . Building from source There are several ways to build treefmt from source. Your choice will depend on whether you're a nix user. Non-Nix User To try the project without building it, run: $ cargo run -- --help The command will output the manual. You can run the tool in this manner with any other flag or option to format your project. To build a binary, you need to have rust installed. You can install it with rustup . Now, if you want to build the project, switch to the project root folder and run: $ cargo build After the successful execution of the cargo build command, you will find the treefmt binary in the target folder. Nix User Nix is a package manager foundational for NixOS. You can use it in NixOS and in any other OS equally. If you're using both treefmt and nix , you can go for treefmt-nix , a special tool that makes installation and configuration of treefmt with nix easier. Non-flake user Here you also have two options: you can install treefmt with plain nix-build , or with nix-shell. To build the package with nix-build, just run: $ nix-build -A treefmt Nix-flake user If you want to use this repository with flakes, please enable the flakes feature first. To run the project with flakes without building it, you can execute the following command in the root folder: $ nix run . -- --help To build the project, run the following command in the root folder: $ nix build The treefmt binary will be available in the result folder.","title":"Installation"},{"location":"installation/#installation","text":"There are two options to install treefmt : by downloading the latest binary, or by compiling and building the tool from source.","title":"Installation"},{"location":"installation/#installing-with-a-binary-file","text":"You can find the list of the latest binaries here .","title":"Installing with a binary file"},{"location":"installation/#building-from-source","text":"There are several ways to build treefmt from source. Your choice will depend on whether you're a nix user.","title":"Building from source"},{"location":"installation/#non-nix-user","text":"To try the project without building it, run: $ cargo run -- --help The command will output the manual. You can run the tool in this manner with any other flag or option to format your project. To build a binary, you need to have rust installed. You can install it with rustup . Now, if you want to build the project, switch to the project root folder and run: $ cargo build After the successful execution of the cargo build command, you will find the treefmt binary in the target folder.","title":"Non-Nix User"},{"location":"installation/#nix-user","text":"Nix is a package manager foundational for NixOS. You can use it in NixOS and in any other OS equally. If you're using both treefmt and nix , you can go for treefmt-nix , a special tool that makes installation and configuration of treefmt with nix easier. Non-flake user Here you also have two options: you can install treefmt with plain nix-build , or with nix-shell. To build the package with nix-build, just run: $ nix-build -A treefmt Nix-flake user If you want to use this repository with flakes, please enable the flakes feature first. To run the project with flakes without building it, you can execute the following command in the root folder: $ nix run . -- --help To build the project, run the following command in the root folder: $ nix build The treefmt binary will be available in the result folder.","title":"Nix User"},{"location":"integrations/","text":"Integrations add your project here. Here is a list of projects that integrate with treefmt. the vim null-ls plugin See https://github.com/jose-elias-alvarez/null-ls.nvim/pull/1512 for usage.","title":"Integrations"},{"location":"integrations/#integrations","text":"add your project here. Here is a list of projects that integrate with treefmt.","title":"Integrations"},{"location":"integrations/#the-vim-null-ls-plugin","text":"See https://github.com/jose-elias-alvarez/null-ls.nvim/pull/1512 for usage.","title":"the vim null-ls plugin"},{"location":"quickstart/","text":"Quickstart To run treefmt in your project, please follow these steps: Install the tool. Install the needed formatters. Run treefmt --init . This will generate the basic configuration file treefmt.toml containing the formatting rules. Edit the configuration (see here how). Run treefmt with the needed flags and options. You can check the supported options by executing treefmt --help . In the following sections we will guide you through installing and configuring treefmt in detail.","title":"About"},{"location":"quickstart/#quickstart","text":"To run treefmt in your project, please follow these steps: Install the tool. Install the needed formatters. Run treefmt --init . This will generate the basic configuration file treefmt.toml containing the formatting rules. Edit the configuration (see here how). Run treefmt with the needed flags and options. You can check the supported options by executing treefmt --help . In the following sections we will guide you through installing and configuring treefmt in detail.","title":"Quickstart"},{"location":"treefmt-configuration/","text":"Configuration treefmt can only be run in the presence of treefmt.toml where files are mapped to specific code formatters. Usually the config file sits in the project root folder. If you're running treefmt in one of the project's folders, then treefmt will look for the config in the parent folders up until the project's root. However, you can place the config anywhere in your project's file tree and specify the path in the the ---config-file flag. The typical section of treefmt.toml looks like this: [formatter.] command = \"\" options = [\"\"...] includes = [\"\"] ...where name is just an identifier. [formatter.elm] command = \"elm-format\" options = [\"--yes\"] includes = [\"*.elm\"] Make sure you installed all the formatters specified in the config before running treefmt . If you don't want to install all formatters, you can still run treefmt by specifying the flag --allow-missing-formatter . This will make the program not error out if the needed formatter is missing. Configuration format [formatter.] This section describes the integration between a single formatter and treefmt. \"Name\" here is a unique ID of your formatter in the config file. It doesn't have to match the formatter name. command : A list of arguments to be executed. This will be concatenated with the options attribute during invocation. The first argument is the name of the executable to run. options : A list of extra arguments to add to the command. These are typically project-specific arguments. includes : A list of glob patterns to match file names, including extensions and paths, used to select specific files for formatting. Typically, only file extensions are specified to pick all files written in a specific language. For instance,[ \"*.sh\" ] selects shell script files. But sometimes, you may need to specify a full file name, like [ \"Makefile\" ], or a pattern picking files in a specific folder, like [ \"/home/user/project/*\" ]. excludes : A list of glob patterns to exclude from formatting. If any of these patterns match, the file will be excluded from formatting by a particular formatter. [global] This section describes the configuration properties that apply to every formatter. excludes : A list of glob patterns to deny. If any of these patterns match, the file won't be formatted. This list is appended to the individual formatter's excludes lists.","title":"Configuration"},{"location":"treefmt-configuration/#configuration","text":"treefmt can only be run in the presence of treefmt.toml where files are mapped to specific code formatters. Usually the config file sits in the project root folder. If you're running treefmt in one of the project's folders, then treefmt will look for the config in the parent folders up until the project's root. However, you can place the config anywhere in your project's file tree and specify the path in the the ---config-file flag. The typical section of treefmt.toml looks like this: [formatter.] command = \"\" options = [\"\"...] includes = [\"\"] ...where name is just an identifier. [formatter.elm] command = \"elm-format\" options = [\"--yes\"] includes = [\"*.elm\"] Make sure you installed all the formatters specified in the config before running treefmt . If you don't want to install all formatters, you can still run treefmt by specifying the flag --allow-missing-formatter . This will make the program not error out if the needed formatter is missing.","title":"Configuration"},{"location":"treefmt-configuration/#configuration-format","text":"","title":"Configuration format"},{"location":"treefmt-configuration/#formattername","text":"This section describes the integration between a single formatter and treefmt. \"Name\" here is a unique ID of your formatter in the config file. It doesn't have to match the formatter name. command : A list of arguments to be executed. This will be concatenated with the options attribute during invocation. The first argument is the name of the executable to run. options : A list of extra arguments to add to the command. These are typically project-specific arguments. includes : A list of glob patterns to match file names, including extensions and paths, used to select specific files for formatting. Typically, only file extensions are specified to pick all files written in a specific language. For instance,[ \"*.sh\" ] selects shell script files. But sometimes, you may need to specify a full file name, like [ \"Makefile\" ], or a pattern picking files in a specific folder, like [ \"/home/user/project/*\" ]. excludes : A list of glob patterns to exclude from formatting. If any of these patterns match, the file will be excluded from formatting by a particular formatter.","title":"[formatter.<name>]"},{"location":"treefmt-configuration/#global","text":"This section describes the configuration properties that apply to every formatter. excludes : A list of glob patterns to deny. If any of these patterns match, the file won't be formatted. This list is appended to the individual formatter's excludes lists.","title":"[global]"},{"location":"usage/","text":"Usage You can run treefmt by executing: $ treefmt or, if it's not in your $PATH : $ ./treefmt Treefmt has the following specification: treefmt [FLAGS] [OPTIONS] [--] [paths]... Flags --allow-missing-formatter Do not exit with an error if some of the configured formatters are missing. --clear-cache Reset the evaluation cache. Invalidation should happen automatically if the formatting tool has been updated, or if the files to format have changed. If cache wasn't properly invalidated, you can use this flag to clear the cache. --fail-on-change Exit with error if some files require re-formatting. This is useful for your CI if you want to detect if the contributed code was forgotten to be formatted. -h, --help Prints available flags and options --init Creates a new config file treefmt.toml . --no-cache Tells treefmt to ignore the evaluation cache entirely. With this flag, you can avoid cache invalidation issues, if any. Typically, the machine that is running treefmt in the CI is starting with a fresh environment each time, so any calculated cache is lost. The --no-cache flag eliminates unnecessary work in the CI. -q, --quiet Don't print output to stderr. --stdin Format the content passed in stdin. -V, --version Print version information. -v, --verbose Change the log verbosity. Log verbosity is based off the number of 'v' used. With one -v , your logs will display [INFO] and [ERROR] messages, while -vv will also show [DEBUG] messages. --config-file Run with the specified config file which is not in the project tree. -f, --formatters ... Only apply selected formatters. Defaults to all formatters. --tree-root Set the path to the tree root directory where treefmt will look for the files to format. Defaults to the folder holding the treefmt.toml file. It\u2019s mostly useful in combination with \u2014config-file to specify the project root which won\u2019t coincide with the directory holding treefmt.toml . -C Run as if treefmt was started in instead of the current working directory (default: .). Equivalent to cd ; treefmt . Arguments ... Paths to format. Defaults to formatting the whole tree CI integration Typically, you would use treefmt in the CI with the --fail-on-change and --no-cache flags . Find the explanations above. You can you set a treefmt job in the GitHub pipeline for Ubuntu with nix-shell like this: name: treefmt on: pull_request: push: branches: main jobs: formatter: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - uses: cachix/install-nix-action@v12 with: nix_path: nixpkgs=channel:nixos-unstable - uses: cachix/cachix-action@v10 with: name: nix-community authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}' - name: treefmt run: nix-shell --run \"treefmt --fail-on-change --no-cache\"","title":"Usage"},{"location":"usage/#usage","text":"You can run treefmt by executing: $ treefmt or, if it's not in your $PATH : $ ./treefmt Treefmt has the following specification: treefmt [FLAGS] [OPTIONS] [--] [paths]...","title":"Usage"},{"location":"usage/#flags","text":"--allow-missing-formatter Do not exit with an error if some of the configured formatters are missing. --clear-cache Reset the evaluation cache. Invalidation should happen automatically if the formatting tool has been updated, or if the files to format have changed. If cache wasn't properly invalidated, you can use this flag to clear the cache. --fail-on-change Exit with error if some files require re-formatting. This is useful for your CI if you want to detect if the contributed code was forgotten to be formatted. -h, --help Prints available flags and options --init Creates a new config file treefmt.toml . --no-cache Tells treefmt to ignore the evaluation cache entirely. With this flag, you can avoid cache invalidation issues, if any. Typically, the machine that is running treefmt in the CI is starting with a fresh environment each time, so any calculated cache is lost. The --no-cache flag eliminates unnecessary work in the CI. -q, --quiet Don't print output to stderr. --stdin Format the content passed in stdin. -V, --version Print version information. -v, --verbose Change the log verbosity. Log verbosity is based off the number of 'v' used. With one -v , your logs will display [INFO] and [ERROR] messages, while -vv will also show [DEBUG] messages. --config-file Run with the specified config file which is not in the project tree. -f, --formatters ... Only apply selected formatters. Defaults to all formatters. --tree-root Set the path to the tree root directory where treefmt will look for the files to format. Defaults to the folder holding the treefmt.toml file. It\u2019s mostly useful in combination with \u2014config-file to specify the project root which won\u2019t coincide with the directory holding treefmt.toml . -C Run as if treefmt was started in instead of the current working directory (default: .). Equivalent to cd ; treefmt .","title":"Flags"},{"location":"usage/#arguments","text":"... Paths to format. Defaults to formatting the whole tree","title":"Arguments"},{"location":"usage/#ci-integration","text":"Typically, you would use treefmt in the CI with the --fail-on-change and --no-cache flags . Find the explanations above. You can you set a treefmt job in the GitHub pipeline for Ubuntu with nix-shell like this: name: treefmt on: pull_request: push: branches: main jobs: formatter: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - uses: cachix/install-nix-action@v12 with: nix_path: nixpkgs=channel:nixos-unstable - uses: cachix/cachix-action@v10 with: name: nix-community authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}' - name: treefmt run: nix-shell --run \"treefmt --fail-on-change --no-cache\"","title":"CI integration"}]}
\ No newline at end of file