go-depend

Analyzes Go package dependencies in a multi-module monorepo and produces directed graphs in DOT format for Graphviz visualization. Recursively traces both internal and external dependencies, grouping packages by module in subgraph clusters.

Installation

go install github.com/kcross-ctoken/go-depend/cmd/go-depend@latest

Or build from source:

git clone https://github.com/kcross-ctoken/go-depend.git
cd go-depend
go build -o go-depend ./cmd/go-depend

Usage

go-depend -module <path> -repo <path> [options]

Required Parameters

Flag	Description
-module	Path to the module directory (contains go.mod)
-repo	Path to the monorepo root containing go.mod files

Optional Parameters

Flag	Description	Default
-main	Path to a specific main.go file (auto-detected if omitted)	auto
-short	Use short package names in graph labels (last 2 path segments)	false
-strip	Prefix to strip from import paths in labels	""
-internal	Only include packages internal to the monorepo	false
-external N	Max depth into external dependency chains (0=none, 1=direct only, -1=unlimited)	0
-testdeps	Show only the dependency tree of test files in the module	false
-o	Output file path (omit for stdout)	stdout

Examples

Auto-detect main function and generate DOT to stdout:

go-depend -module /path/to/myrepo/src/services/orders -repo /path/to/myrepo

Generate with short names, write to file:

go-depend -module src/services/orders -repo . -short -o orders.dot

Specify a particular main file when a module has multiple:

go-depend -module src/services/orders -repo . -main src/services/orders/cmd/server/main.go

Strip a common prefix for cleaner labels:

go-depend -module src/services/orders -repo . \
  -strip "github.com/myorg/myrepo/src" -o orders.dot

Include direct external dependencies:

go-depend -module src/services/orders -repo . -external 1 -short

Generate and render as PNG (requires Graphviz):

go-depend -module src/services/orders -repo . -short | dot -Tpng -o orders.png

Show test-only dependency tree:

go-depend -module src/services/orders -repo . -testdeps -short

Multiple main functions

If a module contains more than one func main() and -main is not provided, the tool will exit with a list of the files found:

Error: multiple func main() found in src/services/orders, use -main to specify one:
  src/services/orders/cmd/server/main.go
  src/services/orders/cmd/worker/main.go

How It Works

1. Scans the module directory for Go files containing func main()
2. Discovers all go.mod files in the monorepo to build a module map
3. Runs go list -json -m all from the entry module to discover external module locations
4. Recursively walks all import dependencies using go/parser and go/ast
5. Skips Go standard library packages (fmt, os, net/http, etc.)
6. Generates a DOT directed graph using emicklei/dot with subgraph clustering by module

Visual Styling

Packages are visually distinguished in the generated graph:

Package Type	Shape	Color	Cluster Style
Main entry point	Double octagon	Light blue	—
Internal (monorepo) package	Box	Light yellow	Yellow filled cluster
External (third-party) package	Box (dashed)	Light grey	Grey dashed cluster

Packages belonging to the same Go module are grouped into subgraph clusters, making it easy to see module boundaries.

Dependencies

• emicklei/dot — DOT graph generation
• golang.org/x/mod — go.mod file parsing