go generate documentation currently says:

Go generate sets several variables when it runs the generator:

$GOARCH
	The execution architecture (arm, amd64, etc.)
$GOOS
	The execution operating system (linux, windows, etc.)
$GOFILE
	The base name of the file.
$GOLINE
	The line number of the directive in the source file.
$GOPACKAGE
	The name of the package of the file containing the directive.
$DOLLAR
	A dollar sign.

Other than variable substitution and quoted-string evaluation, no special processing such as "globbing" is performed on the command line.

As a last step before running the command, any invocations of any environment variables with alphanumeric names, such as $GOFILE or $HOME, are expanded throughout the command line. The syntax for variable expansion is $NAME on all operating systems. Due to the order of evaluation, variables are expanded even inside quoted strings. If the variable NAME is not set, $NAME expands to the empty string.

The last sentence is relevant. It leads the user to believe that if a NAME is not one of the aforementioned variables and is not set in the environment, $NAME would expand to the empty string.

This is not the case for some Go-specific variables (beyond those mentioned in the list above) because expandVar uses os.Getenv(word) to look up environment variables that aren't in g.env. To achieve the behavior as documented above, it should instead be looking up environment variables from cfg.OrigEnv, since cmd/go's main modifies the environment at startup (see here).

To reproduce, consider this program:

package main

import (
	"fmt"
	"os"
)

//go:generate echo ${DOLLAR}GOCACHE expands to '$GOCACHE'

func main() {
	v, ok := os.LookupEnv("GOCACHE")
	if !ok {
		fmt.Println("env var GOCACHE is unset")
		return
	}
	fmt.Printf("$GOCACHE = %q\n", v)
}

What did you do?

$ unset GOCACHE
$ go run .
$ go generate

What did you expect to see?

$ go run .
env var GOCACHE is unset
$ go generate
$GOCACHE expands to ''

What did you see instead?

$ go run .
env var GOCACHE is unset
$ go generate
$GOCACHE expands to '/Users/gopher/Library/Caches/go-build'

/cc @bcmills @jayconrod @matloob