Find the Go packages affected by a Git change.
Why ripples · Installation · Quick Start · Impact Graph · Documentation
English · 简体中文
ripples uses the Go AST, type information, and a declaration dependency graph to find Go packages that are directly or transitively affected between two Git revisions. It follows actual references to changed declarations instead of returning every package that imports a changed package.
The stable output is <module-relative path>.<package name>:
cmd/server.main
internal/order.order
payment.payment
In a large Go repository with multiple services, a change to a shared package can trigger tests, builds, and deployment checks for many services.
Common approaches have different limitations:
git diffonly finds directly changed files and cannot identify transitively affected callers.- Import-graph analysis works at package granularity; any package that imports the changed package may be considered affected.
- Running the full CI pipeline avoids deciding the impact scope in advance, but increases wait time and compute cost.
ripples analyzes changes at declaration granularity: it first identifies changed functions, methods, types, or variables, then propagates impact through actual references to produce the packages that need attention.
CI workflows can map these packages to:
- Tests or build jobs to run
- Affected binaries and services
- PR labels
- Components that need deployment or regression verification
ripples can also generate an impact graph that shows how a change propagates through package references, helping reviewers explain changes and assess their risk.
- Declaration-level analysis: detects added, removed, and modified functions, methods, types, fields, variables, constants, and
initfunctions. - Direct and transitive propagation: walks actual declaration references and call relationships in reverse.
- Interface implementation resolution: resolves concrete implementations from call sites and value flow without mixing unrelated implementations.
- Common Go syntax coverage: follows function values, closures, containers, type assertions, generics,
go,defer, and initialization relationships. - Build input awareness: detects effective changes to build tags, CGo,
//go:directives,go:embed,go.mod, andgo.work. - CI-friendly output: emits stable sorted results with persistent caching, JSON, summaries, and DOT graphs.
See Analysis for the complete coverage and static-analysis boundaries.
Install the latest version with Go:
go install github.com/jimyag/ripples@latest
ripples --versionYou can also download raw amd64 and arm64 binaries for Linux, macOS, and Windows from GitHub Releases.
Analyzing a target project still requires git, a compatible Go toolchain, and a Go module where go list ./... succeeds. See Installation and Usage for platform download commands and complete runtime requirements.
Analyze the latest commit:
ripples -repo . -old HEAD~1 -new HEADExample output:
cmd/server.main
internal/order.order
payment.payment
-repo points to the Go module being analyzed and may be a repository root or a module subdirectory inside a monorepo. -old and -new must resolve to commits. ripples analyzes committed Git trees and does not include uncommitted working tree changes.
See Installation and Usage for options, output formats, and cache configuration.
Emit a reverse package graph with dot, then convert it to SVG with Graphviz:
ripples -repo . -old HEAD~1 -new HEAD -output dot > impact.dot
dot -Tsvg impact.dot -o impact.svgA red border marks a package containing changed declarations. Arrows point to packages that use it:
| Document | Contents |
|---|---|
| Installation and Usage | Installation, CLI options, output formats, DOT, and caching |
| Analysis | Analysis model, supported Go usage patterns, and explicit boundaries |
| Architecture | Revision snapshots, symbol graph, value flow, reverse propagation, cache, and concurrency |
| GitHub Actions | Release download, checksum verification, caching, and downstream job mapping |
task deps
task citask lint uses golangci-lint to check every Go package and test file. Run task --list-all for other common tasks. Local builds are written to bin/ripples.
Pushing a v* tag runs GoReleaser and uploads raw platform binaries plus checksums.txt without tar or zip archives. Run task release-snapshot before publishing to validate the configuration and local artifacts.
This project is licensed under the GNU General Public License v3.0.