go clean — Specification¶

Focus: Precise reference for go clean — synopsis, flags, what each removes, environment, exit codes, and guarantees.

Sources: - go help clean - Build and test caching: https://pkg.go.dev/cmd/go#hdr-Build_and_test_caching - Module cache: https://go.dev/ref/mod#module-cache

1. Synopsis¶

go clean [clean flags] [build flags] [packages]

Removes object files and cached files generated by the Go tools. With cache flags, removes the global build/test/module/fuzz caches.

2. Flags¶

Flag	Removes / effect
(none)	Build outputs left in the named packages' source directories (executable, `_test`/`_obj` leftovers, profiling files)
`-i`	Also the installed binary or archive for the named packages
`-r`	Apply recursively to all dependencies of the named packages
`-cache`	The entire build cache (`GOCACHE`)
`-testcache`	Expire all cached test results (future identical runs re-execute)
`-modcache`	The entire module download cache (`GOMODCACHE`), handling read-only files
`-fuzzcache`	Generated fuzz corpus entries in the cache (not committed `testdata/fuzz` seeds)
`-n`	Print the remove commands without executing them
`-x`	Print the remove commands as they execute

Cache flags operate globally and ignore the package arguments.

3. What each cache is¶

Cache	Location (default)	Contents
Build cache	`GOCACHE` (`~/.cache/go-build` on Linux)	Compiled package objects, action results, cached test results
Module cache	`GOMODCACHE` (`$GOPATH/pkg/mod`)	Downloaded dependency source (read-only)
Fuzz cache	within `GOCACHE`'s fuzz subtree	Generated fuzz corpus

go env GOCACHE GOMODCACHE

4. Environment variables¶

Variable	Role
`GOCACHE`	Build cache location (`go clean -cache`, `-testcache`, `-fuzzcache`)
`GOMODCACHE`	Module cache location (`go clean -modcache`)
`GOPATH`	Default base for `GOMODCACHE` and installed binaries
`GOFLAGS`	Default flags applied to `go` commands

Setting GOCACHE=off disables the build cache (builds do not cache); go clean -cache then has nothing to remove.

5. Exit codes¶

Situation	Exit
Success	0
I/O/permission error removing files	non-zero, error to stderr
Invalid flags	2

6. Behavioral guarantees¶

Correct permission handling. go clean -modcache removes read-only module cache files that rm would fail on.
-testcache expires, not deletes arbitrarily. It marks results so future identical runs re-execute.
-fuzzcache preserves seeds. Only generated corpus is removed; testdata/fuzz source files are untouched.
Cache flags are global. They ignore package arguments.
Build cache is content-addressed. Cleaning is for disk reclamation/corruption recovery, not for fixing stale results (which cannot occur).

7. Relationship to other commands¶

Goal	Command
Re-run tests once, ignore cache	`go test -count=1`
Re-run all tests fresh going forward	`go clean -testcache`
Reclaim dependency disk	`go clean -modcache`
Cold rebuild	`go clean -cache && go build ./...`
Re-download deps	`go mod download` (after `-modcache`)
Verify integrity	`go mod verify`

Build and test caching: https://pkg.go.dev/cmd/go#hdr-Build_and_test_caching
Module cache: https://go.dev/ref/mod#module-cache
go help clean, go help environment