What does go.mod's `tool` directive do, and how does it stop tool-version drift between laptops and CI?

## The problem: tools that live outside the module A Go repository's build usually runs a few programs that are not the compiler: a code generator, a formatter variant, a schema or mock producer. Historically these were not part of the module at all. Each engineer obtained a binary and put it on `PATH`; CI obtained one in its setup step. Nothing recorded which build any of them was, so the same command produced different bytes on different machines. The symptom is not a compile error, it is a **check that is green on the laptop and red in the pipeline**: the formatting or generation step produces output the other environment did not produce, and the diff is blamed on the author who happened to push. The long-standing workaround was a `tools.go` file: a file excluded from normal builds by a build constraint, containing blank imports of the tool packages. Because they were imports, `go mod tidy` kept the corresponding modules in `go.mod` and their exact versions in `go.sum`, so the version was at least *recorded*. It was a trick — a file that exists to lie to the dependency graph — and it still did not give you a command that ran the pinned build. ## What the `tool` directive is Go 1.24 made it first class. `go.mod` gained a `tool` directive naming a **package path** whose package is a `main` package: ``` module example.com/svc go 1.24 tool golang.org/x/tools/cmd/goimports ``` You do not usually type it: `go get -tool golang.org/x/tools/cmd/goimports` adds the `tool` line and the matching `require` on the providing module, and records its hashes in `go.sum`. The version is then resolved exactly like every other dependency version in the module graph, with the same review trail — an upgrade is a diff in `go.mod`, not an undocumented change on somebody's machine. ## Running it `go tool <name>` runs it, where `<name>` is the last element of the package path. The go command builds the tool from the pinned source if it is not already in the build cache, then executes it, forwarding the arguments. `go tool` with no arguments lists the available tools: the ones shipped with the toolchain, plus the ones this module declares. That last part is what makes the directive useful in a check script — the script says `go tool thing -flag`, and it means the same build for every caller, with no setup step to keep in sync and nothing to add to `PATH`. ## What it pins and what it does not Be precise about the boundary, because it is where the remaining drift hides. - It pins the tool's **source version**. Two machines build the same code. - It does **not** pin the Go toolchain that compiles that source, and it does not pin the toolchain that formats or vets your own code. If the pipeline runs one Go release and the laptop runs another, output can still differ — most visibly for anything that emits formatted Go, because the formatter's output has changed across releases (Go 1.19's doc-comment reformatting is the well-known case). Pinning the tool and letting the Go version float only halves the problem. - It does not sandbox the tool. A tool that reads the environment, the clock, or the network can still produce machine-dependent output. ## The tradeoff worth naming The tool's dependencies become part of your main module's requirement graph. That is what makes a single, consistent resolution possible, and it is also the cost: a tool with a large dependency tree adds lines to `go.mod`, participates in version selection with your own requirements, and can pull your build list forward. For a tool used by exactly one repository this is fine and the bookkeeping is worth it. For a large tool shared across many repositories, some teams prefer to keep it out of the graph and pin it another way — and that is a genuine judgment call, not an oversight. ## What to say in an interview The short version: tools used by the build are dependencies, and dependencies belong in `go.mod` where they are versioned, hashed, reviewed and reproducible. The `tool` directive plus `go tool` is the toolchain's own answer to that, the `tools.go` blank-import file is the older answer, and an ambient binary on `PATH` is no answer at all.