Cross-Project Dependency Graph: 51 Go Projects#

Summary#

Across 51 major Go projects, four dependencies appear in virtually every codebase: stretchr/testify (universal), golang.org/x/ extended stdlib packages (near-universal), spf13/cobra+pflag (dominant CLI), and prometheus/client_golang (standard metrics). The dependency graph clusters into distinct ecosystems — HashiCorp, Kubernetes/CNCF, and Charm — while a long tail of projects maintains radical minimalism (3–10 deps) as an explicit design philosophy. The most instructive dimension is not what projects depend on, but how they manage dependency growth: forking, vendoring, replace directives, and “own-the-critical-path” strategies each represent distinct philosophies worth understanding.

Taxonomy#

Tier 1: Universal (found in 45–51 projects)#

github.com/stretchr/testify#

• Projects using it: Every project except the Go standard library itself (P22), GORM (uses only stdlib testing), PocketBase (stdlib only), and wireguard-go (stdlib only). Estimated 47/51 projects.
• How it works: Assertion library with assert (non-failing), require (fatal on failure), mock (gomock-style), and suite (xUnit-style) sub-packages. The assert.Equal call style is de facto standard Go testing idiom.
• When it’s appropriate: Any project that has more than trivial tests. The ergonomic improvement over raw t.Error/t.Fatal is substantial.

golang.org/x/crypto, x/net, x/sync, x/sys, x/text#

• Projects using it: 49–51/51 depending on the sub-package.
• How it works: The “extended standard library” — packages that needed faster release cadences than the stdlib, but are maintained by the Go team and co-versioned with Go releases. Key sub-packages: x/crypto/ssh, x/net/http2, x/sync/errgroup, x/sys/unix, x/text/unicode.
• When it’s appropriate: These are effectively mandatory for any non-trivial networked or CLI program. Projects that claim “no third-party deps” almost always still include golang.org/x/*.

github.com/google/uuid#

• Projects using it: ~35–40 of 51 projects wherever unique IDs are generated.
• How it works: UUID v1/v4/v5 generation. No notable alternatives have emerged — the ecosystem has fully converged.
• When it’s appropriate: Any project that needs globally unique identifiers.

Tier 2: Near-Universal (found in 25–44 projects)#

github.com/spf13/cobra + github.com/spf13/pflag#

• Projects using it: kubernetes, moby, etcd, hugo, traefik, caddy, cockroach, consul, dapr, k3s, helm, istio, argo-cd, sqlc, viper (transitively), frp, headscale, rclone, restic, delve, pocketbase, crush, gh, buildkite-agent, gitea, cobra itself, and many others. Estimated 35–40/51.
• How it works: Cobra provides a command-tree with automatic help, completion, and flag-set management. pflag replaces stdlib flag with POSIX/GNU-style --long and -s short flags, plus --no-flag negation.
• When it’s appropriate: Any multi-command CLI binary. The only strong alternative in the corpus is urfave/cli (gogs, temporal, gitea partially), mitchellh/cli (consul, vault, nomad — HashiCorp legacy), and stdlib flag (nats-server, air, fzf — deliberate minimalism).

Notable absentees: nats-server (stdlib flag only, documented policy), fzf (stdlib flag), gorm (library, no CLI), echo (library), wireguard-go (stdlib flag), PocketBase (cobra present), NATS (explicit no-cobra policy).

github.com/prometheus/client_golang#

• Projects using it: kubernetes, moby, etcd, prometheus itself, grafana, traefik, caddy, cockroach, minio, consul, vault, nomad, dapr, k3s, helm, istio, argo-cd, tekton-pipeline, beego, drone, buildkite-agent, syncthing, rclone, headscale, tailscale, frp, temporal, and more. Estimated 38–42/51.
• How it works: Provides the /metrics HTTP endpoint in Prometheus exposition format. The prometheus.Counter, Gauge, Histogram, Summary primitives are the de facto standard.
• When it’s appropriate: Any server that needs operational observability. Notably absent in: fzf, cobra, gorm, echo, wireguard-go, air, PocketBase, nats-server (uses its own internal metrics).

google.golang.org/grpc + google.golang.org/protobuf#

• Projects using it: kubernetes, moby, etcd, prometheus, grafana, traefik, dapr, k3s, helm, istio, argo-cd, tekton-pipeline, sqlc, beego, consul, vault, nomad, temporal, headscale, buildkite-agent, crush (MCP protocol). Estimated 25–30/51.
• How it works: gRPC is Google’s RPC framework over HTTP/2 with Protocol Buffers for serialization. It provides streaming, deadline propagation, and interceptor chains that parallel HTTP middleware.
• When it’s appropriate: Service-to-service communication in distributed systems. Web frameworks (gin, echo, fiber, buffalo) avoid it by design; CLI tools and single-binary tools (fzf, restic, nats-server) also avoid it.

gopkg.in/yaml.v3 (and sigs.k8s.io/yaml)#

• Projects using it: kubernetes, etcd, helm, k3s, istio, argo-cd, traefik, consul, vault, nomad, dapr, grafana, hugo, gin, beego, syncthing, rclone, headscale, gh, gitea, drone, buildkite-agent, viper, restic, and others. Estimated 35–40/51.
• How it works: The canonical Go YAML parser. v3 adds anchors and aliases support. sigs.k8s.io/yaml is a thin wrapper that converts YAML to JSON before unmarshaling — a Kubernetes convention for uniform type handling.
• When it’s appropriate: Config-heavy projects, Kubernetes-adjacent tooling, anything with structured data files. The transition from gopkg.in/yaml.v3 to go.yaml.in/yaml/v3 (a module path change after the upstream went inactive) is visible in the corpus: cobra, viper, helm, syncthing, delve use the new path.

go.opentelemetry.io/otel (+ OTLP exporter stack)#

• Projects using it: kubernetes, caddy, consul, vault, nomad, dapr, istio, argo-cd, tekton-pipeline, beego, buildkite-agent, headscale, temporal, and newer projects. Estimated 18–22/51.
• How it works: Vendor-neutral distributed tracing and metrics API. Projects adopt OTel as the forward-looking standard replacing Jaeger and Zipkin direct integrations.
• When it’s appropriate: Production services that need distributed tracing. The OTel adoption curve is visible: projects started pre-2020 (moby, consul, vault) may have Jaeger or OpenTracing directly; projects started or modernized post-2021 increasingly use OTel.

Tier 3: Common (found in 10–24 projects)#

go.uber.org/zap#

• Projects using it: kubernetes, etcd, dapr, helm, istio, minio, consul (via go-hclog bridge), tekton-pipeline, temporal, sqlc (indirect via TiDB parser), and others. Estimated 15–18/51.
• How it works: High-performance structured logger with a zap.Logger that uses reflection-free field encoding. Counterpart: zerolog (headscale, drone, caddy via indirect), logrus (moby, traefik, k3s, argo-cd), slog (echo, viper).
• When it’s appropriate: Performance-critical services where logging throughput matters.

github.com/sirupsen/logrus#

• Projects using it: moby, traefik, k3s, argo-cd, gitea, and older projects generally. Estimated 12–15/51.
• How it works: Structured logger with hooks. The dominant Go logger from 2015–2019, now in maintenance mode.
• When it’s appropriate: Legacy codebases that haven’t migrated. The ecosystem is clearly moving away from logrus toward zap, zerolog, and stdlib slog.

github.com/google/go-cmp#

• Projects using it: kubernetes, moby, etcd, traefik, tekton-pipeline, argo-cd, istio, gin, gh, headscale, tailscale, restic, consul, dapr, sqlc. Estimated 20–25/51.
• How it works: Deep equality comparison with cmp.Options for custom transformers. Used in tests where reflect.DeepEqual is insufficient (unexported fields, protobuf messages, etc.).
• When it’s appropriate: Test code with complex struct comparisons, especially Kubernetes-ecosystem projects where proto types need custom equality.

github.com/fsnotify/fsnotify#

• Projects using it: kubernetes, fyne, viper, hugo, consul, nomad, vault, gitea, air, and any project with config hot-reload. Estimated 15–20/51.
• How it works: Cross-platform filesystem event watching. Used by Viper for config file watching (transitively pulling it into all Viper users).
• When it’s appropriate: Dev tools (air), config reload (viper users), asset watch (hugo).

github.com/klauspost/compress#

• Projects using it: etcd, minio, rclone, grafana, traefik, restic, nats-server, syncthing. Estimated 12–15/51.
• How it works: Fast compression library covering zstd, gzip, snappy, s2, and more, with SIMD acceleration. Significantly faster than stdlib compress for the same formats.
• When it’s appropriate: Storage and data-intensive projects where compression throughput matters.

github.com/hashicorp/golang-lru/v2#

• Projects using it: consul, vault, terraform, nomad, gitea, restic, syncthing, beego. Estimated 10–12/51.
• How it works: Thread-safe LRU/ARC/2Q cache implementations. Widely used as a simple in-memory cache without Redis.
• When it’s appropriate: In-process caching of computed values, session data, DNS results.

k8s.io/client-go (and k8s.io/apimachinery, k8s.io/api)#

• Projects using it: kubernetes itself, moby (partial), traefik, dapr, k3s, helm, istio, argo-cd, tekton-pipeline, frp (fringe use). Estimated 12–15/51.
• How it works: The Kubernetes Go client. Informers, listers, dynamic clients, and workqueue form the Kubernetes operator pattern.
• When it’s appropriate: Any project deploying to or managing Kubernetes clusters.

Tier 4: Domain-Specific Clusters#

HashiCorp Cluster (consul, vault, terraform, nomad, dapr partially)#

The five HashiCorp core projects share a family of in-house libraries that creates a tight dependency sub-graph:

• hashicorp/go-hclog — structured logger (shared by all four)
• hashicorp/raft — Raft consensus (consul + nomad)
• hashicorp/serf — gossip protocol (consul + nomad)
• hashicorp/go-memdb — in-memory database (consul + nomad)
• hashicorp/go-plugin — gRPC-over-subprocess plugins (vault + terraform)
• hashicorp/hcl/v2 + go-cty — HCL config language (vault + terraform + nomad)
• hashicorp/mitchellh/cli — CLI framework (consul + vault + nomad + terraform; NOT cobra)
• armon/go-metrics — metrics abstraction (consul + nomad)

This cluster is deliberately self-contained: HashiCorp built alternatives to cobra, viper, zap, and even raft-boltdb rather than adopting community equivalents. The resulting graph is coherent within the cluster but diverges from Go community norms.

Kubernetes/CNCF Cluster (kubernetes, moby, etcd, prometheus, traefik, k3s, helm, istio, argo-cd, tekton-pipeline, dapr)#

• k8s.io/api, k8s.io/apimachinery, k8s.io/client-go — core k8s types
• sigs.k8s.io/yaml, sigs.k8s.io/controller-runtime — ecosystem tools
• k8s.io/klog/v2 + go-logr/logr — k8s logging interfaces
• go.opentelemetry.io/otel — now the CNCF telemetry standard
• gogo/protobuf vs google/protobuf — coexist due to k8s’s historical gogo-protobuf use
• github.com/onsi/ginkgo + gomega — BDD testing framework used in k8s itself and nearby

This cluster is the most internally consistent: once you use k8s.io/apimachinery, you implicitly inherit ~20 further k8s.io/* packages plus Kubernetes-affiliated sigs.k8s.io packages.

Charmbracelet/TUI Cluster (gh, fzf, crush)#

• charmbracelet/bubbletea + charmbracelet/lipgloss + charmbracelet/bubbles — TUI framework
• muesli/termenv — terminal color and feature detection
• mattn/go-runewidth, mattn/go-isatty — terminal utilities
• rivo/tview (gh only, for table views) — widget-based TUI
• charm.land/fang, charm.land/huh (crush) — Charm’s newer ecosystem

fzf predates this cluster (uses tcell directly); gh is partially migrated to it; crush is fully built on it. The cluster is growing but still minority.

Author-Ecosystem Packages (horizontal pattern)#

Several projects create micro-ecosystems where a single author controls a suite of dependencies:

• Hugo: bep/logg, bep/overlayfs, bep/lazycache, bep/simplecobra, bep/imagemeta, bep/godartsass — ~15 packages by Hugo’s lead maintainer
• MinIO: klauspost/reedsolomon, klauspost/compress, klauspost/pgzip, klauspost/cpuid — 4 packages by a single contributor who is also a core MinIO developer
• frp: fatedier/golib, fatedier/yamux — author’s own utility and networking packages
• gogs: gogs/git-module, gogs/chardet, gogs/cron, gogs/go-libravatar — author maintains the entire peripheral ecosystem
• cobra+viper: spf13/pflag, spf13/afero, spf13/cast — all from the same author, designed to compose

This pattern reduces external breakage risk but concentrates maintenance on a small number of individuals.

Dependency Count Distribution#

Key insight: Minimalist projects (fzf, nats-server, echo, gorm, wireguard-go, cobra) have 2–15 deps and often document a policy against adding more. Infrastructure projects (kubernetes, vault, cockroach, consul, rclone) have 100–220 deps because they integrate many external systems. The distribution is bimodal, not normal — few projects have 50–70 deps.

Trends#

1. The sqlite3 CGo-Free Migration#

A clear trend across 2022–2025 projects: replacing mattn/go-sqlite3 (CGo) with modernc.org/sqlite (pure-Go transpiled C) or ncruces/go-sqlite3 (WASM-based). Projects: pocketbase, syncthing, temporal, crush, grafana, helm (v4), headscale. Motivation: cross-compilation without a C toolchain, simpler Docker builds, no CGo overhead in CI. Projects that haven’t migrated (pop, beego, gogs partially) retain both CGo and pure-Go versions simultaneously.

2. OTel Displacing OpenTracing and Direct Jaeger#

Pre-2022 projects used Jaeger directly or OpenTracing; post-2022 projects use go.opentelemetry.io/otel exclusively. Beego still ships both. The OTel adoption rate is high enough that it should now be considered the default for any new service.

3. Logrus → Zap → Zerolog → slog#

A four-generation progression in Go logging:

• Gen 1 (2015–2018): logrus (moby, traefik, k3s, argo-cd)
• Gen 2 (2018–2021): zap (kubernetes, etcd, dapr, temporal, minio)
• Gen 3 (2020–2023): zerolog (headscale, drone, caddy-indirect)
• Gen 4 (2022+): stdlib slog (echo, viper, crush via fang)

The generation a project uses is a reliable proxy for when its core logging infrastructure was last designed.

4. YAML v3 Path Migration#

gopkg.in/yaml.v3 → go.yaml.in/yaml/v3 is a module path migration (same code, new canonical path). The split is now visible in the dependency graph: newer projects use go.yaml.in; older ones use gopkg.in. This migration is incomplete across the corpus.

5. AWS SDK v1 → v2 Migration#

Many projects carry both aws/aws-sdk-go (v1, context-free, monolithic) and aws-sdk-go-v2 (modular, context-aware). Both are present simultaneously in vault and grafana, indicating ongoing migrations that take years. Projects started after 2021 use v2 only.

6. gRPC Protobuf Fork Resolution (gogo → google)#

github.com/gogo/protobuf appeared heavily in pre-2019 Go projects (kubernetes, etcd, moby, consul) for its performance over the official SDK. The official google.golang.org/protobuf has since closed the performance gap. Projects started post-2020 use only the official library; older projects carry both in their dependency graphs (moby, etcd, consul, istio, argo-cd) — a multi-year migration debt visible across the entire cloud-native dependency graph.

Vendoring Patterns#

Five strategies across the corpus:

1. Full Vendor (5 projects)#

kubernetes, moby, tekton-pipeline, delve, go (standard library).

Motivation:

• kubernetes: Generated vendor via hack/update-vendor.sh; 34 sub-modules require coordinated pinning; security review process mandates auditable dep source
• moby: Supply chain security; Docker is a security-critical binary; historical practice predating Go modules
• tekton-pipeline: Kubernetes heritage; CI builds without network access
• delve: Security-critical debugger (runs as root); reproducibility; full audit surface
• go (std): src/vendor/ for stdlib; build must be reproducible without external network

2. Replace-Directives-as-Vendoring (3 projects)#

k3s (73 replace directives pointing to k3s-io forks), Tailscale (8+ strategic forks), traefik (4 containous forks).

Motivation: Achieves patch control without vendoring the full tree. Replace directives let the project maintain surgical patches to upstream while the module proxy handles the rest. K3s uses this for its entire Kubernetes dependency tree — every k8s.io/* package points to a k3s-patched fork.

3. Module Proxy Without Vendor (40+ projects)#

The majority: consul, vault, nomad, terraform, dapr, helm, istio, argo-cd, minio, rclone, prometheus, grafana, and most others.

Motivation: Standard modern Go modules practice. go.sum provides integrity guarantees; CI caches the module download. Vendoring would add hundreds of MB for large dependency trees.

4. Strict Minimal Deps + No Vendor (4 projects)#

nats-server, wireguard-go, echo, cobra.

Motivation: These projects have so few dependencies that the vendor question is moot. NATS’s CONTRIBUTING.md explicitly discourages new dependencies. wireguard-go has 5 deps. echo has 3. The philosophy is: minimize the dep count and vendoring becomes unnecessary.

5. Library Protocol (no vendoring by policy) (6 projects)#

gorm, cobra, viper, echo, fiber, fyne.

Motivation: Libraries should not vendor because doing so conflicts with the host application’s own module graph. Library consumers choose their vendoring strategy.

Common Patterns#

The Extended Standard Library#

golang.org/x/crypto, x/net, x/sync, x/sys, x/text are so universally adopted they function as an extended standard library. Projects that claim “zero third-party dependencies” almost always depend on at least one. The Go project itself vendors them (src/vendor/). These packages should be treated as safe baseline dependencies, not third-party risk.

Ecosystem Convergence on Three CLI Patterns#

Three stable CLI patterns have emerged:

1. cobra+pflag (dominant, ~70% of projects): Any multi-command CLI
2. urfave/cli (secondary, ~10%): Projects preferring functional handler registration
3. hashicorp/cli (HashiCorp-only, ~5%): mitchellh’s framework, consistent within HashiCorp
4. stdlib flag (minimalism, ~15%): fzf, nats-server, wireguard-go, air — deliberate simplicity

The “Own the Critical Path” Pattern#

Projects that depend heavily on a performance-sensitive path fork and maintain the underlying library:

• MinIO: owns minio/mux, minio/cli, minio/xxml, klauspost/*
• Caddy: Matt Holt owns certmagic, acmez, zerossl, libdns
• frp: owns fatedier/golib, fatedier/yamux
• Hugo: bep owns 15 peripheral packages
• Tailscale: owns wireguard-go, golang-x-crypto, netlink, go-winio forks

The pattern signals: when correctness or performance is existential to the project’s value proposition, you cannot afford to wait for upstream.

Dual-Library Anti-Pattern (Version Migration Debt)#

Many projects carry two versions of the same library simultaneously, visible as technical debt in go.mod:

This pattern is a reliable indicator of project age and migration debt. Newer projects (crush, nats-server, wireguard-go, pocketbase) show none of it.

Best Practices#

1. Adopt golang.org/x/ freely; it is not a third-party risk. The extended stdlib packages are co-maintained by the Go team and release with Go. Treating them as third-party is both inaccurate and counterproductive.

2. Use stretchr/testify for test assertions. The ecosystem has converged. Writing custom comparison helpers when testify exists wastes contributor time and reduces readability. The only valid exception: security-critical or zero-dep libraries (gorm, cobra, nats-server) where the absence is a feature.

3. For new services, default to go.opentelemetry.io/otel for observability and go.uber.org/zap or stdlib slog for logging. Logrus is maintenance-mode; direct Jaeger/Zipkin is obsolete. OpenTracing is deprecated.

4. Choose modernc.org/sqlite over mattn/go-sqlite3 for new SQLite integrations. The CGo-free pure-Go implementation now has production validation (grafana, pocketbase, syncthing, temporal). The cross-compilation benefits are significant for CLI distribution.

5. Use replace directives sparingly and document them. K3s’s 73 replace directives are a distribution-engineering necessity; frp’s yamux replace is documented with a resolution plan. Undocumented replace directives (like sqlc’s forked MySQL driver) create invisible dependency debt.

6. Dependency count correlates with integration scope, not quality. rclone (107 deps) and nats-server (10 deps) are both exemplary projects. The right dep count is the one that serves the project’s scope without cross-contamination.

Anti-Patterns#

1. Importing a Large Module for One Package (Air → Hugo)#

Air imports github.com/gohugoio/hugo solely for hugo/watcher/filenotify, pulling in 80+ transitive dependencies including Dart Sass bindings and WebP support. This inflates Air’s go.sum from ~20 entries to ~105. The fix: extract or inline just the needed package. This anti-pattern appears to some degree in several projects but Air is the most egregious example.

2. All Plugins Compiled In (Vault, Gin, Beego)#

Vault compiles all built-in plugins into the main binary because they need go-plugin (subprocess) but their types are direct imports. Gin bundles three JSON backends (sonic, go-json, json-iterator) always. Beego includes 5 niche storage backends as direct deps. The result: every user pays for features they don’t use. The alternative (separate modules, build tags, or explicit imports) adds user complexity but reduces binary size.

3. Dual ORM Transitional State (gogs, pop)#

Gogs runs both gorm.io/gorm (30 files) and xorm.io/xorm (15 files) simultaneously during migration. Pop ships both lib/pq and pgx/v5. These states are stable for years because refactoring database access is risky. They represent an ongoing category of Go maintenance debt.

4. Forked Anthropic/OpenAI SDKs (crush)#

Crush uses charmbracelet/openai-go and charmbracelet/anthropic-sdk-go instead of the official SDKs. While deliberate (custom streaming, model abstraction), this creates a lag risk: upstream API additions require a fork update, and new model capabilities won’t be available until the Charm team merges them.

5. Heavy Kubernetes Import for Light Use (frp)#

frp imports k8s.io/apimachinery primarily for the sets package (a typed set implementation), which transitively pulls in the entire Kubernetes API machinery. This is a lightweight use of a heavyweight package — the fix would be a standalone generic sets library.

Exemplars#

wireguard-go — The Radical Minimalist#

5 direct dependencies for a production WireGuard VPN tunnel: golang.org/x/crypto, golang.org/x/sys, golang.org/x/net, gvisor.dev/gvisor (scoped to one package), golang.zx2c4.com/wintun. No logging framework, no CLI framework, no test framework. Every dependency has a clear security justification. The standard to aspire to for security-critical code.

nats-server — Documented Minimalism#

10 direct dependencies for a production message broker serving millions of messages/second. All five deps are either NATS-ecosystem (nkeys, jwt, nuid) or near-stdlib (klauspost/compress, golang.org/x/crypto, x/sys, x/time). CONTRIBUTING.md documents the no-new-deps policy. The binary is < 20MB and starts in < 1ms.

cobra — The Library Model#

4 direct dependencies for the dominant Go CLI framework. pflag is a sibling co-designed library; mousetrap is a Windows-only UX fix; go-md2man and go-yaml are documentation tooling. No test framework, no logging, no config. Sets the bar for how a library should think about its dependency surface.

kubernetes — The Structured Vendor#

110 direct dependencies, fully vendored, managed via hack/update-vendor.sh. The go.mod is generated (not hand-edited). Dependency updates go through structured security review. This is vendoring as a governance practice, not just a technical choice — appropriate for the most-deployed infrastructure software in the world.

k3s — Replace-as-Patch-Control#

~100 direct dependencies with 73 replace directives pointing every k8s.io/* package to github.com/k3s-io/kubernetes. This encodes an entire distribution engineering strategy in go.mod: K3s is Kubernetes with surgical patches, and every patched dependency is declared explicitly. A teaching example of how replace enables downstream distributions without full forks.

Note on fyne and crush#

fyne (P10): A GUI framework with rendering-specific deps (go-gl, go-text, fyne-io/*) that are unique in the corpus. Its fsnotify, BurntSushi/toml, and urfave/cli/v2 appearances show the framework remains connected to mainstream Go tooling despite the unusual domain.

crush (P51): Consult analysis/results/P51-crush--ai-development-profile.md for context on its AI-assisted development signals. From a dependency perspective, crush is notable for: (1) forked Anthropic/OpenAI SDKs, (2) full Charm ecosystem adoption (no other project uses charm.land/*), (3) MCP protocol as a first-class dependency, and (4) dual CGo-free SQLite backends. These choices are domain-specific (AI coding assistant) rather than Go ecosystem anomalies.