What does a //go:generate comment in a Go source file do, and when does it run?

## What the directive is `go generate` is Go's deliberately minimal answer to code generation. There is no build DSL, no task graph, no plugin system: you put a comment in a Go file naming a command line, and a separate `go` subcommand runs it. ```go //go:generate stringer -type=Status ``` The syntax rules are strict and unforgiving: - The line must begin at the **start of a line** in a Go source file, with no leading whitespace before `//`. - There must be **no space** between `//` and `go:generate`. `// go:generate stringer -type=Status` is a plain comment and is silently ignored — this is the single most common mistake, and nothing warns you about it. - Everything after the directive is the command and its arguments, split on spaces (quoting with `"` and backquotes is honoured for a single argument). ## When it runs — and when it does not It runs when, and only when, someone runs `go generate` on the package: ``` go generate ./... ``` `go build`, `go install`, `go test` and `go vet` do **not** run generators. This is a design decision, not an omission: building a package must never execute arbitrary programs from someone else's source tree. It follows directly that the generated files are part of the repository. Anyone who fetches your module and builds it gets the committed `*_string.go`; they never run your generator, and may not even have it installed. `go generate` processes the packages you name, file by file in the order the go command lists them, and directives within a file in the order they appear. Each command runs with its working directory set to the directory of the file containing the directive, so relative paths in generator arguments are relative to the package, not to where you typed the command. ## No shell The command is executed directly, not through `sh` or a shell of any kind. Pipes, redirection, `&&`, `*` globbing and shell variable expansion do **not** work. If you need any of that, put it in a script or a small Go program and invoke that. What *is* substituted is a small fixed set of variables that `go generate` expands itself before executing: - `$GOFILE` — the base name of the file containing the directive - `$GOLINE` — the line number of the directive - `$GOPACKAGE` — the name of the package - `$GOOS`, `$GOARCH`, `$GOROOT` — the usual build environment values - `$DOLLAR` — a literal `$`, for when you need one There is also a `//go:generate -command <alias> <name> <args...>` form that defines a shorthand for the rest of that file's directives. ## Useful flags - `go generate -n ./...` prints the commands without running them — the first thing to reach for when a directive is not doing what you expect. - `go generate -x ./...` prints each command as it runs. - `go generate -v ./...` lists the packages and files as they are examined. - `go generate -run <regexp> ./...` runs only directives whose original source text matches the regular expression, which is how you re-run one generator across a large repository. If a directive does not fire at all, `-n` plus `-v` usually reveals the cause immediately: a space after `//`, a file excluded by a build constraint, or a package pattern that never matched. ## What it is typically used for The canonical example is `stringer`, which reads a set of `iota`-style constants and writes a `String() string` method for the type, so that printing a `Status` gives `Active` instead of `1`. Other common uses are turning a schema or an interface description into Go types, or producing a lookup table that would be tedious and error-prone to type by hand. The common thread is that the *input* is something already in your repository and the *output* is deterministic Go code. That is what makes committing the output sane: the generated file is reproducible from the source, and a reviewer can read the diff. ## The mental model Think of `//go:generate` as a note to a human that has been made machine-readable. It records, next to the code it produces, exactly which command produced it. The go command will run that note for you on request; it will never run it behind your back.