1# mise
2
3Use `mise.toml` as the project task runner and tool installer. Translate older
4Taskfile/justfile commands into mise instead of preserving the old runner by
5default.
6
7## Baseline Go `mise.toml`
8
9Adapt names and paths, but keep the shape recognisable:
10
11```toml
12min_version = "2026.2.4"
13
14[env]
15GOAMD64 = "v3"
16
17[vars]
18test_args = "-v -race -count=5 -p=3 -timeout=5m ./..."
19
20[tools]
21go = "latest"
22"go:golang.org/x/vuln/cmd/govulncheck" = "latest"
23golangci-lint = "latest"
24
25[tasks.fmt]
26description = "Format Go code"
27run = "golangci-lint fmt"
28
29[tasks.tidy]
30description = "Tidy go.mod and go.sum"
31run = "go mod tidy"
32
33[tasks.modernize]
34description = "Apply Go modernization fixes"
35run = "golangci-lint run --enable-only modernize --fix ./..."
36
37[tasks.lint]
38description = "Lint Go code and apply safe fixes"
39run = "golangci-lint run --fix"
40
41[tasks.fix]
42description = "Format, modernize, and apply lint fixes"
43run = [
44 "mise run fmt",
45 "mise run modernize",
46 "mise run lint",
47]
48
49[tasks.vet]
50description = "Run go vet"
51run = "go vet ./..."
52
53[tasks.vuln]
54description = "Run govulncheck"
55run = "govulncheck ./..."
56
57[tasks.build]
58description = "Build all Go packages"
59run = "go build ./..."
60
61[tasks.test]
62description = "Run Go tests repeatedly with the race detector"
63env = { CGO_ENABLED = "1" }
64run = "go test {{vars.test_args}}"
65
66[tasks."test:quiet"]
67description = "Run Go tests with quiet success output"
68env = { CGO_ENABLED = "1" }
69run = '''
70if output=$(go test {{vars.test_args}} 2>&1); then
71 echo "✓"
72else
73 echo "$output"
74 exit 1
75fi
76'''
77
78[tasks.check]
79description = "Format, tidy, lint, scan, build, and test"
80run = [
81 "mise run fix",
82 "mise run tidy",
83 "mise run vet",
84 "mise run vuln",
85 "mise run build",
86 "mise run test:quiet",
87]
88```
89
90`GOAMD64=v3` is Amolith's personal/performance baseline. Lower or remove it for
91public binaries that need broad x86-64 compatibility.
92
93Do not add a non-mutating tidy check unless the user asks for it. `tidy` is the
94task.
95
96## Binary projects
97
98For a user-facing binary, make build/install tasks target the actual command:
99
100```toml
101[vars]
102binary = "example"
103main = "./cmd/example"
104static_tags = "netgo,osusergo,static_build"
105static_ldflags = "-d -s -w -buildid= -extldflags=-static"
106
107[tasks.build]
108description = "Build a static pure-Go binary"
109env = { CGO_ENABLED = "0" }
110run = '''
111go build \
112 -trimpath \
113 -tags '{{vars.static_tags}}' \
114 -ldflags '{{vars.static_ldflags}}' \
115 -o {{vars.binary}} \
116 {{vars.main}}
117'''
118
119[tasks.install]
120description = "Install a static pure-Go binary"
121env = { CGO_ENABLED = "0" }
122run = '''
123go install \
124 -trimpath \
125 -tags '{{vars.static_tags}}' \
126 -ldflags '{{vars.static_ldflags}}' \
127 {{vars.main}}
128'''
129```
130
131Do not settle version policy by copying the static template. The template leaves
132`-buildvcs` unspecified, so Go uses its `auto` behavior. For version reporting,
133those fields matter only if project code or Fang reads them; they can still
134matter for reproducibility or privacy, so choose `-buildvcs` explicitly when
135that matters. Choose the policy with the user:
136
137- **Best-effort local/dev metadata**: leave `-buildvcs` unset and read
138 `runtime/debug.BuildInfo` or Fang's fallback when `unknown` is acceptable.
139- **Release/package/user-visible version**: derive an exact semver or commit in
140 the task and inject it with `-ldflags -X ...`.
141- **jj-derived versions or multiple version surfaces**: keep a project-owned
142 resolver and pass the values to Fang, server metadata, package metadata, and
143 tests.
144- **Reproducible or privacy-sensitive builds**: consider `-buildvcs=false`, but
145 document the tradeoff. If a release task relies on Go VCS metadata, consider
146 `-buildvcs=true` so missing metadata fails loudly.
147
148The static template is for pure-Go binaries. It will not work for Wails, race
149tests, or projects that require CGO, native keychains, WebKitGTK, or C-backed
150database drivers.
151
152`netgo` forces the pure-Go DNS resolver. `osusergo` forces pure-Go user/group
153lookup. `static_build` is only a project convention unless files or dependencies
154use that build tag. `-extldflags=-static` asks the external linker for static C
155libraries when external linking is involved; it is not a magic fix for CGO.
156
157## Optional pprof tasks
158
159Add these only when the project intentionally exposes `net/http/pprof`, usually
160on localhost and behind an explicit debug flag:
161
162```toml
163[tasks."profile:cpu"]
164run = "go tool pprof -http :6061 'http://127.0.0.1:6060/debug/pprof/profile?seconds=15'"
165
166[tasks."profile:heap"]
167run = "go tool pprof -http :6061 'http://127.0.0.1:6060/debug/pprof/heap'"
168
169[tasks."profile:allocs"]
170run = "go tool pprof -http :6061 'http://127.0.0.1:6060/debug/pprof/allocs'"
171```
172
173## Frontend or Wails projects
174
175Add only the tools the project needs. For Wails, see `wails.md`; for light web
176apps, see `web.md`. Keep frontend package manager choice project-specific: use
177the existing lockfile, or ask before introducing npm, Bun, pnpm, or yarn.