Go Reference ยท The go Command and Tools
The go generate command
Reference for go generate: //go:generate directives, environment variables like $GOFILE, flags -run -n -v -x, writing generators and committing output.
go generate runs commands that are written inside your source files as special comments. Its job is to produce Go code (or other files) before the build: string methods for enums, mocks, Protocol Buffer bindings, embedded assets, SQL access code. The command itself knows nothing about those tools; it only finds the directives and runs them.
Generation is a separate, explicit step. go build and go test never run it, so generated files are normally committed to version control. That keeps builds reproducible and lets go install of your module work for people who do not have your generators installed.
//go:generate stringer -type=Color //go:generate go run ./internal/gen -out tables.go type Color int
go generate ./...
Try it
A generator is an ordinary program that writes a file. The first example finds //go:generate lines the way the tool does, including variable expansion; the second is a tiny generator that emits formatted Go code.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
//go:generate command argument...
go generate [-run regexp] [-skip regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]
| Element | Description |
|---|---|
//go:generate ... |
A line comment that begins exactly with //go:generate at the start of a line (no space after //). The rest is the command. Arguments are space-separated; use double quotes for arguments with spaces, and Go string escapes inside them. |
-run regexp |
Run only directives whose full text matches the expression. |
-skip regexp |
Skip directives that match (Go 1.21). |
-n |
Print the commands without running them. |
-v |
Print the names of files and packages as they are processed. |
-x |
Print commands as they are executed. |
| Build flags | -tags and others decide which files are scanned. |
Variables available to the command (also as environment variables): $GOARCH, $GOOS, $GOFILE (base name of the file), $GOLINE (line number of the directive), $GOPACKAGE, $GOROOT, $DOLLAR (a literal $), and $PATH.
Aliases: //go:generate -command name args defines a short name for a command inside that file, such as //go:generate -command yacc go tool yacc.
Errors: if a command fails, go generate stops at the first failure and exits nonzero. The working directory is always the package directory.
Usage notes
- Run order is deterministic: packages in the order given on the command line (or alphabetically), files in each package sorted by name, directives in source order. A directive can rely on files produced by earlier ones.
- Mark generated files. Put
// Code generated by <tool>; DO NOT EDIT.before thepackageline (exact pattern:^// Code generated .* DO NOT EDIT\.$). Tools like go vet, linters and code review UIs then treat the file differently. - Pin the tool version.
//go:generate go run golang.org/x/tools/cmd/[email protected] -type=Colorworks without any prior install and keeps everyone on one version. In Go 1.24 and later, you can record the tool ingo.modand writego tool stringer. - Not a build step. If a generated file is out of date,
go buildwill not notice. Add a CI job that runsgo generate ./...and fails ifgit diffshows changes. - Patterns matter.
go generate ./...covers the whole module; run it with-nfirst to see what would run. It never descends intotestdataorvendor. - Dependencies on shell features. Commands run without a shell, so
>redirection, pipes and&&do not work. Wrap them in a small Go program (go run ./gen) or a script for portability. go:embedis often simpler. If you only need file contents at build time,embedavoids a generation step.- Format output. Use
go/format.Sourcein your generator, as in the second example, so regenerating does not create diffs.