go.mod and the Module Graph

## What go.mod holds A Go module is a tree of packages with a `go.mod` file at its root. That file declares the **module path** on its `module` line (the import-path prefix for every package inside the module), a `go` line, sometimes a `toolchain` line, and one or more `require` blocks. Each `require` line names another module and the **minimum version** of it this module needs. Nothing in the compiler keeps that list honest. You can delete an import from a `.go` file and the stale `require` line stays; you can add an import and the file has no requirement for it. `go mod tidy` is the command that reconciles the two. ## What tidy actually does It loads the packages of the main module, resolves every import, and then: - **Adds** a `require` line for any module that provides a package you import but that is not required yet. If it has to invent a version, it takes the latest release of that module. - **Removes** any `require` line for a module that no longer provides a package needed to build any package or test in the main module. - **Maintains `// indirect`.** A require gets that comment when no package in your own module imports anything from it; the comment is removed when your code starts importing it directly. - **Syncs `go.sum`**, adding the hashes needed for the resulting build and deleting entries nothing refers to any more. "Every package" is broader than what a single `go build` sees. Tidy considers the packages of the main module for **all build tags and all target platforms**, and it considers the **test** imports of those packages. Since Go 1.24 it also keeps the modules named by `tool` directives in go.mod, which is how executable dependencies are recorded. That breadth is why tidy sometimes keeps a module you cannot find an import for on your own machine — the import is behind a build constraint for another GOOS, or it is in a `_test.go` file. ## What tidy does not do - It **does not upgrade**. If go.mod already requires a module at some version, tidy leaves that version alone; getting newer versions is a separate, deliberate action. - It **does not** rewrite `replace` or `exclude` lines you wrote by hand. - It **does not** tell you *why* something is kept. When a removal or a retention surprises you, `go mod why -m <module>` prints the chain from a package in your module to that module, and `(main module does not need module …)` when nothing reaches it. ## Reading a tidy diff Because tidy is deterministic for a given code base and Go version, its diff is meaningful in review: - a line **added without `// indirect`** means your code now imports something new — a real dependency your team has taken on; - a line **losing** `// indirect` means code that used to reach a module transitively now imports it directly; - a line **removed** means nothing in the module reaches it any more, which should normally line up with an import disappearing in the same pull request. In Go 1.27, `go mod tidy` writes modules whose `go` line is 1.27 or later using a **two-block require layout**: direct requirements in one `require` block, indirect ones in a second. Older layouts stay valid; the split just makes the direct/indirect distinction obvious at a glance. ## In practice The habit that avoids trouble is: change imports, run `go mod tidy`, run the tests, commit go.mod and go.sum **in the same commit as the code**. The CI check is the enforcement — a job that runs `go mod tidy` with the repository's Go version and fails if the working tree changed. That turns "did someone forget to tidy?" from a review judgment into a build result, and it keeps the require block a trustworthy statement of what the module depends on.