What does the //go:embed directive do, and what must be true of the declaration it sits on?

## What the directive actually is `//go:embed` is a *compiler directive*: a line comment with no space after the `//` that the `go` command interprets while building the package. Nothing about it happens at run time. When the toolchain sees the directive it resolves the patterns against the files sitting in the package's own directory on the build machine, reads their contents, and writes those bytes into the object file that becomes part of the final executable. The resulting binary is self-contained: you can delete the whole source tree, copy the executable to an empty container, and the data is still there. ## The declaration it must sit on Three rules govern the declaration, and each has a distinct failure mode. **One variable, at package scope.** The directive applies to the very next variable declaration in the file. Only blank lines and other line comments may separate them. It cannot be attached to a variable declared inside a function — the `go` command rejects that outright — and it cannot be attached to a grouped declaration that declares more than one name. **One of three types.** The variable must be declared as `string`, `[]byte`, or `embed.FS`. For `string` and `[]byte` the directive must match *exactly one* file, and the variable holds that file's contents. For `embed.FS` the directive may match any number of files and directories, and the variable behaves as a small read-only filesystem with `Open`, `ReadFile`, and `ReadDir` methods. **The import.** The file must import `embed`. When the variable is declared as `embed.FS` the import is ordinary, because you name the package in the type. When the variable is a `string` or a `[]byte` you never write `embed.` anywhere, so the compiler would flag the import as unused — that is why the blank form `import _ "embed"` exists. Leaving it out produces an error telling you that `//go:embed` is only allowed in files that import `embed`. ## The pattern rules Patterns use `path.Match` syntax — `*`, `?`, and character classes, always with forward slashes, on every operating system. They are interpreted relative to the directory containing the source file that carries the directive. Several consequences follow: - A pattern may not contain a `.` or `..` path element, and may not begin or end with a slash. There is deliberately no way to reach into a sibling directory or up to the repository root: everything a package embeds must live inside that package's directory tree. - A single directive may list several space-separated patterns, and a single variable may carry several directives; all of the matches are combined into one `embed.FS`. - If a pattern names a directory, the whole subtree under it is embedded recursively — except that names beginning with `.` or `_` are skipped unless the pattern is written with the `all:` prefix. - A pattern that matches nothing is a **build error**. This is a deliberate design choice: a typo in an asset path fails the build on the developer's machine or in the pipeline rather than producing a binary that serves blank pages. ## The gotcha that produces no error at all Because the directive is a comment, writing `// go:embed assets` with a space is simply an ordinary comment. The code still compiles, the variable keeps its zero value — an empty string, a nil slice, or an `embed.FS` containing nothing — and the failure only shows up when something asks for a file. The same is true of a directive separated from its declaration by a non-comment line. When an embedded asset is missing, checking the exact spelling and position of the directive is the first thing to do. ## Why it exists Before this directive, shipping templates, SQL migrations, or a web UI with a Go program meant either a code generator that turned files into a giant Go source file, or a deployment step that copied a directory next to the binary. Both were error-prone: the generated file drifted from the originals, and the copied directory could be missing, stale, or a different version from the binary. Embedding makes the assets part of the same immutable artefact as the code that reads them, which removes an entire class of version-skew incident. The cost, paid at build time, is a larger executable and a rebuild for every asset change.