How does go generate work, and what are best practices around it?

go generate scans source files for //go:generate command args lines (no space after //) and runs the commands with the package directory as the working directory. It is never run by go build or go test. It is a manual, author-side step, and the generated files are committed so that consumers can go get without the tools.

package color

//go:generate go tool stringer -type=Color -trimprefix=Color
//go:generate go run ./gen -out=table_gen.go

type Color int

const (
    ColorRed Color = iota
    ColorGreen
)

Available environment variables: $GOFILE, $GOPACKAGE, $GOLINE, $GOARCH, $GOOS, $DOLLAR. Commands run in the order they appear in files, and files are processed in sorted order. Useful flags are -run regexp and -n/-x.

Best practices:

• Generated files should start with // Code generated ... DO NOT EDIT., which linters, gopls and code review tools recognize.
• Pin generator versions (with the tool directive or go run pkg@v).
• In CI, run go generate ./... && git diff --exit-code to catch stale output.
• Consider generics before code generation. Many stringer/mock/collection use cases no longer need it.