depstat

depstat is a CLI for analyzing Go module dependency graphs, with a strong focus on large multi-module repos such as Kubernetes, etcd, and containerd.

Installation

go install github.com/kubernetes-sigs/depstat@latest

Quick Start

cd <your-go-module>
depstat stats          # dependency counts and max depth
depstat list           # sorted list of all dependencies
depstat graph          # write graph.dot (render with: dot -Tsvg graph.dot -o graph.svg)
depstat cycles         # detect dependency cycles
depstat why <module>   # explain why a dependency is present

Kubernetes, etcd, and containerd

For real usage against Kubernetes, etcd, and containerd (including multi-module --mainModules, diff analysis, and archived dependency checks), see:

• docs/cli-kubernetes.md
• docs/cli-etcd.md
• docs/cli-containerd.md

This guide mirrors the patterns used in Kubernetes test-infra Prow jobs.

Commands

Run depstat help for full command help.

• depstat stats: dependency counts and maximum depth (--json, --csv, --verbose, --split-test-only, --mainModules, --dir)
• depstat list: sorted list of all dependencies in the current module (--json, --split-test-only, --mainModules, --dir)
• depstat graph: dependency graph (--dot, --json, --output, --dep/-p, --show-edge-types, --mainModules, --dir)
• depstat cycles: detect dependency cycles (--json, --mainModules, --dir)
• depstat why <dependency>: explain why a dependency is present (--json, --dot, --svg, --mainModules, --dir)
• depstat diff <base-ref> [head-ref]: compare dependency changes between git refs (--json, --dot, --svg, --stats, --verbose, --split-test-only, --vendor, --vendor-files, --mainModules, --dir)
• depstat archived: detect archived upstream GitHub repositories (--json, --github-token-path, --mainModules, --dir)
• depstat completion [bash|zsh|fish|powershell]

The --mainModules / -m flag accepts a comma-separated list of module names to treat as "main" modules. This is essential for multi-module repositories like Kubernetes, where both the root module and all staging modules should be treated as first-party code rather than external dependencies. Without -m, depstat auto-detects a single main module from go list -m.

Use depstat stats --split-test-only to separate totals into test-only and non-test dependency sections (classified via go mod why -m).

depstat diff includes a high-signal Summary section and reports Version Changes by default.
Use depstat diff --stats for a compact before/after/delta stats report without listing dependencies. With --vendor, it also reports vendor module additions/removals/version changes and Vendor-only Removals (modules removed from vendor but still present in the module graph).
With --vendor-files, it additionally reports added/deleted vendored Go files.

Project Goals

depstat is developed under SIG Architecture code organization efforts to make dependency changes easier to evaluate across Kubernetes and other CNCF projects.

Community Contact Information

• #k8s-code-organization on Kubernetes Slack

Code of Conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.