Frequently Asked Questions

Purpose and Scope

This FAQ answers practical questions that come up when a reader first encounters the Go repository rather than only the installed Go toolchain. The repository is both the development home for the language implementation and the source of public distributions, so the right answer often depends on whether you are trying to install Go, run go commands in an existing project, understand package selection, check compatibility, or contribute a change. The answers below use repository files that define the project identity, the go help text compiled into the command, and the API checker data rules used during releases.

Sources: README.md, src/cmd/go/internal/help/helpdoc.go, api/README

The official tutorial flow starts by installing Go, creating a small module, running code with the go command, and then adding dependencies and tests. This page is complementary: it explains the recurring vocabulary behind those steps. Terms such as binary distribution, source installation, package pattern, build list, cgo, and API feature file are defined before they appear in more specialized guides. If you are blocked on a concrete task, scan the question headings first; if you are new to the repository, read the sections in order.

Sources: README.md, src/cmd/go/internal/help/helpdoc.go, api/README

Relevant Source Files

• README.md - Defines the repository as The Go Programming Language, points to the canonical Git host and GitHub mirror, names official download and source-install documentation, states the license location, and links contribution and question channels.
• src/cmd/go/internal/help/helpdoc.go - Contains built-in help topics for the go command, including package list and pattern behavior plus the help topic for calling between Go and C or C++ through cgo and SWIG.
• api/README - Documents the data files consumed by Go's API checker, the frozen release API files, compatibility exceptions, proposal issue suffixes, and the next-release API staging process.

Distribution, Repository, and Installation Questions

Where is the real Go repository?

The Go project names https://go.googlesource.com/go as the canonical Git repository and https://github.com/golang/go as a mirror. That distinction matters for contributors and for readers comparing repository links in documentation, issue discussions, or code reviews. The GitHub mirror is useful for browsing and integration with GitHub workflows, but the project identity in the root README points to the Go-hosted repository as canonical. For most users installing Go, this repository distinction is less important than using an official binary distribution from the public download site.

Sources: README.md

Should I install a binary release or build from source?

The repository README directs most users to official binary distributions and then to installation instructions. A binary distribution is the normal starting point because it packages the compiler, standard library, go command, and bundled tools for a supported operating system and architecture. Source installation is the fallback when a binary distribution is not available for your platform combination, or when you are intentionally working on the Go implementation itself. This split keeps ordinary application development separate from toolchain development and avoids making new users bootstrap the compiler unnecessarily.

Sources: README.md

What license applies to the source tree?

Unless another file says otherwise, the README states that Go source files are distributed under the BSD-style license found in the repository LICENSE file. For application developers, this mainly means the open source license is defined at the repository root rather than repeated in every package. For contributors, it also means license expectations are part of the project-wide source rules. When documenting or redistributing source from this repository, use the repository license as the controlling reference and check individual files only when they explicitly indicate a different condition.

Sources: README.md

Toolchain and Environment Questions

What is the go command's model for selecting packages?

Many go subcommands operate on a set of packages written as go <action> [packages]. The built-in help text describes package arguments as filesystem paths, import paths, reserved names, or lists of files. If no package argument is supplied, the command applies to the package in the current directory. This is why tutorial commands often work after changing into the directory that contains source code: the current directory becomes the default package selection context for commands such as go run, go build, and go test.

Sources: src/cmd/go/internal/help/helpdoc.go

How do ./... and other wildcard package patterns work?

The ... wildcard expands to match zero or more path elements in filesystem or import paths. Relative filesystem patterns are common during local development; for example, go test ./... means test packages under the current directory tree, subject to exclusions. The help text calls out exclusions for expanded filesystem patterns, including directories named vendor, directories named testdata, files or directories beginning with _ or ., directories containing a go.mod file, and directories matching an ignore directive in a module's go.mod. These rules explain why broad commands sometimes skip nested modules or test fixtures.

Sources: src/cmd/go/internal/help/helpdoc.go

What is an import path pattern, and how does it relate to modules?

Import path patterns are interpreted in module-aware terms. The help text says import path patterns match packages from modules in the build list, which is the list of module versions used for a build. Some commands also accept versioned package patterns such as example.com/my/module@v1.2.3, describing packages at a specific module version independent of the current module's build list. This is the connection between command-line package selection and module dependency resolution: the pattern names packages, while the build list determines which module versions supply them.

Sources: src/cmd/go/internal/help/helpdoc.go

How does Go call C or C++ code?

The go command help topic for C interoperation identifies two supported paths. The first is cgo, which is part of the Go distribution and is documented as cmd/cgo. The second is SWIG, a separate interface generator for connecting languages. During go build, files ending in .swig are passed to SWIG, and .swigcxx files are passed with the C++ option. A package still needs at least one .go file, even if that file contains only a package clause. This keeps mixed-language packages anchored in Go package structure.

Sources: src/cmd/go/internal/help/helpdoc.go

Which environment variables affect C and C++ compilation?

When cgo or SWIG is involved, the go build help text says C-like source files such as .c, .m, .s, .S, or .sx are passed to the C compiler, while .cc, .cpp, and .cxx files are passed to the C++ compiler. The CC and CXX environment variables may be set to choose the C and C++ compilers respectively. This is an important boundary: ordinary pure-Go builds are driven by Go tooling, but mixed-language builds also depend on platform C or C++ toolchains and their configuration.

Sources: src/cmd/go/internal/help/helpdoc.go

Compatibility and API Questions

How does the repository track public API compatibility?

The api directory contains data for Go's API checker, invoked as go tool api from the repository's command tree. Each file is a list of API features, one per line. Release files such as go1.txt and similarly named files are frozen after a version ships; future files add new lines but do not remove existing ones. This format turns public API history into reviewable repository data, making compatibility an auditable part of the source tree instead of an informal promise detached from code.

Sources: api/README

Can any public API disappear?

The API data rules include an except.txt file for features that may disappear without breaking true compatibility. That exception file is intentionally separate from the frozen release API files, so compatibility decisions are explicit. For readers, the practical lesson is that the Go project treats exported API tracking as conservative by default: released API files grow over time, and removal-like behavior is represented through a named exception mechanism rather than silent deletion from historical records.

Sources: api/README

What is required when adding a new standard library API?

Starting with Go 1.19 API files, each API feature line must end with a proposal issue suffix in the form #nnnnn. The same requirement applies to files under api/next, which are staged for the next release. The suffix supports end-of-cycle auditing by connecting each new API feature to the accepted proposal issue that authorized it. In practice, this means a code change adding public API is not complete merely because tests pass; it must also satisfy the repository's API data and release documentation workflow.

Sources: api/README

What is the api/next directory for?

The api/next directory is the only part of the API data area intended to be mutated during ordinary development. Each file there lists features that may be added to the next Go release, and files are named after the accepted proposal issue number. The README also states that adding a file under api/next requires adding at least one file under doc/next. That pairing connects API tracking with release-note preparation, helping contributors document user-visible changes before release finalization.

Sources: api/README

Contribution and Support Questions

Where should I ask questions about Go?

The README distinguishes contribution and support channels. It says the Go issue tracker is used for bug reports and proposals only, and points readers to a questions page for places to ask about the Go language. This distinction is useful because not every difficulty is a project issue: many are learning, design, deployment, or troubleshooting questions better handled in community support channels. If you are unsure whether something is a bug, first reduce it to a reproducible case and compare it with documented tool behavior.

Sources: README.md

How do I contribute to Go?

The README explicitly invites contributions and points contributors to the contribution guidelines. In repository terms, contribution usually means more than submitting code: changes can interact with tests, toolchain behavior, API files, release notes, and compatibility policy. For API-affecting work, the api/README rules are especially important because new public features need proposal issue references and next-release staging. For command behavior, built-in help text like src/cmd/go/internal/help/helpdoc.go is also user-facing documentation and should remain accurate when behavior changes.

Sources: README.md, src/cmd/go/internal/help/helpdoc.go, api/README

Quick Reference

Question area	Repository-backed answer	Primary source
Official distribution	Use official binary releases first; source install is for unsupported platform combinations or toolchain work.	README.md
Canonical repository	The canonical Git repository is on go.googlesource.com; GitHub is a mirror.	README.md
Package arguments	go <action> [packages] accepts filesystem paths, import paths, reserved names, and file lists.	src/cmd/go/internal/help/helpdoc.go
Recursive local commands	./... expands recursively but skips selected directories and nested module roots.	src/cmd/go/internal/help/helpdoc.go
C and C++ interop	cgo is bundled; SWIG is also recognized for .swig and .swigcxx files during builds.	src/cmd/go/internal/help/helpdoc.go
C compiler selection	CC and CXX select C and C++ compilers for mixed-language builds.	src/cmd/go/internal/help/helpdoc.go
API compatibility	Frozen go1*.txt files record released API features; api/next stages upcoming additions.	api/README
New API process	API lines for Go 1.19 and later need accepted proposal issue suffixes such as #nnnnn.	api/README

Next Steps

If your question is about installing or running Go, start with the download and getting-started pages, then return here when command terminology becomes confusing. If your question is about project layout, package naming, or dependency tracking, continue to the module and workspace pages because those explain the module files that shape package resolution. If your question is about contributing to the language, standard library, or tools, read the contributor-facing pages on the API compatibility checker and release notes process before changing public API or user-visible command behavior.

Sources: README.md, src/cmd/go/internal/help/helpdoc.go, api/README