mirror of
https://github.com/numtide/treefmt.git
synced 2024-09-11 17:07:44 +03:00
Merge pull request #7 from numtide/feat/improve-docs
doc: refine docs and usage
This commit is contained in:
commit
0dd4344339
45
.github/workflows/release.yml
vendored
45
.github/workflows/release.yml
vendored
@ -1,30 +1,29 @@
|
||||
name: goreleaser
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
# run only against tags
|
||||
tags:
|
||||
- "v*"
|
||||
push:
|
||||
# run only against tags
|
||||
tags:
|
||||
- "v*"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
goreleaser:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- name: Setup Go
|
||||
uses: actions/setup-go@v4
|
||||
with:
|
||||
go-version: 1.22.x
|
||||
- name: Run goreleaser
|
||||
uses: goreleaser/goreleaser-action@v4
|
||||
with:
|
||||
args: release --clean
|
||||
env:
|
||||
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
|
||||
goreleaser:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- name: Setup Go
|
||||
uses: actions/setup-go@v4
|
||||
with:
|
||||
go-version: 1.22.x
|
||||
- name: Run goreleaser
|
||||
uses: goreleaser/goreleaser-action@v4
|
||||
with:
|
||||
args: release --clean
|
||||
env:
|
||||
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
|
||||
|
@ -11,23 +11,23 @@ version: 1
|
||||
project_name: treefmt
|
||||
|
||||
before:
|
||||
hooks:
|
||||
- go mod tidy
|
||||
hooks:
|
||||
- go mod tidy
|
||||
|
||||
builds:
|
||||
- env:
|
||||
- CGO_ENABLED=0
|
||||
ldflags:
|
||||
- -s -w -X git.numtide.com/numtide/treefmt/build.Version=v{{.Version}}
|
||||
goos:
|
||||
- linux
|
||||
- darwin
|
||||
- env:
|
||||
- CGO_ENABLED=0
|
||||
ldflags:
|
||||
- -s -w -X git.numtide.com/numtide/treefmt/build.Version=v{{.Version}}
|
||||
goos:
|
||||
- linux
|
||||
- darwin
|
||||
|
||||
changelog:
|
||||
sort: asc
|
||||
use: github
|
||||
filters:
|
||||
exclude:
|
||||
- "^chore:"
|
||||
- "^docs:"
|
||||
- "^test:"
|
||||
sort: asc
|
||||
use: github
|
||||
filters:
|
||||
exclude:
|
||||
- "^chore:"
|
||||
- "^docs:"
|
||||
- "^test:"
|
||||
|
20
cli/cli.go
20
cli/cli.go
@ -9,23 +9,23 @@ import (
|
||||
var Cli = Format{}
|
||||
|
||||
type Format struct {
|
||||
AllowMissingFormatter bool `default:"false" help:"Do not exit with error if a configured formatter is missing"`
|
||||
WorkingDirectory kong.ChangeDirFlag `default:"." short:"C" help:"Run as if treefmt was started in the specified working directory instead of the current working directory"`
|
||||
NoCache bool `help:"Ignore the evaluation cache entirely. Useful for CI"`
|
||||
ClearCache bool `short:"c" help:"Reset the evaluation cache. Use in case the cache is not precise enough"`
|
||||
ConfigFile string `type:"existingfile" default:"./treefmt.toml"`
|
||||
AllowMissingFormatter bool `default:"false" help:"Do not exit with error if a configured formatter is missing."`
|
||||
WorkingDirectory kong.ChangeDirFlag `default:"." short:"C" help:"Run as if treefmt was started in the specified working directory instead of the current working directory."`
|
||||
NoCache bool `help:"Ignore the evaluation cache entirely. Useful for CI."`
|
||||
ClearCache bool `short:"c" help:"Reset the evaluation cache. Use in case the cache is not precise enough."`
|
||||
ConfigFile string `type:"existingfile" default:"./treefmt.toml" help:"The config file to use."`
|
||||
FailOnChange bool `help:"Exit with error if any changes were made. Useful for CI."`
|
||||
Formatters []string `help:"Specify formatters to apply. Defaults to all formatters."`
|
||||
TreeRoot string `type:"existingdir" default:"."`
|
||||
TreeRoot string `type:"existingdir" default:"." help:"The root directory from which treefmt will start walking the filesystem."`
|
||||
Walk walk.Type `enum:"auto,git,filesystem" default:"auto" help:"The method used to traverse the files within --tree-root. Currently supports 'auto', 'git' or 'filesystem'."`
|
||||
Verbosity int `name:"verbose" short:"v" type:"counter" default:"0" env:"LOG_LEVEL" help:"Set the verbosity of logs e.g. -vv."`
|
||||
Version bool `name:"version" short:"V" help:"Print version"`
|
||||
Init bool `name:"init" short:"i" help:"Create a new treefmt.toml"`
|
||||
Version bool `name:"version" short:"V" help:"Print version."`
|
||||
Init bool `name:"init" short:"i" help:"Create a new treefmt.toml."`
|
||||
|
||||
Paths []string `name:"paths" arg:"" type:"path" optional:"" help:"Paths to format. Defaults to formatting the whole tree."`
|
||||
Stdin bool `help:"Format the context passed in via stdin"`
|
||||
Stdin bool `help:"Format the context passed in via stdin."`
|
||||
|
||||
CpuProfile string `optional:"" help:"file into which a cpu profile will be written"`
|
||||
CpuProfile string `optional:"" help:"The file into which a cpu profile will be written."`
|
||||
}
|
||||
|
||||
func ConfigureLogging() {
|
||||
|
@ -1,7 +1,7 @@
|
||||
package config
|
||||
|
||||
type Formatter struct {
|
||||
// Command is the command invoke when applying this Formatter.
|
||||
// Command is the command to invoke when applying this Formatter.
|
||||
Command string
|
||||
// Options are an optional list of args to be passed to Command.
|
||||
Options []string
|
||||
|
@ -23,10 +23,11 @@ export default defineConfig({
|
||||
|
||||
sidebar: [
|
||||
{ text: 'Quick Start', link: '/quick-start' },
|
||||
{ text: 'Installation', link: '/installation' },
|
||||
{ text: 'Overview', link: '/overview' },
|
||||
{ text: 'Usage', link: '/usage' },
|
||||
{ text: 'Formatter Specification', link: '/formatter-spec' },
|
||||
{ text: 'Install Treefmt', link: '/install' },
|
||||
{ text: 'Configure Treefmt', link: '/configure' },
|
||||
{ text: 'Run Treefmt', link: '/usage' },
|
||||
{ text: 'Motivation', link: '/about' },
|
||||
{ text: 'Formatter Spec', link: '/formatter-spec' },
|
||||
{ text: 'Contributing', link: '/contributing' },
|
||||
{ text: 'FAQ', link: '/faq' },
|
||||
],
|
||||
|
@ -69,7 +69,7 @@ The tool can be invoked manually or integrated into your CI. There's currently n
|
||||
- **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 😀
|
||||
- **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.
|
||||
|
||||
As a next step, learn how to [install] and [use] `treefmt`.
|
||||
As a next step, learn how to [install] and [run] `treefmt`.
|
||||
|
||||
[install]: installation.md
|
||||
[use]: usage.md
|
||||
[install]: install
|
||||
[run]: usage
|
201
docs/configure.md
Normal file
201
docs/configure.md
Normal file
@ -0,0 +1,201 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Configure Treefmt
|
||||
|
||||
The `treefmt.toml` configuration file consists of a mixture of global options and formatter sections:
|
||||
|
||||
```toml
|
||||
excludes = ["*.md", "*.dat"]
|
||||
|
||||
[formatter.elm]
|
||||
command = "elm-format"
|
||||
options = ["--yes"]
|
||||
includes = ["*.elm"]
|
||||
|
||||
[formatter.go]
|
||||
command = "gofmt"
|
||||
options = ["-w"]
|
||||
includes = ["*.go"]
|
||||
|
||||
[formatter.python]
|
||||
command = "black"
|
||||
includes = ["*.py"]
|
||||
|
||||
# run shellcheck first
|
||||
[formatter.shellcheck]
|
||||
command = "shellcheck"
|
||||
includes = ["*.sh"]
|
||||
pipeline = "sh"
|
||||
priority = 0
|
||||
|
||||
# shfmt second
|
||||
[formatter.shfmt]
|
||||
command = "shfmt"
|
||||
options = ["-s", "-w"]
|
||||
includes = ["*.sh"]
|
||||
pipeline = "sh"
|
||||
priority = 1
|
||||
```
|
||||
|
||||
## Global Options
|
||||
|
||||
- `excludes` - an optional list of glob patters used to exclude certain files from all formatters.
|
||||
|
||||
## Formatter Options
|
||||
|
||||
- `command` - the command to invoke when applying the formatter.
|
||||
- `options` - an optional list of args to be passed to `command`.
|
||||
- `includes` - a list of glob patterns used to determine whether the formatter should be applied against a given path.
|
||||
- `excludes` - an optional list of glob patterns used to exclude certain files from this formatter.
|
||||
- `pipeline` - an optional key used to group related formatters together, ensuring they are executed sequentially
|
||||
against a given path.
|
||||
- `priority` - indicates the order of execution when this formatter is operating as part of a pipeline. Greater
|
||||
precedence is given to lower numbers, with the default being `0`.
|
||||
|
||||
> When two or more formatters in a pipeline have the same priority, they are executed in lexicographical order to
|
||||
> ensure deterministic behaviour over multiple executions.
|
||||
|
||||
## Supported Formatters
|
||||
|
||||
Here is a list of all the formatters we tested. Feel free to send a PR to add other ones!
|
||||
|
||||
### [prettier](https://prettier.io/)
|
||||
|
||||
An opinionated code formatter that supports many languages.
|
||||
|
||||
```toml
|
||||
command = "prettier"
|
||||
options = ["--write"]
|
||||
includes = [
|
||||
"*.css",
|
||||
"*.html",
|
||||
"*.js",
|
||||
"*.json",
|
||||
"*.jsx",
|
||||
"*.md",
|
||||
"*.mdx",
|
||||
"*.scss",
|
||||
"*.ts",
|
||||
"*.yaml",
|
||||
]
|
||||
```
|
||||
|
||||
### [Black](https://github.com/psf/black)
|
||||
|
||||
A python formatter.
|
||||
|
||||
```toml
|
||||
command = "black"
|
||||
includes = ["*.py"]
|
||||
```
|
||||
|
||||
### [clang-format](https://clang.llvm.org/docs/ClangFormat.html)
|
||||
|
||||
A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code.
|
||||
|
||||
```toml
|
||||
command = "clang-format"
|
||||
options = [ "-i" ]
|
||||
includes = [ "*.c", "*.cpp", "*.cc", "*.h", "*.hpp" ]
|
||||
```
|
||||
|
||||
Note: This example focuses on C/C++ but can be modified to use with other languages.
|
||||
|
||||
### Elm
|
||||
|
||||
```toml
|
||||
command = "elm-format"
|
||||
options = ["--yes"]
|
||||
includes = ["*.elm"]
|
||||
```
|
||||
|
||||
### Go
|
||||
|
||||
```toml
|
||||
command = "gofmt"
|
||||
options = ["-w"]
|
||||
includes = ["*.go"]
|
||||
```
|
||||
|
||||
### [Ormolu](https://github.com/tweag/ormolu)
|
||||
|
||||
Haskell formatter. Make sure to use ormolu 0.1.4.0+ as older versions don't
|
||||
adhere to the spec.
|
||||
|
||||
```toml
|
||||
command = "ormolu"
|
||||
options = [
|
||||
"--ghc-opt", "-XBangPatterns",
|
||||
"--ghc-opt", "-XPatternSynonyms",
|
||||
"--ghc-opt", "-XTypeApplications",
|
||||
"--mode", "inplace",
|
||||
"--check-idempotence",
|
||||
]
|
||||
includes = ["*.hs"]
|
||||
```
|
||||
|
||||
### [stylish-haskell](https://github.com/jaspervdj/stylish-haskell)
|
||||
|
||||
Another Haskell formatter.
|
||||
|
||||
```toml
|
||||
command = "stylish-haskell"
|
||||
options = [ "--inplace" ]
|
||||
includes = [ "*.hs" ]
|
||||
```
|
||||
|
||||
### [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt)
|
||||
|
||||
Nix code formatter.
|
||||
|
||||
```toml
|
||||
command = "nixpkgs-fmt"
|
||||
includes = ["*.nix"]
|
||||
```
|
||||
|
||||
### rustfmt
|
||||
|
||||
```toml
|
||||
command = "rustfmt"
|
||||
options = ["--edition", "2018"]
|
||||
includes = ["*.rs"]
|
||||
```
|
||||
|
||||
### [rufo](https://github.com/ruby-formatter/rufo)
|
||||
|
||||
Rufo is an opinionated ruby formatter. By default it exits with status 3 on
|
||||
file change so we have to pass the `-x` option.
|
||||
|
||||
```toml
|
||||
command = "rufo"
|
||||
options = ["-x"]
|
||||
includes = ["*.rb"]
|
||||
```
|
||||
|
||||
### cargo fmt
|
||||
|
||||
`cargo fmt` is not supported as it doesn't follow the spec. It doesn't allow
|
||||
to pass arbitrary files to be formatted, which treefmt relies on. Use `rustfmt`
|
||||
instead (which is what `cargo fmt` uses under the hood).
|
||||
|
||||
### [shfmt](https://github.com/mvdan/sh)
|
||||
|
||||
A shell code formatter.
|
||||
|
||||
```toml
|
||||
command = "shfmt"
|
||||
options = [
|
||||
"-i",
|
||||
"2", # indent 2
|
||||
"-s", # simplify the code
|
||||
"-w", # write back to the file
|
||||
]
|
||||
includes = ["*.sh"]
|
||||
```
|
||||
|
||||
### terraform
|
||||
|
||||
terraform fmt only supports formatting one file at the time. See
|
||||
https://github.com/hashicorp/terraform/pull/28191
|
@ -1,143 +0,0 @@
|
||||
# A list of known formatters
|
||||
|
||||
Here is a list of all the formatters we tested. Feel free to send a PR to add
|
||||
other ones!
|
||||
|
||||
## [prettier](https://prettier.io/)
|
||||
|
||||
An opinionated code formatter that supports many languages.
|
||||
|
||||
```toml
|
||||
command = "prettier"
|
||||
options = ["--write"]
|
||||
includes = [
|
||||
"*.css",
|
||||
"*.html",
|
||||
"*.js",
|
||||
"*.json",
|
||||
"*.jsx",
|
||||
"*.md",
|
||||
"*.mdx",
|
||||
"*.scss",
|
||||
"*.ts",
|
||||
"*.yaml",
|
||||
]
|
||||
```
|
||||
|
||||
## [Black](https://github.com/psf/black)
|
||||
|
||||
A python formatter.
|
||||
|
||||
```toml
|
||||
command = "black"
|
||||
includes = ["*.py"]
|
||||
```
|
||||
|
||||
## [clang-format](https://clang.llvm.org/docs/ClangFormat.html)
|
||||
|
||||
A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code.
|
||||
|
||||
```toml
|
||||
command = "clang-format"
|
||||
options = [ "-i" ]
|
||||
includes = [ "*.c", "*.cpp", "*.cc", "*.h", "*.hpp" ]
|
||||
```
|
||||
|
||||
Note: This example focuses on C/C++ but can be modified to use with other languages.
|
||||
|
||||
## Elm
|
||||
|
||||
```toml
|
||||
command = "elm-format"
|
||||
options = ["--yes"]
|
||||
includes = ["*.elm"]
|
||||
```
|
||||
|
||||
## Go
|
||||
|
||||
```toml
|
||||
command = "gofmt"
|
||||
options = ["-w"]
|
||||
includes = ["*.go"]
|
||||
```
|
||||
|
||||
## [Ormolu](https://github.com/tweag/ormolu)
|
||||
|
||||
Haskell formatter. Make sure to use ormolu 0.1.4.0+ as older versions don't
|
||||
adhere to the spec.
|
||||
|
||||
```toml
|
||||
command = "ormolu"
|
||||
options = [
|
||||
"--ghc-opt", "-XBangPatterns",
|
||||
"--ghc-opt", "-XPatternSynonyms",
|
||||
"--ghc-opt", "-XTypeApplications",
|
||||
"--mode", "inplace",
|
||||
"--check-idempotence",
|
||||
]
|
||||
includes = ["*.hs"]
|
||||
```
|
||||
|
||||
## [stylish-haskell](https://github.com/jaspervdj/stylish-haskell)
|
||||
|
||||
Another Haskell formatter.
|
||||
|
||||
```toml
|
||||
command = "stylish-haskell"
|
||||
options = [ "--inplace" ]
|
||||
includes = [ "*.hs" ]
|
||||
```
|
||||
|
||||
## [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt)
|
||||
|
||||
Nix code formatter.
|
||||
|
||||
```toml
|
||||
command = "nixpkgs-fmt"
|
||||
includes = ["*.nix"]
|
||||
```
|
||||
|
||||
## rustfmt
|
||||
|
||||
```toml
|
||||
command = "rustfmt"
|
||||
options = ["--edition", "2018"]
|
||||
includes = ["*.rs"]
|
||||
```
|
||||
|
||||
## [rufo](https://github.com/ruby-formatter/rufo)
|
||||
|
||||
Rufo is an opinionated ruby formatter. By default it exits with status 3 on
|
||||
file change so we have to pass the `-x` option.
|
||||
|
||||
```toml
|
||||
command = "rufo"
|
||||
options = ["-x"]
|
||||
includes = ["*.rb"]
|
||||
```
|
||||
|
||||
## cargo fmt
|
||||
|
||||
`cargo fmt` is not supported as it doesn't follow the spec. It doesn't allow
|
||||
to pass arbitrary files to be formatted, which treefmt relies on. Use `rustfmt`
|
||||
instead (which is what `cargo fmt` uses under the hood).
|
||||
|
||||
## [shfmt](https://github.com/mvdan/sh)
|
||||
|
||||
A shell code formatter.
|
||||
|
||||
```toml
|
||||
command = "shfmt"
|
||||
options = [
|
||||
"-i",
|
||||
"2", # indent 2
|
||||
"-s", # simplify the code
|
||||
"-w", # write back to the file
|
||||
]
|
||||
includes = ["*.sh"]
|
||||
```
|
||||
|
||||
## terraform
|
||||
|
||||
terraform fmt only supports formatting one file at the time. See
|
||||
https://github.com/hashicorp/terraform/pull/28191
|
75
docs/install.md
Normal file
75
docs/install.md
Normal file
@ -0,0 +1,75 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Install Treefmt
|
||||
|
||||
There are two ways to install `treefmt`:
|
||||
|
||||
1. Download the latest binary
|
||||
2. Compile and build from source.
|
||||
|
||||
## Download a binary file
|
||||
|
||||
You can download the latest `treefmt` binaries [here](https://github.com/numtide/treefmt-go/releases).
|
||||
|
||||
## Build from source
|
||||
|
||||
There are several ways to build `treefmt` from source. Your choice will depend on whether you're a [nix](https://github.com/NixOS/nix) user or
|
||||
not.
|
||||
|
||||
### Non-Nix User
|
||||
|
||||
To try the project without building it, run the following from the project root folder:
|
||||
|
||||
```
|
||||
$ go run main.go --help
|
||||
```
|
||||
|
||||
This 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 `go 1.22` installed. You can find instructions on how to install a `go` compiler
|
||||
[here](https://go.dev/doc/install).
|
||||
|
||||
To build the project, run the following:
|
||||
|
||||
```
|
||||
$ go build
|
||||
```
|
||||
|
||||
After the build command exits successfully, you will find the `treefmt` binary in the project root folder.
|
||||
|
||||
### Nix User
|
||||
|
||||
If you're using both `treefmt` and `nix`, you can make use of [`treefmt-nix`](https://github.com/numtide/treefmt-nix), a wrapper that makes installing and
|
||||
configuring `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`, run the following:
|
||||
|
||||
```
|
||||
$ nix-build -A packages.x86_64-linux.treefmt
|
||||
```
|
||||
|
||||
> note: substitute `x86_64-linux` for the target system you with to build for
|
||||
|
||||
**Nix-flake user**
|
||||
|
||||
If you want to use this repository with flakes, first ensure you have [flakes enabled](https://wiki.nixos.org/wiki/Flakes).
|
||||
You can then execute the following command in the project root folder:
|
||||
|
||||
```
|
||||
$ nix run . -- --help
|
||||
```
|
||||
|
||||
To build the project, run the following command in the project root folder:
|
||||
|
||||
```
|
||||
$ nix build
|
||||
```
|
||||
|
||||
The `treefmt` binary will be available in the `result` folder.
|
@ -1,71 +0,0 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
There are two options to install `treefmt`:
|
||||
|
||||
1. Downloading the latest binary
|
||||
2. Compiling and building it from source.
|
||||
|
||||
## Installing with a binary file
|
||||
|
||||
You can find the list of the latest binaries [here](https://github.com/numtide/treefmt-go/releases).
|
||||
|
||||
## Building from source
|
||||
|
||||
There are several ways to build `treefmt` from source. Your choice will depend on whether you're a [nix](https://github.com/NixOS/nix) user or
|
||||
not.
|
||||
|
||||
### Non-Nix User
|
||||
|
||||
To try the project without building it, run:
|
||||
|
||||
```
|
||||
$ go run main.go --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 `go 1.22` installed. You can find instructions [here](https://go.dev/doc/install).
|
||||
|
||||
Now, if you want to build the project, switch to the project root folder and run:
|
||||
|
||||
```
|
||||
$ go build
|
||||
```
|
||||
|
||||
After the successful execution of the build command, you will find the `treefmt` binary in the project root folder.
|
||||
|
||||
### Nix User
|
||||
|
||||
If you're using both `treefmt` and `nix`, you can go for [`treefmt-nix`](https://github.com/numtide/treefmt-nix), a wrapper 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.
|
4
docs/package-lock.json
generated
4
docs/package-lock.json
generated
@ -1,11 +1,11 @@
|
||||
{
|
||||
"name": "Treefmt Docs",
|
||||
"name": "treefmt-docs",
|
||||
"version": "0.0.1",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "Treefmt Docs",
|
||||
"name": "treefmt-docs",
|
||||
"version": "0.0.1",
|
||||
"devDependencies": {
|
||||
"vitepress": "^1.1.4"
|
||||
|
@ -4,15 +4,14 @@ outline: none
|
||||
|
||||
# Quick start
|
||||
|
||||
To run `treefmt` in your project, please follow these steps:
|
||||
To run `treefmt` in your project, follow these steps:
|
||||
|
||||
1. [Install] `treefmt`.
|
||||
2. Install any formatters you wish to use with `treefmt`.
|
||||
2. Ensure any formatters you wish to use are also installed e.g. `gofmt`
|
||||
3. Run `treefmt --init` to generate a basic configuration file `treefmt.toml`.
|
||||
4. Edit the configuration, adding formatters as desired. See [here] for more info on how to configure a formatter.
|
||||
5. Run `treefmt` with the needed flags and options. You can check the supported options by executing `treefmt --help`.
|
||||
4. Edit `treefmt.toml`, [configuring] formatters as desired.
|
||||
5. Run `treefmt` with the needed [flags & options].
|
||||
|
||||
In the following sections we will guide you through installing and configuring `treefmt` in detail.
|
||||
|
||||
[install]: installation.md
|
||||
[here]: formatter-spec.md
|
||||
[install]: install
|
||||
[configuring]: configure
|
||||
[flags & options]: usage
|
||||
|
183
docs/usage.md
183
docs/usage.md
@ -1,94 +1,113 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Usage
|
||||
|
||||
You can run treefmt by executing:
|
||||
|
||||
`$ treefmt`
|
||||
|
||||
or, if it's not in your `$PATH`:
|
||||
|
||||
`$ ./treefmt`
|
||||
|
||||
Treefmt has the following specification:
|
||||
`treefmt` has the following specification:
|
||||
|
||||
```
|
||||
treefmt [FLAGS] [OPTIONS] [--] [paths]...
|
||||
Usage: treefmt [<paths> ...] [flags]
|
||||
|
||||
Arguments:
|
||||
[<paths> ...] Paths to format. Defaults to formatting the whole tree.
|
||||
|
||||
Flags:
|
||||
-h, --help Show context-sensitive help.
|
||||
--allow-missing-formatter Do not exit with error if a configured formatter is missing.
|
||||
-C, --working-directory="." Run as if treefmt was started in the specified working directory instead of the current working directory.
|
||||
--no-cache Ignore the evaluation cache entirely. Useful for CI.
|
||||
-c, --clear-cache Reset the evaluation cache. Use in case the cache is not precise enough.
|
||||
--config-file="./treefmt.toml" The config file to use.
|
||||
--fail-on-change Exit with error if any changes were made. Useful for CI.
|
||||
--formatters=FORMATTERS,... Specify formatters to apply. Defaults to all formatters.
|
||||
--tree-root="." The root directory from which treefmt will start walking the filesystem.
|
||||
--walk="auto" The method used to traverse the files within --tree-root. Currently supports 'auto', 'git' or 'filesystem'.
|
||||
-v, --verbose Set the verbosity of logs e.g. -vv ($LOG_LEVEL).
|
||||
-V, --version Print version.
|
||||
-i, --init Create a new treefmt.toml.
|
||||
--stdin Format the context passed in via stdin.
|
||||
--cpu-profile=STRING The file into which a cpu profile will be written.
|
||||
```
|
||||
|
||||
## Flags
|
||||
|
||||
`--walk <auto|git|filesystem>`
|
||||
|
||||
> The method used to traverse the files within `<tree-root>`.
|
||||
> Default is `auto`, where we will detect if the `<tree-root>` is a git repository and use the `git` walker for
|
||||
> traversal. If not we will fall back to the `filesystem` walker.
|
||||
|
||||
`--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 <config-file>`
|
||||
|
||||
> Run with the specified config file which is not in the project tree.
|
||||
|
||||
`-f, --formatters <formatters>...`
|
||||
|
||||
> Only apply selected formatters. Defaults to all formatters.
|
||||
|
||||
`--tree-root <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’s mostly useful in combination with `--config-file` to specify the project root which won’t coincide with the directory holding `treefmt.toml`.
|
||||
|
||||
`-C <work-dir>`
|
||||
|
||||
> Run as if `treefmt` was started in `<work-dir>` instead of the current working directory (default: `.`). Equivalent to `cd <work dir>; treefmt`.
|
||||
|
||||
## Arguments
|
||||
|
||||
`<paths>...`
|
||||
### `[<paths> ...]`
|
||||
|
||||
> Paths to format. Defaults to formatting the whole tree
|
||||
Paths to format. Defaults to formatting the whole tree
|
||||
|
||||
## Flags
|
||||
|
||||
### `-h, --help`
|
||||
|
||||
Prints available flags and options
|
||||
|
||||
### `--allow-missing-formatter`
|
||||
|
||||
Do not exit with an error if some of the configured formatters are missing.
|
||||
|
||||
### `-C, --working-directory="."`
|
||||
|
||||
Run as if `treefmt` was started in the specified working directory instead of the current working directory
|
||||
|
||||
### `--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
|
||||
CI is starting with a fresh environment each time, so any calculated cache is lost.
|
||||
|
||||
The `--no-cache` flag eliminates unnecessary work in CI.
|
||||
|
||||
### `--config-file <config-file>`
|
||||
|
||||
Run with the specified config file.
|
||||
|
||||
### `--fail-on-change`
|
||||
|
||||
Exit with error if any changes were made.
|
||||
|
||||
This is useful for CI if you want to detect if someone forgot to format their code.
|
||||
|
||||
### `-f, --formatters <formatters>...`
|
||||
|
||||
Specify formatters to apply. Defaults to all formatters.
|
||||
|
||||
### `--tree-root="."`
|
||||
|
||||
The root directory from which `treefmt` will start walking the filesystem.
|
||||
|
||||
### `--walk <auto|git|filesystem>`
|
||||
|
||||
The method used to traverse the files within `--tree-root`. Currently supports `auto`, `git` or `filesystem`.
|
||||
|
||||
Default is `auto`, where we will detect if the `<tree-root>` is a git repository and use the `git` walker for
|
||||
traversal. If not we will fall back to the `filesystem` walker.
|
||||
|
||||
### `-v, --verbose`
|
||||
|
||||
Set the verbosity of logs e.g. `-vv`. Can also be set with an integer value in an env variable `$LOG_LEVEL`.
|
||||
|
||||
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.
|
||||
|
||||
### `--init`
|
||||
|
||||
Create a new `treefmt.toml`.
|
||||
|
||||
### `--stdin`
|
||||
|
||||
Format the content passed in via stdin.
|
||||
|
||||
### `-V, --version`
|
||||
|
||||
Print version.
|
||||
|
||||
## CI integration
|
||||
|
||||
Typically, you would use treefmt in the CI with the `--fail-on-change` and `--no-cache flags`. Find the explanations above.
|
||||
Typically, you would use `treefmt` in CI with the `--fail-on-change` and `--no-cache flags`.
|
||||
|
||||
You can you set a `treefmt` job in the GitHub pipeline for Ubuntu with nix-shell like this:
|
||||
You can configure a `treefmt` job in a GitHub pipeline for Ubuntu with `nix-shell` like this:
|
||||
|
||||
```yaml
|
||||
name: treefmt
|
||||
@ -100,14 +119,14 @@ jobs:
|
||||
formatter:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v1
|
||||
- uses: cachix/install-nix-action@v12
|
||||
- uses: actions/checkout@v4
|
||||
- uses: cachix/install-nix-action@v26
|
||||
with:
|
||||
nix_path: nixpkgs=channel:nixos-unstable
|
||||
- uses: cachix/cachix-action@v10
|
||||
- uses: cachix/cachix-action@v14
|
||||
with:
|
||||
name: nix-community
|
||||
authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
|
||||
- name: treefmt
|
||||
run: nix-shell --run "treefmt --fail-on-change --no-cache"
|
||||
run: nix-shell -p treefmt --run "treefmt --fail-on-change --no-cache"
|
||||
```
|
||||
|
@ -9,7 +9,7 @@ _: {
|
||||
inherit (self'.packages.default) version;
|
||||
|
||||
src = ../docs;
|
||||
npmDepsHash = "sha256-J9qTWueOcSBq7qRec6YdTuWI2VlVQ0q6AynDLovf6s0=";
|
||||
npmDepsHash = "sha256-vHxJHuhvQJ0P4wS1Hd2BIfPMSptnLhuHGLXCO+P5iFs=";
|
||||
|
||||
# we have to use a custom build phase because vitepress is doing something funky with the ttty
|
||||
buildPhase = ''
|
||||
|
Loading…
Reference in New Issue
Block a user