Skip to content
Tutorials Center
My learning

Topics

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
//go:generate stringer -type=Color
//go:generate go run ./internal/gen -out tables.go

type Color int
Terminal
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.

Go Finding directives and expanding variables

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.

Go A generator that writes 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.

Syntax

Go
//go:generate command argument...
Terminal
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 the package line (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=Color works without any prior install and keeps everyone on one version. In Go 1.24 and later, you can record the tool in go.mod and write go tool stringer.
  • Not a build step. If a generated file is out of date, go build will not notice. Add a CI job that runs go generate ./... and fails if git diff shows changes.
  • Patterns matter. go generate ./... covers the whole module; run it with -n first to see what would run. It never descends into testdata or vendor.
  • 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:embed is often simpler. If you only need file contents at build time, embed avoids a generation step.
  • Format output. Use go/format.Source in your generator, as in the second example, so regenerating does not create diffs.