How does the GOFLAGS environment variable change what `go build` and `go test` do?

## What it is `GOFLAGS` is an environment variable read by the `go` command itself. Its value is a **space-separated list of standalone flag settings**, each written as `-flag` or `-flag=value`. Before running a subcommand, the `go` command applies each entry that the subcommand recognises, then applies whatever was written on the command line — so an explicit flag overrides the same flag from `GOFLAGS`. Two consequences of the format matter in practice: - **Each entry must be standalone.** `-tags integration` as two words is wrong; `-tags=integration` is right, because the list is split on spaces. - **Values cannot contain spaces**, for the same reason. A flag whose value is a multi-word string cannot be expressed here. And one consequence of the "known to the current command" rule: a flag meaningful to `go build` does not break `go list` or `go env`, which simply ignore it. ## Why anyone reaches for it The honest use case is applying a build-shaping flag uniformly without touching every invocation. `-trimpath` is the canonical example: you want every artefact this machine produces to be path-free, and you do not want to rely on every script, every Makefile target and every developer remembering the flag. Setting it once means the tenth build script written next year is trimmed too. ``` $ go env -w GOFLAGS=-trimpath $ go env GOFLAGS -trimpath ``` `go env -w` writes the setting into the `go` command's own environment configuration file rather than into your shell profile, so it survives new shells and applies to every Go project on the machine. `go env -u GOFLAGS` removes it again. ## Why it is also a trap Everything good about `GOFLAGS` — invisible, persistent, machine-wide — is what makes it a debugging hazard. 1. **It does not appear in the command that was run.** A build log showing `go build ./...` tells you nothing about the flags actually in effect. When a colleague's build behaves differently from yours and the commands match, `go env GOFLAGS` on both machines is the first comparison to make. 2. **It changes build cache keys.** Build flags are part of the key, so a machine with `GOFLAGS=-trimpath` and a machine without it populate different cache entries for the same packages. In a shared or persisted cache this shows up as a mysteriously low hit rate rather than as an error. 3. **It is machine-wide.** `go env -w` is not scoped to a project. A flag set for one repository silently applies to every other repository on that machine, which is how a setting adopted for a good reason in one place becomes an unexplained difference in another. 4. **It survives the person who set it.** A laptop configured two years ago carries the setting into every new checkout; nothing in the repository records that it exists. ## Using it responsibly The practical rule is that `GOFLAGS` should carry only settings you would be happy to apply to *every* Go build on the machine, and that anything load-bearing for a release should also be written explicitly where the release is produced. Belt and braces: the flag is in `GOFLAGS` so nobody forgets it, and spelled out in the release command so the log proves it was used. Anything narrower — a flag that matters for one repository, one target, one job — belongs in that repository's build script, where a reader can see it. When a build produces something surprising and the command line looks innocent, the checklist is short: `go env GOFLAGS`, `go env GOOS GOARCH CGO_ENABLED`, and the toolchain version. The environment is part of the build inputs whether or not anyone wrote it down.