NAME¶

packages - package lists and patterns

DESCRIPTION¶

Many commands apply to a set of packages:

go <action> [packages]

Usually, [packages] is a list of package patterns, which 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

If no import paths are given, the action applies to the package in the current directory.

“...” elements in filesystem or import paths expand to match 0 or more path elements. Specific rules are described below.

File system patterns

Patterns beginning with a file system root like / on Unixes, or a volume name like C: on Windows are interpreted as absolute file system paths. Patterns beginning with a “.” or “..” element are interpreted as relative file system paths. File system paths denote the package contained within the given directory.

Relative paths can be used as a shorthand on the command line. If you are working in the directory containing the code imported as “unicode” and want to run the tests for “unicode/utf8”, you can type “go test ./utf8” instead of needing to specify the full path. Similarly, in the reverse situation, “go test ..” will test “unicode” from the “unicode/utf8” directory. Relative patterns are also allowed, such as “go test ./...” to test all subdirectories.

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

These can be included by either using them in the prefix, or changing into the directories. For example, “./...” won’t match a “./testdata/foo” package, but “./testdata/...” will.

Directories containing other go modules, which 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 be import paths as described in “go help importpath”. Import path patterns natch the packages from modules in the build list. The “build list” is 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.

Import path patterns may also use a “...” wildcard, such as:

“example.com/my/module/...”.

This can be combined with the version specifier such as:

“example.com/my/module/...@latest”.

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 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. 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 the 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. In most cases, it is an error to do so (e.g. “go build main.go” or “go build *.go”). Instead prefer to operate on complete packages (directories), such as: “go build .”

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. Within a program, all packages must be identified by a unique import path.

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.

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.

As 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”, 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.

There following package names have special meanings:

• “main” denotes the top-level package in a stand-alone executable. “main” packages cannot be imported.
• “documentation” indicates documentation for a non-Go program in the directory. Files in package documentation are ignored by the go command.
• “_test” 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).