Go Commands Reference
This page provides a comprehensive reference for essential Go (Golang) commands, covering package management, building, testing, documentation, and advanced tool usage. Mastering these commands is crucial for efficient Go development.
Package Management with Go Get
The go get command is used to fetch and install packages and their dependencies. It's fundamental for managing external libraries in your Go projects.
# To fetch dependencies
go get github.com/foo/bar@v1.2.3
go get github.com/foo/bar@8e1b8d3
# Upgrade the dependency.
go get -u github.com/foo/bar
# Clear module cache
go clean -modcache
Building Executables with Go Build
The go build command compiles Go packages and their dependencies. You can specify the output file name and target platform for cross-compilation.
# Building an Executable.
go build -o=/tmp/foo . # Compile the package in the current directory
go build -o=/tmp/foo ./cmd/foo # Compile the package in the ./cmd/foo directory
# Cross-Compilation
GOOS=linux GOARCH=amd64 go build -o=/tmp/linux_amd64/foo .
GOOS=windows GOARCH=amd64 go build -o=/tmp/windows_amd64/foo.exe .
# List of all supported OS/architectures
go tool dist list
# Using Compiler and Linker Flags
go tool compile -help # complete list of available compiler flags
go build -gcflags="-m -m" -o=/tmp/foo . # print optimization decisions
go build -gcflags="all=-N -l" -o=/tmp/foo . # disable optimizations and inlining
go tool link -help # list of available linker flags
go build -ldflags="-X main.version=1.2.3" -o=/tmp/foo . # add a version number
go build -ldflags="-s -w" -o=/tmp/foo . # strip debug information from the binary
CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-extldflags "-static"' . # make the binary as static as possible
Testing and Benchmarking with Go Test
The go test command runs tests and benchmarks. It supports various flags for controlling test execution, race detection, and performance analysis.
# Run all tests in the current directory
go test .
# Run all tests in the current directory and sub-directories
go test ./...
# Testing with race detector
go test -race ./...
# Bypass the test cache when running tests
go test -count=1 ./...
# Delete all cached test results
go clean -testcache
# Run the test with the exact name TestFooBar
go test -v -run=^TestFooBar$ .
# Handy flag - skip long running tests
go test -short ./...
# Handy flag - don't run further tests after a failure.
go test -failfast ./...
# Running and Comparing Benchmarks
go test -bench=. ./... # Run all benchmarks and tests
go test -run=^$ -bench=. ./... # Run all benchmarks (and no tests)
go test -bench=. -benchmem ./... # Forces the output of memory allocation statistics
go test -bench=. -benchtime=5s ./... # Run each benchmark test for at least 5 seconds
go test -bench=. -count=3 ./... # Repeat each benchmark test 3 times over
# Comparing changes between benchmarks
go get golang.org/x/tools/cmd/benchcmp@latest # Install the compare tool.
go test -run=^$ -bench=. -benchmem ./... > /tmp/old.txt # Measure benchmark before changes
go test -run=^$ -bench=. -benchmem ./... > /tmp/new.txt # Measure benchmark after changes
benchcmp /tmp/old.txt /tmp/new.txt # Compare changes.
Documentation and Debugging Tools
Go provides built-in tools for viewing documentation and debugging issues, such as go doc, go fix, and go bug.
# View simplified documentation for the strings package
go doc strings
# View documentation for the strings.Replace function
go doc strings.Replace
# View the source code for the strings.Replace function
go doc -src strings.Replace
# Upgrading the code to a New Go Release
go fix ./...
# Create a new Github issue for Go's standard library
go bug
Environment and Cache Management
Manage your Go environment variables, build cache, and module cache effectively.
# View environment information
go env # List all environment variables.
go env -w GOPATH=/foo/bar # Set GOPATH environment variable to /foo/bar
# Build cache
go env GOCACHE # Check where your build cache is
go build -a -o=/tmp/foo . # Force all packages to be rebuilt
go clean -cache # Remove everything from the build cache
Advanced Go Tooling
Explore advanced tools like tracing and race condition detection for performance optimization and debugging.
# Trace generation
go test -run=^$ -bench=^BenchmarkFoo$ -trace=/tmp/trace.out .
go tool trace /tmp/trace.out # Works only on Chrome / Chromium at the moment
# Checking for Race Conditions
go build -race -o=/tmp/foo . # not for production