README
¶
gotools
A wrapper around go get -tool with added ergonomics like dependency isolation, deterministic sync, managed execution, and
CI-friendly diagnostics.
But why?
Installing tools straight into your project's go.mod pollutes the dependency graph with tool-only dependencies. gotools
keeps tool dependencies isolated behind three strategies. See Strategies for more details.
⚠️ Tools are compiled locally from source (
go get -tool) — read the risks and recommendations before committing to a strategy.
Requirements
- Your projects need Go 1.24 or higher. Go 1.24 is the first release with
tooldirectives andgo tool, which is what gotools manages; earlier Go versions cannot run tools this way. - Building gotools from source needs Go 1.27. Pre-built binaries need only the Go you already have.
Install
go install github.com/piusalfred/gotools/cmd/gotools@latest
For more installation options, See Installation options.
Quick Start
# Bootstrap with the default split strategy
gotools init
# Install some tools
gotools install github.com/google/addlicense
gotools install golangci-lint \
github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.11.4
# Run a tool
gotools exec addlicense -l mit -c "Your Name" .
gotools exec golangci-lint run ./...
# List all managed tools
gotools list
Run gotools help for the full command reference. You can also check out the USAGE documentation for more examples and details.
Features
| Three Isolation Strategies | Choose between split (default), module (safest), or unified (simplest). |
| Go Version Parity | Tool environments automatically sync to the Go version defined in your project's root go.mod. |
| Seamless Migration | Move between strategies dynamically with the migrate command without losing your pinned versions. |
| Auto-Migration on Sync | If the tools directory structure doesn't match .gotools.json, sync detects the mismatch and migrates automatically. |
| Reproducibility | Commit the tools/ directory to guarantee environment parity across teams and CI. |
| Self-Update | Update gotools itself with a single command. |
Documentation
The documentation index says which page to read for what. All of them:
| Doc | Contents |
|---|---|
| USAGE | Command reference, examples, risks, doctor, JSON output, shell completions, cleanup, exit codes |
| INSTALLATION | All installation methods: go install, pre-built binaries, curl installer, self-update, version pinning |
| DOCKER | The ghcr.io/piusalfred/gotools image: running it, the cache volume, dev containers, CI |
| STRATEGIES | The three isolation strategies compared |
| MIGRATION | Moving between strategies |
| CONFIGURATION | The .gotools.json manifest, schema versioning, module prefix |
| CI | CI integration, version guard, offline mode, locking and timeouts, pre-commit |
| SECURITY | Trust model, what checksum verification does and does not prove, module verification warnings |
| DEVELOPMENT | Source layout, building, testing, releases (for contributors) |
| TODOLIST | Open, decided and finished work, with status and notes |
License
MIT — Copyright (c) 2026 Pius Alfred
Documentation
¶
Overview ¶
Package gotools manages Go build tools with `tool` directives. The program is cmd/gotools; the implementation lives in the packages under internal (one self-standing package per concern, and internal/command with one file per command).
The version lives in version.txt at the module root, the one place the Makefile, the Version Guard workflow and the release workflow read it from, and is embedded in the binary.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gotools
command
Command gotools manages Go build tools with `tool` directives, keeping their dependencies out of your project's module graph.
|
Command gotools manages Go build tools with `tool` directives, keeping their dependencies out of your project's module graph. |
|
internal
|
|
|
cli
Package cli is the gotools command line on urfave/cli v3: an App with one entry point, Run(ctx, args), that serves the commands declared in package command.
|
Package cli is the gotools command line on urfave/cli v3: an App with one entry point, Run(ctx, args), that serves the commands declared in package command. |
|
command
Package command holds the gotools commands.
|
Package command holds the gotools commands. |
|
config
Package config resolves gotools' configuration.
|
Package config resolves gotools' configuration. |
|
doctor
Package doctor diagnoses a gotools environment: the Go installation, the module proxy, the manifest, each managed tool, the lock, module integrity and disk use.
|
Package doctor diagnoses a gotools environment: the Go installation, the module proxy, the manifest, each managed tool, the lock, module integrity and disk use. |
|
errors
Package errors is the exit-code contract shared by gotools packages: an error that carries the process exit code and the message for stderr.
|
Package errors is the exit-code contract shared by gotools packages: an error that carries the process exit code and the message for stderr. |
|
fingerprint
Package fingerprint records the state a sync reconciled, so the next sync can tell whether anything changed.
|
Package fingerprint records the state a sync reconciled, so the next sync can tell whether anything changed. |
|
format
Package format renders what a command reports as text or JSON.
|
Package format renders what a command reports as text or JSON. |
|
fsx
Package fsx holds the file operations gotools needs to keep a project safe: writes that are never half done, and a refusal to follow symlinks.
|
Package fsx holds the file operations gotools needs to keep a project safe: writes that are never half done, and a refusal to follow symlinks. |
|
gocmd
Package gocmd runs the go command.
|
Package gocmd runs the go command. |
|
goversion
Package goversion answers questions about the Go toolchain: whether it is new enough, and which Go version a tool's modfile should declare.
|
Package goversion answers questions about the Go toolchain: whether it is new enough, and which Go version a tool's modfile should declare. |
|
lock
Package lock excludes other processes from a directory with an flock(2) advisory lock.
|
Package lock excludes other processes from a directory with an flock(2) advisory lock. |
|
manifest
Package manifest reads and writes .gotools.json: the layout, the settings and the list of managed tools.
|
Package manifest reads and writes .gotools.json: the layout, the settings and the list of managed tools. |
|
modparser
Package modparser reads and edits go.mod files on golang.org/x/mod/modfile.
|
Package modparser reads and edits go.mod files on golang.org/x/mod/modfile. |
|
resolve
Package resolve finds the tool a name stands for and asks go whether it can run.
|
Package resolve finds the tool a name stands for and asks go whether it can run. |
|
selfupdate
Package selfupdate replaces the running gotools binary with the newest release for this operating system and architecture.
|
Package selfupdate replaces the running gotools binary with the newest release for this operating system and architecture. |
|
strategy
Package strategy is the tool-isolation strategy: which files hold a tool's go.mod and go.sum, and which strategies a tools directory already uses.
|
Package strategy is the tool-isolation strategy: which files hold a tool's go.mod and go.sum, and which strategies a tools directory already uses. |
|
tools
Package tools changes which tools a project manages.
|
Package tools changes which tools a project manages. |
|
tracer
Package tracer records finished tool invocations as JSON Lines.
|
Package tracer records finished tool invocations as JSON Lines. |
|
verify
Package verify reports Go settings that weaken module verification.
|
Package verify reports Go settings that weaken module verification. |
Click to show internal directories.
Click to hide internal directories.