Table of Contents
go Command Quick Reference
Contents
Subcommand overview
| Command |
What it does |
go build |
Compile packages and dependencies (binary only for main). |
go run |
Compile and run a main package. |
go install |
Build and install a binary into $GOBIN/$GOPATH/bin. |
go test |
Run tests, benchmarks, fuzzers, examples. |
go vet |
Report likely mistakes via static analysis. |
go fmt |
Run gofmt over packages (canonical formatting). |
go mod |
Manage modules, dependencies, go.mod/go.sum. |
go get |
Add/upgrade/remove module dependencies. |
go work |
Manage multi-module workspaces (go.work). |
go list |
List packages/modules and metadata (great with -json). |
go doc |
Show documentation for a package/symbol. |
go generate |
Run //go:generate directives. |
go clean |
Remove build artifacts and caches. |
go env |
Print/set Go environment variables. |
go version |
Print Go version (and a binary's build version). |
go tool |
Run a bundled tool (pprof, trace, cover, objdump...). |
go fix |
Update code to newer Go APIs. |
go bug |
Open a bug report template with environment info. |
go telemetry |
Manage Go toolchain telemetry settings. |
go build flags
| Flag |
Effect |
-o <path> |
Output file/directory name. |
-v |
Print package names as they compile. |
-x |
Print the underlying commands run. |
-race |
Enable the data race detector. |
-msan / -asan |
Memory / address sanitizer. |
-trimpath |
Remove local filesystem paths from the binary (reproducible builds). |
-ldflags "..." |
Pass flags to the linker: -s -w (strip), -X pkg.Var=val (set string var). |
-gcflags "..." |
Pass flags to the compiler: -m (escape analysis), -N -l (disable opt/inline for debugging). |
-tags "a,b" |
Set build tags / constraints. |
-mod=mod\|readonly\|vendor |
Module download/verify behavior. |
-p N |
Parallelism (number of programs to run). |
-a |
Force rebuild of all packages. |
-buildvcs=false |
Don't stamp VCS info into the binary. |
-cover |
Build with coverage instrumentation (Go 1.20+ for binaries). |
go build -o bin/app -trimpath -ldflags "-s -w -X main.version=$(git describe)" ./cmd/app
go build -gcflags="-m" ./... # show escape-analysis decisions
go test flags
| Flag |
Effect |
-run <regexp> |
Run only matching tests/subtests. |
-bench <regexp> |
Run matching benchmarks (. = all). |
-fuzz <regexp> |
Run a fuzz target. |
-v |
Verbose: log every test and t.Log output. |
-count N |
Run each test N times; -count=1 disables caching. |
-race |
Race detector. |
-cover / -coverprofile f |
Coverage summary / write profile. |
-covermode set\|count\|atomic |
Coverage counting mode (atomic for -race). |
-coverpkg <list> |
Packages to measure coverage for. |
-benchmem |
Report allocations in benchmarks. |
-benchtime <d\|Nx> |
Per-benchmark duration or iteration count. |
-cpuprofile / -memprofile / -blockprofile / -mutexprofile |
Write profiles. |
-trace f |
Write an execution trace. |
-timeout <d> |
Per-package timeout (default 10m); panic dump on expiry. |
-short |
Signal testing.Short() to skip slow tests. |
-parallel N |
Max simultaneous t.Parallel tests. |
-shuffle on\|off\|seed |
Randomize test/benchmark order. |
-failfast |
Stop after the first failing test. |
-json |
Emit machine-readable results. |
-list <regexp> |
List matching tests without running them. |
-tags |
Build tags. |
-c |
Compile the test binary to pkg.test, don't run. |
go test -run TestParse/empty -v -count=1 ./...
go test -bench=. -benchmem -benchtime=3s -cpuprofile=cpu.out ./pkg
go mod subcommands
| Command |
Effect |
go mod init <path> |
Create a new go.mod. |
go mod tidy |
Add missing & remove unused deps; sync go.sum. |
go mod download [pkg] |
Download modules into the cache. |
go mod verify |
Verify cached modules match go.sum. |
go mod why <pkg> |
Explain why a package/module is needed. |
go mod graph |
Print the module requirement graph. |
go mod edit <flags> |
Edit go.mod programmatically (-require, -replace, -droprequire). |
go mod vendor |
Copy dependencies into ./vendor. |
go mod tidy
go mod edit -replace github.com/foo/bar=../bar
go mod why -m golang.org/x/sys
go get patterns
go get example.com/pkg # add at latest (or upgrade)
go get example.com/pkg@v1.4.0 # pin exact version
go get example.com/pkg@latest # latest tagged release
go get example.com/pkg@master # a branch
go get example.com/pkg@e3702bed2 # a commit
go get example.com/pkg@none # remove the dependency
go get -u ./... # upgrade deps to latest minor/patch
go get -u=patch ./... # patch upgrades only
go get -t ./... # include test dependencies
Note (Go 1.16+): go get only manages dependencies. To install a tool binary use go install pkg@version.
go tool pprof <profile> # interactive profiler (top/list/web/peek)
go tool pprof -http=:8080 cpu.out # browser UI (needs graphviz for graphs)
go tool trace trace.out # execution trace viewer
go tool cover -html=cover.out # coverage in browser
go tool cover -func=cover.out # per-function coverage table
go tool dist list # all GOOS/GOARCH targets
go tool objdump -s main.main bin # disassemble
go tool nm bin # symbol table
go tool compile -S file.go # emit assembly
go env
go env # print all
go env GOPATH GOROOT GOBIN # specific vars
go env -w GOPROXY=https://proxy.golang.org,direct # persist a setting
go env -w GOFLAGS=-mod=readonly
go env -u GOPROXY # unset back to default
go env -json # JSON output
Key variables: GOOS, GOARCH, CGO_ENABLED, GOPROXY, GOPRIVATE, GONOSUMDB/GONOSUMCHECK, GOFLAGS, GOMODCACHE, GOCACHE, GOTOOLCHAIN.
Package patterns
./... # current dir and all subdirectories (recursive)
. # just the current directory's package
all # every package in the module (and deps, for some cmds)
std # the standard library
./cmd/... # everything under ./cmd
example.com/pkg # an import-path package
go list ./... # list package import paths
go list -f '{{.Dir}}' ./... # custom template output
go list -m all # all modules in the build
go list -deps -json ./cmd/app # full dependency metadata
go doc strings.Builder # docs for a symbol
go doc -all net/http # full package docs