Go Commands & Documentation — Middle Level¶

# 1. Works offline — no internet needed
go doc fmt.Println

# 2. Shows YOUR version's API (not current main branch)
go doc github.com/some/library.Function

# 3. Faster than browser navigation
go doc strings  # instant, vs opening browser, navigating, searching

# 4. Shows source code for any package
go doc -src net/http.Request

# 5. Works for private packages (no pkg.go.dev needed)
go doc ./internal/auth

# Configure git to ignore whitespace in diffs
git config --global core.whitespace trailing-space,space-before-tab

# Run before every commit (can be automated via pre-commit hook)
go fmt ./...

# OR: Use gofmt directly for more control
gofmt -w .              # Format all .go files
gofmt -d .              # Show what would change
gofmt -e .              # Show all errors, even when many
gofmt -r 'a[b:len(a)] -> a[b:]' .  # Apply rewrite rules!

# Method A: Terminal (fastest)
go doc fmt.Println

# Method B: Local web server (prettiest for extended reading)
go install golang.org/x/tools/cmd/godoc@latest
godoc -http=:6060
# Visit http://localhost:6060

# Method C: pkg.go.dev (shareable, always online)
# https://pkg.go.dev/fmt#Println

# Method D: Editor integration
# Most Go editors (VS Code + gopls, GoLand) show docs on hover
# This uses the same data as `go doc` internally

# Built-in:
go vet ./...

# Community tools (install separately):
go install honnef.co/go/tools/cmd/staticcheck@latest
staticcheck ./...

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run

# Security-focused:
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

# WRONG — pushing unformatted code
git add .
git commit -m "fix bug"
git push

# RIGHT — always format before commit
go fmt ./...
go vet ./...
git add .
git commit -m "fix bug"
git push

# WRONG — generates code during every build
build:
    go generate ./...
    go build ./...

# BETTER — generate is a development step, not build step
generate:
    go generate ./...

build:
    go build ./...

# Disable specific analyzer with nolint comment
// nolint: govet  # this is a go vet check, not golangci-lint

# For go vet specifically:
go vet -composites=false ./...  # disable composite literal check

# Check which analyzers exist
go doc cmd/vet

# Check which module version is active
go list -m github.com/some/package

# To see docs for a specific version:
# The docs will reflect the version in go.mod
# Update go.mod to see different version's docs:
go get github.com/some/package@v1.2.3
go doc github.com/some/package.Function

# Preview changes without applying
gofmt -d ./myfile.go

# See what rule triggered a change:
# The most common: trailing commas in multi-line function calls/declarations
# go fmt REQUIRES trailing commas before closing ) or }

# See where each value comes from
go env -json

# Check user-level overrides
cat $GOENV  # usually ~/.config/go/env

# Reset all user-level settings
go env -u GOPATH
go env -u GOPROXY

go doc [flags] [package | [package.]symbol[.methodOrField]]

Flags:
  -all       Show documentation for all symbols, not just exported
  -c         Case-sensitive matching
  -cmd       Show documentation for package's main command
  -short     One-line representation for each symbol
  -src       Show the full source code for the symbol
  -u         Show unexported symbols along with exported (like -all but wider)

# Examples:
go doc -all -u fmt          # everything in fmt, including unexported
go doc -short os            # one-line summary per exported symbol
go doc -c bufio.Reader      # case-sensitive match
go doc -src http.ServeMux   # show source code of ServeMux

# Key variables and their meanings:
GOROOT    # Go installation directory
GOPATH    # Workspace for non-module projects (less relevant today)
GOMODCACHE # Where downloaded modules are cached (~/.go/pkg/mod)
GOBIN     # Where `go install` puts binaries (default: $GOPATH/bin)
GOCACHE   # Build cache (~/.cache/go-build)
GOENV     # Location of user-level env file (~/.config/go/env)
GOPROXY   # Module proxy URL (default: https://proxy.golang.org,direct)
GONOSUMCHECK # Patterns to skip sum database check
GONOSUMDB # Modules to skip sum database check
GOFLAGS   # Default flags for all go commands
GOOS      # Target OS: linux, windows, darwin, freebsd
GOARCH    # Target arch: amd64, arm64, 386, arm
CGO_ENABLED # Whether to enable cgo (default: 1)
GOEXPERIMENT # Experimental features to enable

# Setting for corporate environments:
GOPROXY=https://proxy.company.com,direct  # use corporate proxy
GONOSUMCHECK=*.company.com                # skip checksum for internal packages

# Find all direct and indirect dependencies
go list -m all

# Find which modules have known vulnerabilities
govulncheck ./...

# Find the dependency graph for a specific package
go list -json -deps . | jq -r '.Deps[]' | sort | head -20

# Find why a dependency is included
go mod why github.com/some/package

# Show module graph
go mod graph | grep gin  # find all gin-related deps

# go vet error: Printf format issue
go vet ./...
# ./main.go:15:3: Printf call has arguments but no formatting directives
# Fix: use fmt.Print(x) not fmt.Printf(x) for non-format strings

# go vet error: unreachable code
# ./main.go:20:3: unreachable code
# Fix: remove code after return/panic

# go build error: ambiguous import
# Found in two different modules:
# Likely need to use replace directive in go.mod

# go list error: module not found
go list -m github.com/nonexistent/pkg
# go: module github.com/nonexistent/pkg: not a known module path
# Fix: check the import path spelling

# Check for known vulnerabilities in dependencies
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

# Audit GOPROXY setting — ensure you're using trusted proxy
go env GOPROXY
# Default: https://proxy.golang.org,direct (trusted)

# For private code, use GONOSUMCHECK to skip public checksum DB
go env -w GONOSUMCHECK="*.internal.company.com"

# Verify your go.sum is complete (not tampered)
go mod verify

# Check for dependencies with unusual licenses
go list -json -m all | jq -r '.[] | select(.Indirect == false) | .Path'

# Speed up builds with build cache
go env GOCACHE              # where cache lives
go clean -cache             # clear if debugging build issues

# Build cache is automatic — don't disable it
# The cache makes repeated builds nearly instant for unchanged packages

# Parallel test execution
go test -parallel=8 ./...   # run up to 8 test binaries in parallel

# Profile the build itself
go build -x ./...           # verbose: shows all commands run
go build -work ./...        # keeps temp directory for inspection

# List what would be compiled without compiling
go list -f '{{.ImportPath}} {{.Dir}}' ./...

# Pitfall 1: go fmt can't format code with syntax errors
# Fix syntax errors before formatting

# Pitfall 2: go generate order matters
# Generators are run in the order they appear in the source file
# If generator B depends on output of generator A, they must be in order

# Pitfall 3: go list -m all includes INDIRECT dependencies
# The (indirect) annotation indicates it's not directly imported
# go mod tidy will remove truly unused indirect dependencies

# Pitfall 4: GOFLAGS can cause surprising behavior
go env GOFLAGS  # if this is set, it modifies all go commands
# -mod=vendor means `go build` will use vendor/ not module cache

# Mistake 1: Not running go mod tidy before committing
# Results in go.mod having unused dependencies

# Mistake 2: go install inside a module changes go.mod
# Use: go install tool@version  (Go 1.16+)
# Not: go get tool  (modifies go.mod)

# Mistake 3: Documenting "what" not "why"
# BAD:
# // SetTimeout sets the timeout
// SetTimeout(d time.Duration)

# GOOD:
// SetTimeout sets the deadline for all operations on this connection.
// The timeout applies to reads, writes, and dial operations.
// A value of zero disables the timeout.
// SetTimeout(d time.Duration)

# Mistake 4: Using go vet as the only quality check
# go vet is fast but limited
# Add golangci-lint for comprehensive checking

# Trick 1: go doc can show a method's receiver type
go doc (*http.Request).Context  # shows the method on the pointer receiver

# Trick 2: go list can filter with templates
go list -f '{{if not .Standard}}{{.ImportPath}}{{end}}' ./...
# Only non-standard library packages

# Trick 3: go env -json for programmatic use
go env -json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['GOROOT'])"

# Trick 4: go vet respects build tags
go vet -tags integration ./...  # only vet files with //go:build integration tag