go-recipes

Contents

• Test
  • Continuous Tests Monitoring with codecov.io
  • Make treemap of coverage with go-cover-treemap
  • Browse coverage
  • Browse coverage with gocov-html
  • Browse coverage with xgo
  • Browse coverage in terminal with gocovsh
  • Pretty print coverage in terminal with nikandfor/cover
  • Run coverage collector server with goc
  • Visualize live coverage in VSCode with goc
  • Detect drops in coverage with go-test-coverage
  • :gift: Comment code coverage reports in pull request with go-coverage-report
  • :gift: Debug with Differential Coverage
  • :gift: Manipulate coverage profiles with gopherage
  • Shuffle tests
  • Run tests sequentially
  • Run tests in parallel
  • Run all Fuzz tests
  • :gift: Fuzz Go binaries using LibAFL with GoLibAFL
  • Detect goroutine leaks with goleak
  • Detect goroutine leaks with leaktest
  • Visualize test runs with vgt
  • Summarize go test with tparse
  • Decorate go test with richgo
  • Decorate go test with gotest
  • Decorate go test with gotestsum
  • Format go test results as documentation with gotestdox
  • Get slowest tests with gotestsum
  • Auto-Instrument skipping slowest tests with gotestsum
  • Automatically re-run failed tests with gotestsum
  • Make JUnit test report with gotestsum
  • Make JUnit test report with go-junit-report
  • Report each subtest as its own case with qualflare-go
  • Get packages without tests
  • Perform Mutation Testing with ooze
  • Perform Mutation Testing with avito-tech/go-mutesting
  • :gift: Perform Mutation Testing with jonbaldie/go-mutesting
  • Perform Mutation Testing with go-mutesting
  • Trace tests with go-test-trace
  • Speedup tests for large codebases
• Dependencies
  • Upgrade dependencies
  • Get Go version of current module
  • Get Go versions of upstream modules
  • Get directly dependent modules that can be upgraded
  • Get upstream modules without Go version
  • Get available module versions
  • Get go module libyear, number of releases, version delta with go-libyear
  • Make graph of upstream modules with modgraphviz
  • Make graph of upstream packages with import-graph
  • Scrape details about upstream modules and make graph with import-graph
  • Scrape licenses of upstream dependencies with go-licenses
  • Explore dependencies with goda
  • Explore dependencies interactively with spaghetti
  • Explore dependencies graph interactively with modview
  • Explore Go module ecosystem dependency graph interactively with shape-of-go
  • Explore dependencies graph in CLI with depth
  • Explore your GOPATH with GUI with goggles
  • Enforce Go code architecture with go-arch-lint
  • Check Clean Architecture with go-cleanarch
  • Use go mod directives
  • Locally patch dependency with replace
  • Locally patch dependency with go.work
• Code Visualization
  • Make C4 diagram with go-structurizr
  • Make graph of function calls with callgraph
  • Make graph of function calls in package with go-callvis
  • Make PlantUML diagram with goplantuml
  • Make PlantUML diagram with go-plantuml
  • Visualize the entropy of a code base with a 3D force-directed graph with dep-tree
  • Make 3D chart of Go codebase with gocity
  • Make histogram of Go files per package
  • Explore Go code in browser powered by go-guru with pythia
  • Interactively visualize packages with goexplorer
  • Make D2 graph of architecture and dependencies with go-arch-lint graph
• Code Generation
  • Run go:generate in parallel
  • Generate String method for enum types
  • Generate enums encoding with go-enum-encoding
  • Generate enums with goenums
  • Generate data types from JSON Schema with go-jsonschema
  • Generate constructor for a struct with gonstructor
  • Generate Table Driven Tests with gotests
  • Generate mocks with mockgen
  • Generate interface for a struct with ifacemaker
  • Generate interface for a struct with interfacer
  • Generate interface for a struct with struct2interface
  • Generate interface for CSV file with structer
  • Generate decorator for interface with gowrap
  • Modify struct field tags with gomodifytags
  • Generate code from OpenAPI 3 specification with oapi-codegen
  • Generate C-Go Bindings with c-for-go
• Generics
  • Enum via generics with enum
• Refactor
  • Replace symbol with gofmt
  • Apply refactoring patches with gopatch
  • Keep consistent ordering of imports with goimports
  • Keep consistent ordering of imports with gci
  • Keep consistent ordering of imports with goimportx
• Errors
  • Errors with return traces with errtrace
  • Errors with stack traces and source fragments with tracerr
  • Pretty print panic messages with panicparse
  • :gift: Generate errors from a spec with zederr
• Build
  • Fetch private dependencies in CI
  • Show compiler optimization decisions on heap and inlining
  • Disable inlining
  • Aggressive inlining
  • :gift: Reduce size of binary
  • Profile-guided optimization
  • Manually disable or enable cgo
  • Include metadata in binary during compilation with ldflags
  • Check if symbol or package is included in binary
  • Build for Raspberry Pi, Virtual Machine, embedded or normal PC with gokrazy
  • Visualise dependencies size in compiled binaries with go-size-analyzer
  • Make treemap breakdown of Go executable binary with go-binsize-treemap
  • Custom import path
  • Custom import path with govanityurls
  • Custom import path with sally
  • Custom import path with kkn.fi/vanity
  • Custom import path enforcement
  • Manage multiple Go versions with Goenv
  • Transpile C to Go with cxgo
  • Transpile Go to Javascript with gopherjs
  • Run compile-time function evaluation with prep
  • :gift: Containerize your builds with brewkit
• Assembly
  • Get assembly of Go code snippets online
  • Get Go SSA intermediary representation with ssaplayground
  • View Go assembly interactively with lensm
  • View Go assembly with color annotation with pat/disfunc
  • Generate Go assembly in Go with avo
  • Generate AST for code snippets with go/ast
  • Generate AST for code snippets with go2ast
  • Visualize Go SSA function using Graphviz with go-ssaviz
  • Make graph of AST with astgraph
  • Convert C assembly to Go assembly with c2goasm
• Deployment
  • :gift: Automatically set memory and cpu limits in K8S
• Execution
  • Get version of binary installed with go install
  • Embed Go Playground to your blog with codapi
  • Embed Go Playground to your blog with goplay
  • Run alternative Go Playground with goplay.tools
  • Use TinyGo Playground with tinygo
  • Run interactive Go kernels in Jupyter Notebook with gophernotes
  • Run interactive Go interpreter with yaegi
  • Run interactive Go interpreter with gomacro
  • Run Go function in shell with gorram
  • Run Go function in shell with gosh
  • Run simple fileserver with net/http
  • Create 3D visualization of concurrency traces with gotrace
  • Wrap command with os/exec
  • Capture output of command to file with os/exec
  • Capture output of command and process it with os/exec
  • Piping between processes with os/exec
  • errgroup and CommandContext with os/exec
• Monitor
  • Monitor Go Runtime metrics with opentelemetry
  • Monitor goroutines with grmon
  • Monitor Go processes with gops
  • Monitor Go runtime metrics in browser with live-pprof
  • Monitor Go runtime metrics in browser with statsviz
  • Auto-Instrument all functions with go-instrument
  • Auto-Instrument all functions with otelinji
  • Auto-Instrument functions for DataDog with orchestrion
  • Continuous Profiling with Pyroscope
• Benchmark
  • Run benchmarks
  • Table-driven benchmarks
  • Align benchmark output
  • Generate benchmark CPU and Memory profiles with go test
  • Visualize callgraph of profiles with pprof
  • Visualize flamegraphs of profiles with pprof
  • Visualize profiles online
  • :gift: Profile and visualize (with video) Go profiles through eBPF with go-profile
  • Get delta between two benchmarks with benchstat
  • Get summary of benchmarks with benchstat
  • Benchmark against git commit with pat/ba
  • Continuous benchmarking
  • Continuous benchmarking with gobenchdata
  • Continuous benchmarking with benchdiff
  • Continuous benchmarking with cob
  • Generate live traces with net/http/trace
  • Generate traces with go test
  • View traces with go tool trace
  • View traces with gotraceui
  • View in-process traces with trc
  • View wallclock traces with fgtrace
  • Get on/off CPU profiles with fgprof
• Document
  • Make alternative documentation with golds
  • Read Go binary documentation in man format with goman
  • Generate badge with gobadge
  • Generate README.md based on GoDoc comments with goreadme
  • :gift: display contents of a module with go-mod-viewer
• Education
  • Run Turtle Graphics online with goplay.space
• Style Guide
  • Google
  • Uber
  • Go Code Review Comments
• Security
  • Run official vulnerability check with govulncheck
  • Detect escalated privileges in dependencies with capslock
  • Run static analysis with gosec
  • Perform Taint Analysis with taint
  • Use Microsoft Go compiler with microsoft/go
• Static Analysis
  • Run default static analysis with go vet
  • Run custom static analysis tool with go vet
  • Run official static analyzers not included in go vet
  • Detect most common issues with staticcheck
  • Detect common style, performance, and naming issues with revive
  • Detect potential Nil panics with nilaway
  • Detect most common issues with go-critic
  • Reference and run common linters with golangci-lint
  • Detect non-exhaustive switch and map with exhaustive
  • Detect structs with uninitialized fields with go-exhaustruct
  • :gift: Detect missing cascade calls with go-lint-cascade
  • Detect unreachable functions with deadcode
  • Detect unsafe code with go-safer
  • Detect panic without explaining comment with panic-linter
  • Detect unnecessary type conversions with unconvert
  • Detect global variables with gochecknoglobals
  • Detect slices that could be preallocated with prealloc
  • Detect unnecessary import aliases with unimport
  • Detect unexpected import aliases with importas
  • Detect inconsistent import aliases with consistentimports
  • Detect naked returns with nakedret
  • Detect mixing pointer and value method receivers with smrcptr
  • Detect vertical function ordering with vertfn
  • Detect vertical symbol ordering with refdir
  • Detect tests with wrong t.Parallel() usage with paralleltest
  • Detect tests with wrong t.Parallel() usage with tparallel
  • Detect magic numbers with mnd
  • Detect magic strings with goconst
  • Detect bound checks with pat/boundcheck
  • :gift: Detect performance optimizations with perfsprint
  • Calculate Cognitive Complexity with gocognit
  • Calculate Cyclomatic Complexity with gocyclo
  • Calculate Cyclomatic Complexity with cyclop
  • Calculate age of comments with go-commentage
  • Ensure if statements using short assignment with ifshort
  • Detect sub-optimal struct layout with betteralign
  • Detect sub-optimal struct layout with structlayout-optimize
  • Visualize struct layout with structlayout
  • Rely on compiler for stricter Enums
  • Analyze function callsites with go-callsite-stats
• Guides
  • Go Optimization Guide
  • Go 101

Test

⏫ Continuous Tests Monitoring with codecov.io

Track tests duration, errors, and flakiness. Run JUnit test output converter and submit results to codecov.io via GitHub Action. — https://codecov.io

go test -coverprofile=coverage.out -cover -json ./... | gotestsum --junitfile tests.xml

Requirements

go install gotest.tools/gotestsum@latest

⏫ Make treemap of coverage with go-cover-treemap

Visualize distribution of code coverage in your project. This helps to identify code areas with high and low coverage. Useful when you have large project with lots of files and packages. This 2D "image-hash" of your project should be more representative than a single number. Also available at https://nikolaydubina.github.io/go-cover-treemap/. — @nikolaydubina

go test -coverprofile cover.out ./...
go-cover-treemap -coverprofile cover.out > out.svg

Requirements

go install github.com/nikolaydubina/go-cover-treemap@latest

⏫ Browse coverage

This is very helpful tool from the official Go toolchain. Similar visualization is integrated into VSCode and GoLand, but can be used separately.

go test -coverprofile cover.out ./...
go tool cover -html=cover.out

⏫ Browse coverage with gocov-html

Browse code coverage in statically generated HTML page. Multiple styles are supported. You may need to convert coverage report into gocov format. — @matm

gocov test strings | gocov-html -t golang > strings.html
gocov test encoding/csv strings | gocov-html -t kit > strings.html
gocov test strings|./gocov-html -cmax 90 > strings.html # show functions with <90% coverage

Requirements

go install github.com/axw/gocov/gocov@latest
go install github.com/matm/gocov-html/cmd/gocov-html@latest

⏫ Browse coverage with xgo

The displayed coverage is a combination of coverage and git diff. By default, only modified lines were shown. This helps to quickly locate changes that were not covered, and add tests for them incrementally. — @xhd2015

xgo tool coverage serve cover.out

Requirements

go install github.com/xhd2015/xgo/cmd/xgo@latest

⏫ Browse coverage in terminal with gocovsh

Browse code coverage similarly to HTML provided by official Go toolchain, but in terminal. Other notable features are package level statistics, coverage only for changed files. — @orlangure

go test -cover -coverprofile coverage.out
gocovsh                        # show all files from coverage report
git diff --name-only | gocovsh # only show changed files
git diff | gocovsh             # show coverage on top of current diff
gocovsh --profile profile.out  # for other coverage profile names

Requirements

go install github.com/orlangure/gocovsh@latest

⏫ Pretty print coverage in terminal with nikandfor/cover

It is similar to go tool cover -html=cover.out but in terminal. You can filter by functions, packages, minimum coverage, and more. — @nikandfor

cover

Requirements

go install github.com/nikandfor/cover@latest

⏫ Run coverage collector server with goc

This tool allows to collect coverage as soon as code is executed. — @qiniu

goc server
goc build
goc profile

Requirements

go install github.com/qiniu/goc@latest

⏫ Visualize live coverage in VSCode with goc

Official Go VSCode plugin already has coverage highlighting. In addition to that, this tool shows covered lines as soon as they are executed. This can be useful for running manual integration or system tests or debugging. — @qiniu

Requirements

go install github.com/qiniu/goc@latest

⏫ Detect drops in coverage with go-test-coverage

This tool is designed to report issues when test coverage falls below a specified threshold. Likely you would want to use it in the CI. — @vladopajic

go-test-coverage --config=./.testcoverage.yml

Requirements

go install github.com/vladopajic/go-test-coverage/v2@latest

⏫ :gift: Comment code coverage reports in pull request with go-coverage-report

A CLI tool and GitHub Action to post Go code coverage reports as a comment on your pull requests. — @fgrosse

⏫ :gift: Debug with Differential Coverage

This is a useful basic technique that should be more widely known (just like bisect). Read more in the blog post. — @rsc

⏫ :gift: Manipulate coverage profiles with gopherage

Kubernetes test-infra contains a couple of useful granular tools to manipulate coverage profiles. — @kubernetes

aggregate [files...]
diff [first] [second]
filter [file]
html [coverage]
junit [profile]
merge [files...]
metadata [...fields]

Requirements

go install k8s.io/test-infra/gopherage/cmd/aggregate@latest
go install k8s.io/test-infra/gopherage/cmd/diff@latest
go install k8s.io/test-infra/gopherage/cmd/filter@latest
go install k8s.io/test-infra/gopherage/cmd/html@latest
go install k8s.io/test-infra/gopherage/cmd/junit@latest
go install k8s.io/test-infra/gopherage/cmd/metadata@latest
go install k8s.io/test-infra/gopherage/cmd/merge@latest

⏫ Shuffle tests

This is less known option that is disabled by default. However, for robust test suite it is beneficial. More test flags and full description is available at go help testflag.

go test -shuffle=on

⏫ Run tests sequentially

Use when you need to synchronize tests, for example in integration tests that share environment. Official documentation.

go test -p 1 -parallel 1 ./...

⏫ Run tests in parallel

Add t.Parallel to your tests case function bodies. As per documentation, by default -p=GOMAXPROCS and -parallel=GOMAXPROCS when you run go test. Different packages by default run in parallel, and tests within package can be enforced to run in parallel too. Make sure to copy test case data to new variable, why explained here. Official documentation.

...
for _, tc := range tests {
    tc := tc
    t.Run(tc.name, func(t *testing.T) {
        t.Parallel()
        ...

⏫ Run all Fuzz tests

The standard tool runs only a single fuzz test. Use the following to run all fuzz tests in a package.

go test -list . | grep Fuzz | xargs -P 8 -I {} go test -fuzz {} -fuzztime 5s .

⏫ :gift: Fuzz Go binaries using LibAFL with GoLibAFL

This project provides a setup for fuzzing Go binaries using LibAFL. By leveraging Go native libFuzzer-compatible instrumentation (sancov_8bit), we enable advanced fuzzing capabilities beyond Go built-in fuzzing support. — @srlabs

⏫ Detect goroutine leaks with goleak

Instrument your test cases with verification call. Alternatively, you can add single call in TestMain. This tool was recommended by Pyroscope in blog. — Uber

func TestA(t *testing.T) {
  defer goleak.VerifyNone(t)
  ...
}

Requirements

go get -u go.uber.org/goleak

⏫ Detect goroutine leaks with leaktest

Refactored, tested variant of the goroutine leak detector found in both net/http tests and the cockroachdb source tree. You have to call this library in your tests. — @fortytw2

func TestPoolContext(t *testing.T) {
  ctx, cancel := context.WithTimeout(context.Background(), time.Second)
  defer cancel()
  defer leaktest.CheckContext(ctx, t)()

  go func() {
    for {
      time.Sleep(time.Second)
    }
  }()
}

⏫ Visualize test runs with vgt

This tool visualizes Go test results in a browser. It's helpful with understanding parallelism of tests and identifying slow tests. More information can be found in our blog post about optimizing Go tests parallelism. — @roblaszczak

go test -json ./... | vgt

Requirements

go install github.com/roblaszczak/vgt@latest

⏫ Summarize go test with tparse

This lightweight wrapper around STDOUT of JSON of go test will nicely render colorized test status, details of failures, duration, coverage, and package summary. — @mfridman

set -o pipefail && go test ./... -json | tparse -all

Requirements

go install github.com/mfridman/tparse@latest

⏫ Decorate go test with richgo

Add colors and enrich go test output. It can be used in CI pipeline and has lots of alternative visualizations and options. — @kyoh86

richgo test ./...

Requirements

go install github.com/kyoh86/richgo@latest

⏫ Decorate go test with gotest

Add colors to go test output. Very lightweight wrapper around go test STDOUT. — @rakyll

gotest ./...

Requirements

go install github.com/rakyll/gotest@latest

⏫ Decorate go test with gotestsum

This wrapper around go test renders test output in easy to read format. Also supports JUnit, JSON output, skipping slow tests, running custom binary. — @dnephin

gotestsum --format dots

Requirements

go install gotest.tools/gotestsum@latest

⏫ Format go test results as documentation with gotestdox

Decorates go test results by converting CamelCaseTestNames into readable sentences. — @bitfield

gotestdox ./...

Requirements

go install github.com/bitfield/gotestdox/cmd/gotestdox@latest

⏫ Get slowest tests with gotestsum

This is subcommand of gotestsum that processes JSON output of go test to find slowest tests. — @dnephin

go test -json -short ./... | gotestsum tool slowest --threshold 500ms

Example

gotest.tools/example TestSomething 1.34s
gotest.tools/example TestSomethingElse 810ms

Requirements

go install gotest.tools/gotestsum@latest

⏫ Auto-Instrument skipping slowest tests with gotestsum

This is subcommand of gotestsum that processes JSON output of go test to find slowest tests and instruments test cases to skip them with t.Skip() statements. — @dnephin

go test -json ./... | gotestsum tool slowest --skip-stmt "testing.Short" --threshold 200ms

Example

gotest.tools/example TestSomething 1.34s
gotest.tools/example TestSomethingElse 810ms

Requirements

go install gotest.tools/gotestsum@latest

⏫ Automatically re-run failed tests with gotestsum

Other useful option of gotestsum is to re-run failed tests. For example, if you have flaky tests that are idempotent, then re-running them may be a quick fix. — @dnephin

gotestsum --rerun-fails --packages="./..."

Requirements

go install gotest.tools/gotestsum@latest

⏫ Make JUnit test report with gotestsum

JUnit is widely used format for test reporting. — @dnephin

go test -json ./... | gotestsum --junitfile unit-tests.xml

Requirements

go install gotest.tools/gotestsum@latest

⏫ Make JUnit test report with go-junit-report

JUnit is widely used format for test reporting. Go benchmark output is also supported. — @jstemmer

go test -v 2>&1 ./... | go-junit-report -set-exit-code > report.xml

Requirements

go install github.com/jstemmer/go-junit-report/v2@latest

⏫ Report each subtest as its own case with qualflare-go

Turns go test -json into a report where every subtest is its own case with its own status and timing, and where labels, steps and files attached from inside a test travel with it. Also detects build failures, which produce no event in the JSON stream at all before Go 1.24. — @Qualflare

qualflare-go ./...

Requirements

go install github.com/Qualflare/qualflare-go/cmd/qualflare-go@latest

⏫ Get packages without tests

If code coverage does not report packages without tests. For example for CI or quality control.

go list -json ./... | jq -rc 'select((.TestGoFiles | length)==0) | .ImportPath'

Example

github.com/gin-gonic/gin/ginS
github.com/gin-gonic/gin/internal/json

Requirements

https://stedolan.github.io/jq/download/

⏫ Perform Mutation Testing with ooze

Mutation testing is a technique used to assess the quality and coverage of test suites. It involves introducing controlled changes to the code base, simulating common programming mistakes. These changes are, then, put to test against the test suites. A failing test suite is a good sign. It indicates that the tests are identifying mutations in the code—it "killed the mutant". If all tests pass, we have a surviving mutant. This highlights an area with weak coverage. It is an opportunity for improvement. — @gtramontina

go test -v -tags=mutation

Requirements

go get github.com/gtramontina/ooze

⏫ Perform Mutation Testing with avito-tech/go-mutesting

This is fork of zimmski/go-mutesting. It has more mutators and latest updates. — @vasiliyyudin

go-mutesting ./...

for _, d := range opts.Mutator.DisableMutators {
  pattern := strings.HasSuffix(d, "*")

-	if (pattern && strings.HasPrefix(name, d[:len(d)-2])) || (!pattern && name == d) {
+	if (pattern && strings.HasPrefix(name, d[:len(d)-2])) || false {
    continue MUTATOR
  }
}

Requirements

go install github.com/avito-tech/go-mutesting/cmd/go-mutesting@latest

⏫ :gift: Perform Mutation Testing with jonbaldie/go-mutesting

Fork of avito-tech/go-mutesting with a much richer mutator set, CI quality gates, covered MSI %, baseline tracking, per-test filtering, parallel execution, and LLM-ready output. — @jonbaldie

go-mutesting ./...

for _, d := range opts.Mutator.DisableMutators {
  pattern := strings.HasSuffix(d, "*")

-	if (pattern && strings.HasPrefix(name, d[:len(d)-2])) || (!pattern && name == d) {
+	if (pattern && strings.HasPrefix(name, d[:len(d)-2])) || false {
    continue MUTATOR
  }
}

Requirements

go install github.com/jonbaldie/go-mutesting/v2/cmd/go-mutesting@latest

⏫ Perform Mutation Testing with go-mutesting

Find common bugs source code that would pass tests. This is earliest tool for mutation testing in Go. More functions and permutations were added in other mutation Go tools it inspired. — @zimmski

go-mutesting ./...

for _, d := range opts.Mutator.DisableMutators {
  pattern := strings.HasSuffix(d, "*")

-	if (pattern && strings.HasPrefix(name, d[:len(d)-2])) || (!pattern && name == d) {
+	if (pattern && strings.HasPrefix(name, d[:len(d)-2])) || false {
    continue MUTATOR
  }
}

Requirements

go install github.com/zimmski/go-mutesting/cmd/go-mutesting@latest

⏫ Trace tests with go-test-trace

Collect test execution as distributed traces. This is useful for tracking test duration, failures, and flakiness. Your distributed tracing storage, search, UI, exploration, dashboards, and alarms all automatically become test status collection. If you run integration tests in your CI, then it is particularly handy to investigate your integration tests the same way as real requests, such as Go processes, databases, etc. However, if you do not have distributed traces, it is still useful for ad hoc investigations. This tool processes STDOUT of go test. No automatic instrumentation is done. — @rakyll

go-test-trace ./...

Requirements

# open telemetry collector
# traces UI (Datadog, Jaeger, Honeycomb, NewRelic)
go install github.com/rakyll/go-test-trace@latest

⏫ Speedup tests for large codebases

As of 2023-12-11, large codebases may be slow to run tests by default commands. Compiling package test binaries first and executing them later can lead to significant overall speedup.

go test -c ./pkg/mypackage -o my_pkg_test_binary.bin
./my_pkg_test_binary.bin | ... # normal test output post processing

Dependencies

⏫ Upgrade dependencies

In case VSCode or GoLand broke and you need to update dependencies manually.

go get -u ./...

⏫ Get Go version of current module

For example, setup correct Go version automatically from go.mod in CI.

go mod edit -json | jq -r .Go

Requirements

https://stedolan.github.io/jq/download/

⏫ Get Go versions of upstream modules

Use this when upgrading version of Go or finding old modules.

go list -deps -json ./... | jq -rc 'select(.Standard!=true and .Module.GoVersion!=null) | [.Module.GoVersion,.Module.Path] | join(" ")' | sort -V | uniq

Example

1.11 github.com/ugorji/go/codec
1.11 golang.org/x/crypto
1.12 github.com/golang/protobuf

Requirements

https://stedolan.github.io/jq/download/

⏫ Get directly dependent modules that can be upgraded

Keep your modules updated. Similar function is integrated in VSCode official Go plugin and GoLand.

go list -u -m $(go list -m -f '{{.Indirect}} {{.}}' all | grep '^false' | cut -d ' ' -f2) | grep '\['

Example

github.com/goccy/go-json v0.5.1 [v0.7.3]
github.com/golang/protobuf v1.3.3 [v1.5.2]
github.com/json-iterator/go v1.1.9 [v1.1.11]

⏫ Get upstream modules without Go version

Find outdated modules or imports that you need to upgrade.

go list -deps -json ./... | jq -rc 'select(.Standard!=true and .Module.GoVersion==null) | .Module.Path' | sort -u

Example

github.com/facebookgo/clock
golang.org/x/text
gopkg.in/yaml.v2

Requirements

https://stedolan.github.io/jq/download/

⏫ Get available module versions

This works even if you did not download or install module locally. This is useful to check to which version you can upgrade to, what is the latest version, and whether there are v2+ major versions recognized by Go toolchain.

go list -m -versions github.com/google/gofuzz

⏫ Get go module libyear, number of releases, version delta with go-libyear

libyear is a simple measure of software dependency freshness. It is a single number telling you how up-to-date your dependencies are. For example Rails 5.0.0 (June 2016) is 1 libyear behind 5.1.2 (June 2017). This tool can also compute number of releases, and version number delta. — @nieomylnieja

go-libyear /path/to/go.mod

Example

package                             version  date        latest   latest_date  libyear
github.com/nieomylnieja/go-libyear           2023-11-06                        2.41
github.com/pkg/errors               v0.8.1   2019-01-03  v0.9.1   2020-01-14   1.03
github.com/urfave/cli/v2            v2.20.0  2022-10-14  v2.25.7  2023-06-14   0.67
golang.org/x/mod                    v0.12.0  2023-06-21  v0.14.0  2023-10-25   0.35
golang.org/x/sync                   v0.3.0   2023-06-01  v0.5.0   2023-10-11   0.36

Requirements

go install github.com/nieomylnieja/go-libyear/cmd/go-libyear@latest

⏫ Make graph of upstream modules with modgraphviz

For each module, the node representing the greatest version (i.e., the version chosen by Go's minimal version selection algorithm) is colored green. Other nodes, which aren't in the final build list, are colored grey. — official Go team

go mod graph | modgraphviz | dot -Tsvg -o mod-graph.svg

Requirements

https://graphviz.org/download/
go install golang.org/x/exp/cmd/modgraphviz@latest

⏫ Make graph of upstream packages with import-graph

Find unexpected dependencies or visualize project. Works best for small number of packages, for large projects use grep to narrow down subgraph. Without -deps only for current module. — @nikolaydubina

go list -deps -json ./... | jq -c 'select(.Standard!=true) | {from: .ImportPath, to: .Imports[]}' | jsonl-graph | dot -Tsvg > package-graph.svg

Requirements

https://stedolan.github.io/jq/download/
https://graphviz.org/download/
go install github.com/nikolaydubina/import-graph@latest
go install github.com/nikolaydubina/jsonl-graph@latest

⏫ Scrape details about upstream modules and make graph with import-graph

Find low quality or unmaintained dependencies. — @nikolaydubina

go mod graph | import-graph -i=gomod | jsonl-graph -color-scheme=file://$PWD/basic.json | dot -Tsvg > output.svg

Requirements

https://graphviz.org/download/
go install github.com/nikolaydubina/import-graph@latest
go install github.com/nikolaydubina/jsonl-graph@latest

⏫ Scrape licenses of upstream dependencies with go-licenses

Collect all the licenses for checking if you can use the project, for example in proprietary or commercial environment. — Google

go-licenses csv github.com/gohugoio/hugo

Example

github.com/cli/safeexec,https://github.com/cli/safeexec/blob/master/LICENSE,BSD-2-Clause
github.com/bep/tmc,https://github.com/bep/tmc/blob/master/LICENSE,MIT
github.com/aws/aws-sdk-go,https://github.com/aws/aws-sdk-go/blob/master/LICENSE.txt,Apache-2.0
github.com/jmespath/go-jmespath,https://github.com/jmespath/go-jmespath/blob/master/LICENSE,Apache-2.0
github.com/gorilla/websocket,https://github.com/gorilla/websocket/blob/master/LICENSE,BSD-2-Clause
github.com/pelletier/go-toml/v2,https://github.com/pelletier/go-toml/blob/master/v2/LICENSE,MIT
github.com/spf13/cobra,https://github.com/spf13/cobra/blob/master/LICENSE.txt,Apache-2.0
github.com/kyokomi/emoji/v2,https://github.com/kyokomi/emoji/blob/master/v2/LICENSE,MIT
go.opencensus.io,Unknown,Apache-2.0
github.com/Azure/azure-storage-blob-go/azblob,https://github.com/Azure/azure-storage-blob-go/blob/master/azblob/LICENSE,MIT
github.com/yuin/goldmark-highlighting,https://github.com/yuin/goldmark-highlighting/blob/master/LICENSE,MIT

Requirements

go install github.com/google/go-licenses@latest

⏫ Explore dependencies with goda

This tool has extensive syntax for filtering dependencies graphs. It can work with packages and modules. — Egon Elbre

goda graph . | dot -Tsvg -o graph.svg
goda graph -cluster -short "github.com/nikolaydubina/go-cover-treemap:all" | dot -Tsvg -o graph.svg

Requirements

https://graphviz.org/download/
go install github.com/loov/goda@latest

⏫ Explore dependencies interactively with spaghetti

Useful in large refactorings, dependency breaking, physical layout changes. — Alan Donovan, official Go team

Requirements

go install github.com/adonovan/spaghetti@latest

⏫ Explore dependencies graph interactively with modview

Transform your Go project's dependency graph into a dynamic, interactive visualization with modview. This powerful tool takes the complexity out of your module graph, offering a clear and explorable view of your project's dependencies. — @bayraktugrul

modview --open

Requirements

go install github.com/bayraktugrul/modview@latest

⏫ Explore Go module ecosystem dependency graph interactively with shape-of-go

A map of the Go module ecosystem containing over 2.6 million modules and 9.4 million declared dependency edges in a single graph. The interactive WebGL viewer visualizes the connected module galaxy with hub and dependent analysis. Live interactive map at shape-of-go.pages.dev. — @LuisLSousa

⏫ Explore dependencies graph in CLI with depth

Use this tool to retrieve and visualize Go source code dependency trees in CLI. You can also visualize multiple packages at once, set max depth, select internal only, and show explanation. — @KyleBanks

depth github.com/KyleBanks/depth/cmd/depth

Example

github.com/KyleBanks/depth/cmd/depth
  ├ encoding/json
  ├ flag
  ├ fmt
  ├ io
  ├ log
  ├ os
  ├ strings
  └ github.com/KyleBanks/depth
    ├ fmt
    ├ go/build
    ├ path
    ├ sort
    └ strings
12 dependencies (11 internal, 1 external, 0 testing).

Requirements

go install github.com/KyleBanks/depth/cmd/depth@latest

⏫ Explore your GOPATH with GUI with goggles

Browse and search local packages. View package documentation. Displays badges for GoDoc, Goreportcard, and Travis.CI (if .travis.yml is present). — @KyleBanks

goggles

Requirements

go install github.com/KyleBanks/goggles/cmd/goggles@latest

⏫ Enforce Go code architecture with go-arch-lint

Architecture linter. Will check all project import path and compare with arch rules defined in yml file. Useful for hexagonal / onion / ddd / mvc / etc patterns. — @fe3dback

go-arch-lint

Requirements

go install github.com/fe3dback/go-arch-lint@latest

⏫ Check Clean Architecture with go-cleanarch

Clean architecture validator for go, like a The Dependency Rule and interaction between packages in your Go projects. — @roblaszczak

go-cleanarch

Requirements

go install github.com/roblaszczak/go-cleanarch@latest

⏫ Use go mod directives

Tell Go compiler which versions of upstreams to include in your build. Tell all users of your module how to deal with versions of your module.

// Deprecated: use example.com/mod/v2 instead.
module example.com/mod

go 1.16

require example.com/other/thing v1.0.2
require example.com/new/thing/v2 v2.3.4
exclude example.com/old/thing v1.2.3
replace example.com/bad/thing v1.4.5 => example.com/good/thing v1.4.5
retract [v1.9.0, v1.9.5]

⏫ Locally patch dependency with replace

This can be useful for development. First appeared on blog.

# clone your dependency to $DEP folder
# make changes
go mod edit -replace github.com/google/go-cmp=$DEP

⏫ Locally patch dependency with go.work

This is an alternative version may be more robust to accidental mistakes. First appeared on blog.

# clone your dependency to $DEP folder
# make changes
go work init
go work use . $DEP

Code Visualization

⏫ Make C4 diagram with go-structurizr

This library provides tools to generate C4 diagrams. The process is a bit involved, however you get diagram generated from real Go code automatically. Steps are outlined in blog. — @krzysztofreczek

Requirements

manually defining Go main.go script to invoke library
graphviz
manual coloring spec (DB, classes)

⏫ Make graph of function calls with callgraph

Visualize complex or new project quickly or to study project. Requires main.go in module. Supports Graphviz output format. Has many options for filtering and formatting. — official Go team

callgraph -format graphviz . | dot -Tsvg -o graph.svg
recommend: grep <package/class/func of interest>
recommend: grep -v Error since many packages report error
recommend: adding `rankdir=LR;` to graphviz file for denser graph
recommend: you would have to manually fix graphviz file first and last line

Requirements

go install golang.org/x/tools/cmd/callgraph@latest

⏫ Make graph of function calls in package with go-callvis

Quickly track which packages current package is calling and why. — @ofabry

go-callvis .

Requirements

go install github.com/ofabry/go-callvis

⏫ Make PlantUML diagram with goplantuml

Generates class diagrams in a widely used format with information on structs, interfaces, and their relationships. Render .puml files in, for example, planttext.com. — @jfeliu007

goplantuml -recursive path/to/gofiles path/to/gofiles2

Requirements

go get github.com/jfeliu007/goplantuml/parser
go install github.com/jfeliu007/goplantuml/cmd/goplantuml@latest

⏫ Make PlantUML diagram with go-plantuml

Automatically generates visualizations of classes and interfaces for Go packages. We recommend the recursive option. Render .puml files in, for example, planttext.com. — @bykof

go-plantuml generate -d . -r -o graph.puml

Requirements

go install github.com/bykof/go-plantuml@latest

⏫ Visualize the entropy of a code base with a 3D force-directed graph with dep-tree

This excellent interactive visualisation tool lets you explore code base as 3D graph. The more decoupled and modular a code base is, the more spread and clustered the graph will look like. — @gabotechs

⏫ Make 3D chart of Go codebase with gocity

Fresh artistic perspective on Go codebase. GoCity is an implementation of the Code City metaphor for visualizing source code - folders are districts; files are buildings; structs are buildings on the top of their files. This project has research paper "GoCity Code City for Go" at SANER'19. Also available at go-city.github.io. — @rodrigo-brito

Requirements

go install github.com/rodrigo-brito/gocity@latest

⏫ Make histogram of Go files per package

Find when package is too big or too small. Adjust histogram length to maximum value.

go list -json ./... | jq -rc '[.ImportPath, (.GoFiles | length | tostring)] | join(" ")' | perl -lane 'print (" " x (20 - $F[1]), "=" x $F[1], " ", $F[1], "\t", $F[0])'

Example

================== 18	github.com/gin-gonic/gin
     ============= 13	github.com/gin-gonic/gin/binding
                 = 1	github.com/gin-gonic/gin/internal/bytesconv
                 = 1	github.com/gin-gonic/gin/internal/json
       =========== 11	github.com/gin-gonic/gin/render

Requirements

https://stedolan.github.io/jq/download/

⏫ Explore Go code in browser powered by go-guru with pythia

Explore Go source code in browser. It provides exported symbols summary for navigation. It answers questions like: definition; callers; implementers. It is browser frontend based on go-guru, which was developed by Go core team from Google. — @fzipp

pythia net/http

Requirements

go install github.com/fzipp/pythia@latest
go install golang.org/x/tools/cmd/guru@latest

⏫ Interactively visualize packages with goexplorer

Based on go-callvis, this tool is an interactive package explorer of packages. This tool has not been updated for a long time. — @ofabry

⏫ Make D2 graph of architecture and dependencies with go-arch-lint graph

Can include vendors or not, and be of type 'flow' or 'di'. — @fe3dback

go-arch-lint graph

Requirements

go install github.com/fe3dback/go-arch-lint@latest

Code Generation

⏫ Run go:generate in parallel

Official Go team encourages to run sequentially. However, in certain situations, such as lots of mocks, parallelization helps a lot, albeit, you should consider including your generated files in git. The solution below spawns multiple processes, each per pkg.

grep -rnw "go:generate" -E -l "${1:-*.go}" . | xargs -L1 dirname | sort -u | xargs -P 8 -I{} go generate {}

⏫ Generate String method for enum types

This is an official tool for generating String for enums. It supports overrides via comments. — official Go team

package painkiller

//go:generate stringer -type=Pill -linecomment

type Pill int

const (
  Placebo Pill = iota
  Ibuprofen
  Paracetamol
  PillAspirin   // Aspirin
  Acetaminophen = Paracetamol
)

// "Acetaminophen"
var s string = Acetaminophen.String()

Requirements

go install golang.org/x/tools/cmd/stringer@latest

⏫ Generate enums encoding with go-enum-encoding

Generate encoding code for enums. This follows json struct tag notation. — @nikolaydubina

go generate ./...

type Color struct{ c uint }

//go:generate go-enum-encoding -type=Color
var (
  Undefined = Color{}  // json:"-"
  Red       = Color{1} // json:"red"
  Green     = Color{2} // json:"green"
  Blue      = Color{3} // json:"blue"
)

Requirements

go install github.com/nikolaydubina/go-enum-encoding@latest

⏫ Generate enums with goenums

Generate strict and fast enums. Generated code is much more tightly typed than just iota defined enums. You will get JSON decoder and encoder as well. This tool allows to generate extra fields and default values in enum structs. — @zarldev

goenums <file-with-iota.go>

package milkyway

type planet int // Gravity[float64],RadiusKm[float64],MassKg[float64],OrbitKm[float64],OrbitDays[float64],SurfacePressureBars[float64],Moons[int],Rings[bool]

//go:generate goenums planets.go
const (
  unknown planet = iota // invalid
  mercury               // Mercury 0.378,2439.7,3.3e23,57910000,88,0.0000000001,0,false
  venus                 // Venus 0.907,6051.8,4.87e24,108200000,225,92,0,false
  earth                 // Earth 1,6378.1,5.97e24,149600000,365,1,1,false
  mars                  // Mars 0.377,3389.5,6.42e23,227900000,687,0.01,2,false
  jupiter               // Jupiter 2.36,69911,1.90e27,778600000,4333,20,4,true
  saturn                // Saturn 0.916,58232,5.68e26,1433500000,10759,1,7,true
  uranus                // Uranus 0.889,25362,8.68e25,2872500000,30687,1.3,13,true
  neptune               // Neptune 1.12,24622,1.02e26,4495100000,60190,1.5,2,true
)

Requirements

go install github.com/zarldev/goenums@latest

⏫ Generate data types from JSON Schema with go-jsonschema

JSON Schema is a widely used standard for the definition of structured data types. This tool will generate a Go struct, decoder, and validation based on the JSON Schema spec. — @omissis

go-jsonschema -p main myschema.jsonschema

// Code generated by github.com/atombender/go-jsonschema, DO NOT EDIT.

package main

import "encoding/json"
import "fmt"

type Veggie struct {
        // Do I like this vegetable?
        VeggieLike bool `json:"veggieLike" yaml:"veggieLike" mapstructure:"veggieLike"`

        // The name of the vegetable.
        VeggieName string `json:"veggieName" yaml:"veggieName" mapstructure:"veggieName"`
}

// UnmarshalJSON implements json.Unmarshaler.
func (j *Veggie) UnmarshalJSON(b []byte) error {
        var raw map[string]interface{}
        if err := json.Unmarshal(b, &raw); err != nil {
                return err
        }
        if v, ok := raw["veggieLike"]; !ok || v == nil {
                return fmt.Errorf("field veggieLike in Veggie: required")
        }
        if v, ok := raw["veggieName"]; !ok || v == nil {
                return fmt.Errorf("field veggieName in Veggie: required")
        }
        type Plain Veggie
        var plain Plain
        if err := json.Unmarshal(b, &plain); err != nil {
                return err
        }
        *j = Veggie(plain)
        return nil
}

// A representation of a person, company, organization, or place
type A2Schema struct {
        // Fruits corresponds to the JSON schema field "fruits".
        Fruits []string `json:"fruits,omitempty" yaml:"fruits,omitempty" mapstructure:"fruits,omitempty"`

        // Vegetables corresponds to the JSON schema field "vegetables".
        Vegetables []Veggie `json:"vegetables,omitempty" yaml:"vegetables,omitempty" mapstructure:"vegetables,omitempty"`
}

Example

{
      "$id": "https://example.com/arrays.schema.json",
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "description": "A representation of a person, company, organization, or place",
      "type": "object",
      "properties": {
            "fruits": {
                  "type": "array",
                  "items": {
                        "type": "string"
                  }
            },
            "vegetables": {
                  "type": "array",
                  "items": {
                        "$ref": "#/$defs/veggie"
                  }
            }
      },
      "$defs": {
            "veggie": {
                  "type": "object",
                  "required": [
                        "veggieName",
                        "veggieLike"
                  ],
                  "properties": {
                        "veggieName": {
                              "type": "string",
                              "description": "The name of the vegetable."
                        },
                        "veggieLike": {
                              "type": "boolean",
                              "description": "Do I like this vegetable?"
                        }
                  }
            }
      }
}

Requirements

go get github.com/atombender/go-jsonschema/...
go install github.com/atombender/go-jsonschema@latest

⏫ Generate constructor for a struct with gonstructor

Constructor is a widely used useful pattern. This tool generates basic version of it that passes arguments to struct. It also supports initializer method. — @moznion

//go:generate gonstructor --type=Structure --constructorTypes=allArgs
type Structure struct {
  foo string
  bar io.Reader
  Buz chan interface{}
}

Requirements

go install golang.org/x/tools/cmd/goimports@latest
go install github.com/moznion/gonstructor/cmd/gonstructor@latest

⏫ Generate Table Driven Tests with gotests

This tool generates basic test placeholder. It is included into official Go plugin in VSCode and other major code editors. — @cweill

⏫ Generate mocks with mockgen

This mocking framework integrates well with Go's built-in testing package, but can be used in other contexts too. — Go Core team, Uber

mockgen . Conn,Driver

# foo.go
type Foo interface {
  Bar(x int) int
}

func SUT(f Foo) {
  // ...
}
# foo_test.go
func TestFoo(t *testing.T) {
  ctrl := gomock.NewController(t)

  m := NewMockFoo(ctrl)

  // Does not make any assertions. Executes the anonymous functions and returns
  // its result when Bar is invoked with 99.
  m.
    EXPECT().
    Bar(gomock.Eq(99)).
    DoAndReturn(func(_ int) int {
      time.Sleep(1*time.Second)
      return 101
    }).
    AnyTimes()

  // Does not make any assertions. Returns 103 when Bar is invoked with 101.
  m.
    EXPECT().
    Bar(gomock.Eq(101)).
    Return(103).
    AnyTimes()

  SUT(m)
}

Requirements

go install go.uber.org/mock/mockgen@latest

⏫ Generate interface for a struct with ifacemaker

This is a development helper program that generates a Golang interface by inspecting the structure methods of an existing .go file. The primary use case is to generate interfaces for gomock, so that gomock can generate mocks from those interfaces. This makes unit testing easier. — @vburenin

ifacemaker -f human.go -s Human -i HumanIface -p humantest -y "HumanIface makes human interaction easy" -c "DONT EDIT: Auto generated"

# human.go
package main

import "fmt"

type Human struct {
  name string
  age  int
}

// Returns the name of our Human.
func (h *Human) GetName() string {
  return h.name
}

// Our Human just had a birthday! Increase its age.
func (h *Human) Birthday() {
  h.age += 1
  fmt.Printf("I am now %d years old!\n", h.age)
}

// Make the Human say hello.
func (h *Human) SayHello() {
  fmt.Printf("Hello, my name is %s, and I am %d years old.\n", h.name, h.age)
}

func main() {
  human := &Human{name: "Bob", age: 30}
  human.GetName()
  human.SayHello()
  human.Birthday()
}

# human_interface.go
// DONT EDIT: Auto generated
package humantest

// HumanIface makes human interaction easy
type HumanIface interface {
  // Returns the name of our Human.
  GetName() string
  // Our Human just had a birthday! Increase its age.
  Birthday()
  // Make the Human say hello.
  SayHello()
}

Requirements

go install github.com/vburenin/ifacemaker@latest

⏫ Generate interface for a struct with interfacer

This tool generates interface for a struct. Can be invoked in go:generate. — @rjeczalik

interfacer -for os.File -as mock.File

// Created by interfacer; DO NOT EDIT

package mock

import (
        "os"
)

// File is an interface generated for "os".File.
type File interface {
        Chdir() error
        Chmod(os.FileMode) error
        Chown(int, int) error
        Close() error
        Fd() uintptr
        Name() string
        Read([]byte) (int, error)
        ReadAt([]byte, int64) (int, error)
        Readdir(int) ([]os.FileInfo, error)
        Readdirnames(int) ([]string, error)
        Seek(int64, int) (int64, error)
        Stat() (os.FileInfo, error)
        Sync() error
        Truncate(int64) error
        Write([]byte) (int, error)
        WriteAt([]byte, int64) (int, error)
        WriteString(string) (int, error)
}

Requirements

go install github.com/rjeczalik/interfaces/cmd/interfacer@latest

⏫ Generate interface for a struct with struct2interface

This is alternative tool for interface generation that is aimed to be faster and leaner. It generates only pointer method receiver methods for a struct. — @reflog

struct2interface -f . -i IDecimal -p fpdecimal -s Decimal -o idecimal.go

Requirements

go install github.com/reflog/struct2interface@latest

⏫ Generate interface for CSV file with structer

This tool generates struct that can read and write CSV file of this struct. Order of fields is hardcoded. — @rjeczalik

structer -f aws-billing.csv -tag json -as billing.Record

# aws-billing.csv
# "InvoiceID","PayerAccountId","LinkedAccountId","RecordType","RecordID","BillingPeriodStartDate","BillingPeriodEndDate","InvoiceDate"
# "Estimated","123456","","PayerLineItem","5433212345","2016/01/01 00:00:00","2016/01/31 23:59:59","2016/01/21 19:19:06"          

# record.go
// Record is a struct generated from "aws-billing.csv" file.
type Record struct {
        InvoiceID              string    `json:"invoiceID"`
        PayerAccountID         int64     `json:"payerAccountID"`
        LinkedAccountID        string    `json:"linkedAccountID"`
        RecordType             string    `json:"recordType"`
        RecordID               int64     `json:"recordID"`
        BillingPeriodStartDate time.Time `json:"billingPeriodStartDate"`
        BillingPeriodEndDate   time.Time `json:"billingPeriodEndDate"`
        InvoiceDate            time.Time `json:"invoiceDate"`
}

// MarshalCSV encodes r as a single CSV record.
func (r *Record) MarshalCSV() ([]string, error) {
    ...
}

// UnmarshalCSV decodes a single CSV record into r.
func (r *Record) UnmarshalCSV(record []string) error {
    ...
}

Requirements

go install github.com/rjeczalik/interfaces/cmd/structer@latest

⏫ Generate decorator for interface with gowrap

GoWrap is a command line tool that generates decorators for Go interface types using simple templates. With GoWrap you can easily add metrics, tracing, fallbacks, pools, and many other features into your existing code in a few seconds. — @hexdigest

gowrap gen -p io -i Reader -t prometheus -o reader_with_metrics.go

Requirements

go install github.com/hexdigest/gowrap/cmd/gowrap@latest

⏫ Modify struct field tags with gomodifytags

This tool makes it easy to update, add or delete the tags and options in a struct field. You can add new tags, update existing tags (such as appending a new key, i.e: db, xml, etc..) or remove existing tags. It's intended to be used by an editor, but also has modes to run it from the terminal. — @fatih

Requirements

go install github.com/fatih/gomodifytags@latest

⏫ Generate code from OpenAPI 3 specification with oapi-codegen

Generate Go client and server boilerplate from OpenAPI 3 specifications. — @deepmap

oapi-codegen --config=config.yaml api.yaml

Requirements

go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

⏫ Generate C-Go Bindings with c-for-go

This project allows to reuse existing C/C++ libraries in your Go applications, by automatically creating c-go bindings for a given set of C headers and the manifest file. We believe in component-based software engineering and think that reusing C/C++ code in Go applications could bring a huge boost to developer's productivity and system's performance. Read more about the motivation: top reasons to use bindings. — @xlab

Generics

⏫ Enum via generics with enum

Type safe enums for Go without code generation or reflection. — @orsinium

type Color enum.Member[string]

var (
  Red    = Color{"red"}
  Green  = Color{"green"}
  Blue   = Color{"blue"}
  Colors = enum.New(Red, Green, Blue)
)

Refactor

⏫ Replace symbol with gofmt

I found this in announcement notice of Go 1.18 for changes to interface{} to any. This can be useful for other refactorings too.

gofmt -w -r 'interface{} -> any' .

⏫ Apply refactoring patches with gopatch

With this tool it is very easy to perform refactorings. It is also possible to organize and maintain your refactoring procedures through patches. — Uber

@@
@@
-import "errors"

-errors.New(fmt.Sprintf(...))
+fmt.Errorf(...)

Example

return errors.New(fmt.Sprintf("invalid port: %v", err))
// becomes
return fmt.Errorf("invalid port: %v", err)

⏫ Keep consistent ordering of imports with goimports

This is official tool for for grouping and sorting imports. However, it has only basic grouping functionality. — Go Core team

goimports -w -local .

Requirements

go install golang.org/x/tools/cmd/goimports@latest

⏫ Keep consistent ordering of imports with gci

This tool splits all import blocks into different sections, now support five section types: standard (e.g. 'fmt'); custom; default; blank; dot. It will keep each section sorted and keep ordering of sections consistent. — @daixiang0

gci write -s standard -s default -s "prefix(github.com/daixiang0/gci)" main.go

// before
package main
import (
  "golang.org/x/tools"
  
  "fmt"
  
  "github.com/daixiang0/gci"
)

// after
package main
import (
    "fmt"

    "golang.org/x/tools"

    "github.com/daixiang0/gci"
)

Requirements

go install github.com/daixiang0/gci@latest

⏫ Keep consistent ordering of imports with goimportx

This tool groups and sorts imports within groups. It keeps consistent ordering of groups. Detection of groups may be not always accurate. — @anqiansong

goimportx --file /path/to/file.go --group "system,local,third"

package main

import (
  "flag"
  "io"
  "log"
  "os"

  "github.com/nikolaydubina/mdpage/page"
  "github.com/nikolaydubina/mdpage/render"
  yaml "gopkg.in/yaml.v3"
)

Requirements

go install github.com/anqiansong/goimportx@latest

Errors

⏫ Errors with return traces with errtrace

Return trace is the path that an error took to return to the user. This can be more illustrative than a typical stack trace that produced the error. This tool has a convenient automatic instrumentation CLI to update your code. — @bracesdev

git ls-files -- '*.go' | xargs errtrace -w

Requirements

use package "braces.dev/errtrace"
instrument code by wrapping errors through all functions with this library

⏫ Errors with stack traces and source fragments with tracerr

This library collects stack traces and pretty prints code fragments. Stack traces induce performance penalty. — @ztrue

package main

import (
  "io/ioutil"

  "github.com/ztrue/tracerr"
)

func main() {
  if err := read(); err != nil {
    tracerr.PrintSourceColor(err)
  }
}

func read() error {
  return readNonExistent()
}

func readNonExistent() error {
  _, err := ioutil.ReadFile("/tmp/non_existent_file")
  // Add stack trace to existing error, no matter if it's nil.
  return tracerr.Wrap(err)
}

⏫ Pretty print panic messages with panicparse

Read panic messages easier. Need to redirect STDERR to this tool with panic stack traces. The tool has HTML output and does lots of deduplication and enhancements. Refer to examples in original repo. — @maruel

go test -v |& pp

Requirements

go install github.com/maruel/panicparse/v2/cmd/pp@latest

⏫ :gift: Generate errors from a spec with zederr

This is a tool for error codes documentation and code generation. You can define all the errors in one YAML file and generate strictly typed error constructors. Error public messages are automatically localized on initialization based on the user locale. — @amanbolat

zederr gen --go-out ./out --spec zederr_spec.yaml

Requirements

go install github.com/amanbolat/zederr/cmd/zederr@latest

Build

⏫ Fetch private dependencies in CI

If you are building in CI (e.g. GitHub Actions), you need to download private repositories. Common way to accomplish this is with job like below.

name: go private modules
env:
  USER: ${{ secrets.USER }}
  TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
run: git config --global url."https://${USER}:${TOKEN}@github.com".insteadOf "https://github.com"

⏫ Show compiler optimization decisions on heap and inlining

Building with -m flag will show decisions of compiler on inlining and heap escape. This can help you to validate your understanding of your code and optimize it.

go build -gcflags="-m -m" . 2>&1 | grep inline

Example

...
./passengerfp.go:25:6: cannot inline (*PassengerFeatureTransformer).Fit: function too complex: cost 496 exceeds budget 80
...
./passengerfp.go:192:6: can inline (*PassengerFeatureTransformer).NumFeatures with cost 35 as: method(*PassengerFeatureTransformer) func() int { if e == nil { return 0 }; count := 6; count += (*transformers.OneHotEncoder).NumFeatures(e.Sex); count += (*transformers.OneHotEncoder).NumFeatures(e.Embarked); return count }
...
./passengerfp.go:238:43: inlining call to transformers.(*OneHotEncoder).FeatureNames
./passengerfp.go:238:43: inlining call to transformers.(*OneHotEncoder).NumFeatures
...
./passengerfp.go:151:7: parameter e leaks to {heap} with derefs=0:
./passengerfp.go:43:11: make(map[string]uint) escapes to heap

⏫ Disable inlining

Usually you may not need it, but can reduce binary size and even improve performance.

go build -gcflags="-l" .

⏫ Aggressive inlining

Usually you may not need it, but can improve performance. This includes mid-stack inlining.

go build -gcflags="-l -l -l -l" .

⏫ :gift: Reduce size of binary

First, get breakdown of how much specific packages take space in your binary. Very often you will see some dependency taking 80% of your binary size, yet often you can have more slim version of it. (e.g. elasticsearch, gcp clients). Then, apply compiler directives to strip away non-essential information.

go build -ldflags="-s -w" .

⏫ Profile-guided optimization

Starting go 1.20 compiler supports Profile-guided optimization. You need to collect profiles and then supply in computation to compiler. You can get improvement in performance by around 4%. Official guideline.

1. store a `pprof` CPU profile with filename default.pgo in the main package directory of the profiled binary
2. build with `go build -pgo=auto``, which will pick up `default.pgo` files automatically.

⏫ Manually disable or enable cgo

Disable cgo with CGO_ENABLED=0 and enable with CGO_ENABLED=1. If you don't, cgo may end-up being enabled or code dynamically linked if, for example, you use some net or os packages. You may want to disable cgo to improve performance, since compiler and runtime would have easier job optimizing code. This also should reduce your image size, as you can have alpine image with less shared libraries.

⏫ Include metadata in binary during compilation with ldflags

You can pass metadata through compiler to your binary. This is useful for including things like git commit, database schema version, integrity hashes. Variables can only be strings.

go build -v -ldflags="-X 'main.Version=v1.0.0'"
go build -v -ldflags="-X 'my/pkg/here.Variable=some-string'"

package main

var Version string

func main() {
  // Version here has some value
  ...
}

⏫ Check if symbol or package is included in binary

This is useful for investigations during performance optimization, security, or compiler work. First spotted in blog.

go tool nm main | grep -Ei '<symbol A>|<symbol B>|...'
go tool nm main | grep -Ei 'golangci-lint|gofumpt'

⏫ Build for Raspberry Pi, Virtual Machine, embedded or normal PC with gokrazy

Turn your Go program(s) into an appliance running on the Raspberry Pi 3, Pi 4, Pi 5, Pi Zero 2 W, or amd64 PCs! gokrazy.org. The surface area for security vulnerabilities is drastically reduced. gokrazy uses its own minimal Go userland instead of a traditional Linux distribution base. The root filesystem is entirely read-only (making persistent malware installation hard) and new versions of the system are installed by overwriting the root file system with the new version. No default shell access: There is neither xz nor OpenSSH on a gokrazy system. Interactive access for debugging is possible, but needs to be explicitly started. — @stapelberg

follow instructions at: https://gokrazy.org/quickstart/

Requirements

go install github.com/gokrazy/tools/cmd/gok@main

⏫ Visualise dependencies size in compiled binaries with go-size-analyzer

A tool for analyzing the dependencies in compiled Golang binaries, providing insight into their impact on the final build. WebAssembly demo: https://gsa.zxilly.dev. — @Zxilly

gsa --web target_binary

Requirements

go install github.com/Zxilly/go-size-analyzer/cmd/gsa@latest

⏫ Make treemap breakdown of Go executable binary with go-binsize-treemap

Useful for studying Go compiler, large projects, projects with C/C++ and cgo, 3rd party dependencies, embedding. However, total size may not be something to worry about for your executable. — @nikolaydubina

go tool nm -size <binary finename> | go-binsize-treemap > binsize.svg

Requirements

go install github.com/nikolaydubina/go-binsize-treemap@latest

⏫ Custom import path

Go can automatically fetch from custom http/https servers using <meta> tag to discover how to fetch code. There are multiple tools that can help set this up. This can help for security and analytics. This is also known as vanity URLs. documentation.

# some notable examples
golang.org/x/exp
go.uber.org/multierr
honnef.co/go/tools/cmd/staticcheck

⏫ Custom import path with govanityurls

Simple HTTP server that lets you host custom import paths for your Go packages. — Google

govanityurls

Requirements

go install github.com/GoogleCloudPlatform/govanityurls@latest

⏫ Custom import path with sally

Simple HTTP server that lets you host custom import paths for your Go packages. — Uber

sally

Requirements

go install go.uber.org/sally@latest

⏫ Custom import path with kkn.fi/vanity

Simple HTTP server that lets you host custom import paths for your Go packages. — @kare

vanity

Requirements

go get kkn.fi/vanity

⏫ Custom import path enforcement

When import path is using custom domain, it is possible to block code from compilation unless it is used. This can help ensure security and prevent breaking changes. documentation.

package pdf // import "rsc.io/pdf"

⏫ Manage multiple Go versions with Goenv

This tool makes it easier for managing multiple Go versions on same host. This works through intercepting Go commands and directing them to the right Go version bin and directory. Official Go documentation on this topic. — @clivern

⏫ Transpile C to Go with cxgo

CxGo is a tool for translating C source code to Go (aka transpiler, source-to-source compiler). It uses cc v3 for preprocessing and parsing C (no clang/gcc dependencies!) and a custom type-checker and AST translation layer to make the best output possible. — @dennwc

cxgo file main.c

Requirements

go install github.com/gotranspile/cxgo/cmd/cxgo@latest

⏫ Transpile Go to Javascript with gopherjs

GopherJS compiles Go code (go.dev) to pure JavaScript code. Its main purpose is to give you the opportunity to write front-end code in Go which will still run in all browsers. — @neelance

gopherjs build <package>

Requirements

go install github.com/gopherjs/gopherjs@v1.19.0-beta1

⏫ Run compile-time function evaluation with prep

By using prep.Comptime, you can evaluate functions at compile time, replacing them with their computed results. — @pijng

go build -a -toolexec="prep" main.go

package main

import (
  "fmt"
  "github.com/pijng/prep"
)

func main() {
  // This will be evaluated at compile-time
  result := prep.Comptime(fibonacci(300))

  fmt.Println("Result:", result)
}

func fibonacci(n int) int {
  fmt.Printf("calculating fibonacci for %d\n", n)

  if n <= 1 {
    return n
  }
  a, b := 0, 1
  for i := 2; i <= n; i++ {
    a, b = b, a+b
  }
  return b
}

Requirements

go install github.com/pijng/prep/cmd/prep@latest

⏫ :gift: Containerize your builds with brewkit

BrewKit is a container-native build system focused on repeatable builds and caching.

brewkit build

local app = "service";

local copy = std.native('copy');

{
    apiVersion: "brewkit/v1",
    targets: {
        all: ['gobuild'],
        
        gobuild: {
            from: "golang:1.24",
            workdir: "/app",
            copy: [
                copy('cmd', 'cmd'),
                copy('pkg', 'pkg'),
            ],
            command: std.format("go build -o ./bin/%s ./cmd/%s", [app])
        }
    }
}

Requirements

go install github.com/ispringtech/brewkit/cmd/brewkit@latest

Assembly

⏫ Get assembly of Go code snippets online

Use godbolt.org to compile and see assembly of short Go code. You can check different platforms and compilers including cgo. This tool is commonly used by C++ community. — @mattgodbolt

⏫ Get Go SSA intermediary representation with ssaplayground

Check what does Go compiler do. Might be useful if you trying to optimize some code or learn more about compiler. https://golang.design/gossa. — @changkun

⏫ View Go assembly interactively with lensm

Understand how Go is compiled better. — @egonelbre

Requirements

go install loov.dev/lensm@main

⏫ View Go assembly with color annotation with pat/disfunc

This tool shows assembly of functions and what lines mean by color. — @maruel

disfunc -f 'nin\.CanonicalizePath$' -pkg ./cmd/nin | less -R

Requirements

go install github.com/maruel/pat/cmd/...@latest

⏫ Generate Go assembly in Go with avo

Write better quality Go assembly quicker in Go language itself. This tool conveniently generates stub for Go code to call your generated assembly. Used by Go core. — @mmcloughlin

//go:build ignore
// +build ignore

package main

import . "github.com/mmcloughlin/avo/build"

func main() {
  TEXT("Add", NOSPLIT, "func(x, y uint64) uint64")
  Doc("Add adds x and y.")
  x := Load(Param("x"), GP64())
  y := Load(Param("y"), GP64())
  ADDQ(x, y)
  Store(y, ReturnIndex(0))
  RET()
  Generate()
}

⏫ Generate AST for code snippets with go/ast

Access Go core AST mechanism to generate AST.

package main

import (
  "go/ast"
  "go/parser"
  "go/token"
)

func main() {
  fs := token.NewFileSet()
  tr, _ := parser.ParseExpr("(3-1) * 5")
  ast.Print(fs, tr)
}

Example

0  *ast.BinaryExpr {
1  .  X: *ast.ParenExpr {
2  .  .  Lparen: -
3  .  .  X: *ast.BinaryExpr {
4  .  .  .  X: *ast.BasicLit {
5  .  .  .  .  ValuePos: -
6  .  .  .  .  Kind: INT
7  .  .  .  .  Value: "3"
8  .  .  .  }
9  .  .  .  OpPos: -
10  .  .  .  Op: -
11  .  .  .  Y: *ast.BasicLit {
12  .  .  .  .  ValuePos: -
13  .  .  .  .  Kind: INT
14  .  .  .  .  Value: "1"
15  .  .  .  }
16  .  .  }
17  .  .  Rparen: -
18  .  }
19  .  OpPos: -
20  .  Op: *
21  .  Y: *ast.BasicLit {
22  .  .  ValuePos: -
23  .  .  Kind: INT
24  .  .  Value: "5"
25  .  }
26  }

⏫ Generate AST for code snippets with go2ast

This is a wrapper around go/ast machinery that makes generating AST easier. — @reflog

echo "a := 1" | go2ast

Example

[]ast.Stmt {
  &ast.AssignStmt {
    Lhs: []ast.Expr {
      &ast.Ident {
        Name: "a",
      },
    },
    Tok: :=,
    Rhs: []ast.Expr {
      &ast.BasicLit {
        ValuePos: 32,
        Kind: INT,
        Value: "1",
      },
    },
  },
}

Requirements

go install github.com/reflog/go2ast@latest

⏫ Visualize Go SSA function using Graphviz with go-ssaviz

This tool provides a visual overview of Go SSA function using Graphviz. This is especially useful in SSA-based static analysis. This tool generates an HTML page that is easy to navigate. [dem