GO-PACKAGES(7)

✨ NAME ✨

packages — package lists and patterns 🫶

okay bestie, this is the page from the Go programming tools and commands manual that explains how the go command figures out which packages you're even talking about. it's giving "index of every way to point at code" and honestly? iconic. let's get into it 💅

---

🌸 DESCRIPTION 🌸

so, a ton of commands work on a whole set of packages at once, like this:

go <action> [packages]

usually that <packages> is a list of package patterns, and a pattern can take several forms:

• a relative or absolute path to a file system directory, which can contain ... wildcard elements
• an import path, which can also contain ... wildcard elements
• a reserved name that expands to a set of packages
• a list of files

and if you don't hand it any import paths at all, the action just applies to the package in the current directory. lowkey convenient, fr fr ✨

those ... elements inside filesystem or import paths expand to match 0 or more path elements. the specific rules are below, don't skip them 👇

📁 File system patterns

patterns that begin with a file system root — like / on Unixes, or a volume name like C: on Windows — get interpreted as absolute file system paths. patterns that begin with a . or .. element get interpreted as relative file system paths. either way, file system paths denote the package contained within the given directory. simple as that 💖

relative paths are also a cute shorthand on the command line. say you're working in the directory containing the code imported as unicode and you wanna run the tests for unicode/utf8 — you can just type go test ./utf8 instead of specifying the whole entire full path. and in the reverse situation, go test .. will test unicode from the unicode/utf8 directory. relative patterns are allowed too, like go test ./... to test all subdirectories. so handy 🎀

now here's the part where file system patterns expanded with the ... wildcard exclude the following:

• directories named vendor
• directories named testdata
• files and directories with names beginning with _ or .
• directories that contain a go.mod file
• directories matching an ignore directive in a module's go.mod file

want them included anyway? you can, by either using them in the prefix, or changing into those directories. for example, ./... won't match a ./testdata/foo package, but ./testdata/... will. main character problem-solving energy 💅

directories containing other go modules — which, remember, are denoted by the presence of a go.mod file — can only be matched by changing the working directory into module.

🦋 Import path patterns

patterns may also be import paths, as described in go help importpath. import path patterns match the packages from modules in the build list. and what's the build list? it's the list of module versions used for a build. see https://go.dev/ref/mod#glos-build-list for more details. 👑

some commands accept versioned package patterns, such as:

example.com/my/module@v1.2.3

these describe the matching package at the given version, independent of the versions used by the current module. so you can ✨specify✨ ngl.

import path patterns may also use a ... wildcard, such as example.com/my/module/..., and that can be combined with the version specifier too, like example.com/my/module/...@latest. obsessed with the flexibility honestly.

import path pattern expansion with ... depends on context:

• prefix/... matches all packages in modules in the build list that share the prefix, even if they belong to different modules
• patterns that include a version specifier, such as in prefix/...@latest, only match packages from the module that prefix belongs to

👑 Reserved names

the following reserved names each expand to a set of packages:

• work expands to all packages in the main module (or workspace modules)
• tool expands to the tools defined in the current module's go.mod file
• all expands to all packages in the main module (or workspace modules) and their dependencies, including dependencies needed by tests of any of those. and in the legacy GOPATH mode? all expands to all packages found in all the GOPATH trees 🌈
• std expands to all the packages in the standard library and their internal libraries
• cmd expands to the Go repository's commands and their internal libraries

🍓 List of .go files

if your pattern is a list of Go files rather than a complete package, the go command synthesizes a virtual package named command-line-arguments containing just the given files. but bestie, in most cases doing this is an error — like with go build main.go or go build *.go. 😭

instead, prefer to operate on complete packages (directories), such as:

go build .

periodt. that's the move 💖

🧚 Package names

packages are identified by their import path. import paths for packages in the standard library use their relative path under $GOROOT/src. import paths for all other packages are a combination of their module name and their relative directory path within the module. and within a program, all packages must be identified by a unique import path. no duplicates allowed, we don't do that here 💅

packages also have names, declared with the package keyword in a .go file, and used as the identifier when imported by another package. by convention, the names of importable packages match the last element of their import path — generally the name of the directory containing the package. cute, consistent, chef's kiss 🎀

package names do not have to be unique within a module, but packages that share the same name can't be imported together without one of them being aliased to a different name. so choose your aliases wisely ✨

since the go command primarily operates on directories, all non test .go files within a directory (excluding subdirectories) should share the same package declaration. test files may suffix their package declaration with _test, and tests in these files are compiled as a separate package and don't have access to unexported identifiers of their corresponding package. see go help test and go help testflag for details 👀

the following package names have special meanings:

• main denotes the top-level package in a stand-alone executable. and main packages cannot be imported. not even a little bit 🙅‍♀️
• documentation indicates documentation for a non-Go program in the directory. files in package documentation are ignored by the go command
• _test — that's the suffix in *_test.go files. these form a separate test package that only has access to the colocated package's exported identifiers. see go doc testing for details

for more information about import paths, see go help importpath. 💜

---

💖 AUTHOR 💖

this manual page was created using help2man and afterwards updating the output. it is maintained by the Debian Go Compiler Team <team+go-compiler@tracker.debian.org> for the Debian project (and may be used by others).

---

and that's the whole vibe check, bestie — this one's from Go 1.27, dated August 2026, and it lives in section 7 of the manual. go forth and point at packages correctly 🫶🌟