Compiles every package in the module. Without -o it only type-checks and links — no binary is left behind.

go build -o bin/app ./cmd/app

Watch out./... skips the vendor directory and nested modules (directories with their own go.mod).

Compiles into a temp directory and runs immediately — the daily driver for local development.

go run ./cmd/app --config dev.yaml

Watch outKilling the go run process may leave the actual child binary running — always ship go build artifacts in production.

Runs all tests. Handy flags: -v verbose, -run to filter by regex, -race for the race detector, -cover for coverage.

go test -race -run TestParse ./pkg/parser/...
go test -coverprofile=cover.out ./... && go tool cover -html=cover.out

Watch outTest results are cached; changing env vars or external files does NOT invalidate the cache — force a rerun with -count=1.

The official static analyzer: printf mismatches, unreachable code, malformed struct tags, and more.

go vet ./... && staticcheck ./...

Watch outvet only covers a small set of high-confidence checks; add staticcheck in CI for much broader coverage.

Installs a command into GOBIN (default ~/go/bin) — the standard way to manage global Go tools.

go install golang.org/x/tools/cmd/goimports@latest
go install honnef.co/go/tools/cmd/staticcheck@2025.1

Watch outWith @version, go install ignores the go.mod in the current directory and builds in isolation; to add a project dependency use go get, not go install.

Wipes the build cache and module download cache — the last resort when dependency changes seem to have no effect.

go clean -cache
go clean -modcache   # harsher: deletes every downloaded module

Watch out-modcache deletes every downloaded module; the next build re-downloads everything, so use it carefully on CI images.

Initializes a module and writes go.mod. The module path is exactly what others will use to import you.

go mod init github.com/yourname/project

Watch outPrivate repos still need a full host-based path (e.g. git.company.com/team/proj); a short made-up name makes the module unresolvable.

Adds/removes go.mod entries to match real imports and completes go.sum — run it before every commit.

go mod tidy
go mod tidy -compat=1.26   # stay compatible with an older version

Watch outOn "missing go.sum entry", run go mod download <module> first, then tidy again; tidy scans build tags for the current GOOS/GOARCH only — mind -compat for older toolchains.

Adds, upgrades or downgrades a dependency (edits go.mod only — installs no binaries).

go get github.com/gin-gonic/gin@latest
go get github.com/sirupsen/logrus@v1.9.3   # same for downgrades

Watch outOmitting the version means @upgrade and may pull a cascade of indirect upgrades; pin an exact version for minimal diffs.

Lists all dependencies with available upgrades (a [v1.2.3] suffix means a newer version exists).

go list -m -u all
go list -m -versions github.com/spf13/cobra   # every version of one module

Watch out"all" includes indirect deps and gets long; filter to direct deps with go list -m -f '{{if not .Indirect}}{{.Path}}{{end}}' all.

Answers "who pulled this package in?" by showing the import chain from your main packages to it.

go mod why golang.org/x/sys
go mod graph | grep jwt   # the full dependency graph

Watch outwhy shows the chain from the main module's perspective; for raw version requirements between modules use go mod graph.

Downloads dependencies into the local cache without compiling — use it to warm up CI caches.

go mod download
go mod download github.com/gin-gonic/gin   # download just this module

Watch outMost "missing go.sum entry" build failures are fixed by downloading the offending module explicitly.

Verifies that cached modules match the hashes recorded in go.sum — guards against a tampered cache.

go mod verify

Watch outOnly "all modules verified" is a pass; any mismatch means the cache is untrustworthy — run go clean -modcache.

Formats source code: -l lists non-conforming files, -w rewrites in place, -d shows the diff without writing.

gofmt -l .          # CI check: any output means failure
gofmt -d main.go    # preview what would change
gofmt -s -w .       # also simplify the code

Watch outgofmt never adds/removes imports and does not reorder import groups — that is goimports territory, and their output can differ.

= gofmt + automatic import addition/removal + grouping (stdlib first, then third-party).

go install golang.org/x/tools/cmd/goimports@latest
goimports -local github.com/myorg -w .   # own packages in their own group

Watch outWithout -local, your own organization's packages land in the third-party group; the first run on a large repo builds an index and is expectedly slow.

Reads documentation in the terminal — packages, functions and types, no browser needed.

go doc net/http.Server
go doc json.Marshal
go doc github.com/gin-gonic/gin@latest   # pkg@version since Go 1.27

Watch outQuerying a third-party package that is not downloaded yet fails — run go mod download first or append @version.

Scans for //go:generate directives and runs them (mocks, stringer, and other codegen).

//go:generate stringer -type=Status
go generate ./...

Watch outgo generate is NOT part of the build — go build never triggers it. Commit generated files or run it in CI.

A stricter third-party formatter (a superset of gofmt), popular for enforcing team-wide style.

go install mvdan.cc/gofumpt@latest
gofumpt -extra -w .

Watch outgofumpt output is a stricter gofmt-compatible style; mixing both tools on one repo creates flip-flopping diffs.

The de-facto deep static analyzer: bugs, performance, deprecated APIs and simplifications.

go install honnef.co/go/tools/cmd/staticcheck@latest
staticcheck ./...

Watch outComplements go vet rather than replacing it: vet covers compiler-grade certainties, staticcheck covers broader practice.

The module download proxy. A regional mirror is essential where proxy.golang.org is unreachable or slow.

go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOPROXY=https://goproxy.io,direct   # another popular mirror

Watch outPut direct last: it means "fall back to the origin only after all proxies fail"; writing only direct disables proxies entirely.

Glob patterns for private module prefixes; matching modules bypass the proxy and checksum database and fetch directly.

go env -w GOPRIVATE=git.company.com/*,github.com/myorg/*
go env -w GONOPROXY=git.company.com/*   # bypass the proxy only

Watch outGOPRIVATE is the default for both GONOPROXY and GONOSUMDB; set those two individually when you only want one behavior.

Default flags appended to every go command, e.g. a global -mod=mod or -race.

go env -w GOFLAGS=-mod=mod
go env -u GOFLAGS   # unset the setting

Watch outWith a vendor/ directory and go >= 1.14, -mod=vendor is automatic — that is usually why go get edits seem to have no effect.

GOPATH is the workspace root; modules cache at $GOPATH/pkg/mod (GOMODCACHE); installed binaries land in GOBIN.

go env GOPATH GOMODCACHE GOBIN
go env -w GOBIN=$HOME/bin   # custom install location

Watch out"command not found" right after go install almost always means GOBIN is not on your PATH.

Toggles CGO. Set it to 0 for cross-compilation and fully static binaries.

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o app ./cmd/app

Watch outWith CGO off, net DNS resolution and os/user lookups fall back to pure-Go implementations that behave slightly differently from glibc (and are usually more reliable in Alpine containers).

The Go 1.11–1.22 module-mode switch; removed from the go command entirely in Go 1.23 — no need to set it anymore.

go env GO111MODULE   # on current versions: unknown go environment variable

Watch outDelete GO111MODULE=on from legacy CI scripts; if a script starts failing after a toolchain upgrade, this is why.

Module path, minimum language version, and the expected toolchain — the three header lines of go.mod.

module github.com/you/proj

go 1.26

toolchain go1.27.1

Watch outSince Go 1.21 the go directive is a hard floor: an older toolchain refuses to build instead of "giving it a try".

Declares a dependency with its minimum version. The // indirect comment marks deps your code does not import directly.

require (
	github.com/gin-gonic/gin v1.10.0
	golang.org/x/sys v0.24.0 // indirect
)

Watch outSince Go 1.27, go mod tidy consolidates scattered require blocks into the standard direct/indirect two-block layout — hand-splitting blocks is pointless.

Substitutes a module with a local directory or fork — the standard way to debug deps or apply temporary patches.

replace github.com/foo/bar => ../bar

replace github.com/foo/bar v1.2.3 => github.com/you/bar v1.2.4-fix

Watch outreplace only applies to the main module: when someone imports your library, the replace directives inside it are ignored.

Explicitly excludes a broken version; the go command treats it as non-existent.

exclude github.com/foo/bar v1.2.3

Watch outexclude is main-module-only too; to withdraw versions of a published library use retract, not exclude.

Lets a library author withdraw published versions (the antidote to a bad release); go get automatically avoids them.

retract (
	v1.2.0   // shipped an unfinished feature by mistake
	v1.1.9   // security issue, please upgrade to v1.1.10
)

Watch outretract does not delete versions (they stay on the proxy and can still be requested explicitly); it only removes them from queries like @latest.

Target OS and architecture — prefix go build with them to cross-compile.

GOOS=linux   GOARCH=amd64 go build -o app-linux-amd64   ./cmd/app
GOOS=linux   GOARCH=arm64 go build -o app-linux-arm64   ./cmd/app
GOOS=windows GOARCH=amd64 go build -o app.exe           ./cmd/app
GOOS=darwin  GOARCH=arm64 go build -o app-darwin-arm64  ./cmd/app

Watch outDependencies that use CGO (e.g. sqlite3 drivers) fail to cross-compile without a target C toolchain — switch to pure-Go alternatives like modernc.org/sqlite.

Lists every GOOS/GOARCH pair supported by your toolchain.

go tool dist list
go tool dist list | grep linux

Watch outExotic pairs (e.g. linux/riscv64) need no extra installation — if it is listed, it compiles.

Toolchain selection policy: auto downloads and switches per go.mod (default); local uses only the installed version.

go env GOTOOLCHAIN
go env -w GOTOOLCHAIN=local   # never download a toolchain automatically

Watch outOn CI images prefer local with the right version preinstalled — otherwise builds download a toolchain on the spot, which is slow and can fail.

The release-build trio: strips local paths, symbol table and DWARF info — typically 20–30% smaller binaries.

go build -trimpath -ldflags="-s -w" -o bin/app ./cmd/app

Watch outAfter -s -w, panics still carry line numbers but source-level debugging with delve is gone — use it for release artifacts only.

Shows the active toolchain version and full environment — the first step of any environment debugging.

go version
go env GOVERSION GOOS GOARCH GOPROXY
go env -json   # machine-readable dump of every setting

Watch outgo env shows the effective value, which can come from the OS environment, the go env -w file, or built-in defaults.