Skip to content

Commit

Permalink
doc: refine docs and usage
Browse files Browse the repository at this point in the history
Signed-off-by: Brian McGee <[email protected]>
  • Loading branch information
brianmcgee committed May 10, 2024
1 parent e5a6cc6 commit e5da10e
Show file tree
Hide file tree
Showing 14 changed files with 415 additions and 334 deletions.
46 changes: 23 additions & 23 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,30 +1,30 @@
name: goreleaser

on:
pull_request:
push:
# run only against tags
tags:
- "v*"
pull_request:
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}}
32 changes: 16 additions & 16 deletions .goreleaser.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 10 additions & 10 deletions cli/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
2 changes: 1 addition & 1 deletion config/formatter.go
Original file line number Diff line number Diff line change
@@ -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
Expand Down
9 changes: 5 additions & 4 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
],
Expand Down
6 changes: 3 additions & 3 deletions docs/overview.md → docs/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 201 additions & 0 deletions docs/configure.md
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit e5da10e

Please sign in to comment.