gobreaker

A command-line tool that detects breaking changes in Go APIs by comparing different versions of your code.

Overview

gobreaker analyzes your Go packages and reports incompatible API changes between versions, helping you maintain backward compatibility and follow semantic versioning principles. It uses golang.org/x/exp/apidiff under the hood to perform accurate API comparisons.

Installation

go install github.com/flaticols/gobreaker/cmd/gobreaker@latest

Or build from source:

git clone https://github.com/flaticols/gobreaker.git
cd gobreaker
go build -o gobreaker ./cmd/gobreaker

Usage

gobreaker [OPTIONS] <base-ref> [repo-path]

Arguments

• base-ref (required): The base reference to compare against (branch, tag, or commit SHA)
• repo-path (optional): Path to the git repository (defaults to current directory)

Options

• -o, --output <format>: Output format - text (default), json, or markdown
• -v, --version: Print version information and exit
• -h, --help: Show help message

Examples

# Compare current branch against main in current directory
gobreaker main

# Compare against a specific tag in a different repository
gobreaker v1.0.0 /path/to/repo

# Output results as JSON
gobreaker -o json main

# Output results as Markdown (useful for PR comments)
gobreaker --output markdown main

# Check version
gobreaker --version

Output Formats

Text (default)

Shows a human-readable report of breaking changes with proper indentation.

JSON

Outputs structured JSON data for programmatic consumption.

Markdown

Generates a Markdown-formatted report suitable for documentation or pull request comments.

What It Detects

gobreaker identifies various types of breaking changes including:

• Removed or renamed exported functions, types, methods, or variables
• Changed function signatures
• Removed or changed struct fields
• Interface method changes
• Type definition changes

Development

Building

go build -o gobreaker ./cmd/gobreaker

Running Tests

go test ./...

Claude Code Plugin

gobreaker is also available as a Claude Code plugin, bringing breaking-change detection directly into your AI-assisted workflow.

Install from marketplace

/plugin marketplace add flaticols/gobreaker
/plugin install gobreaker

Usage

# Compare default branch vs working directory
/gobreaker:check

# Compare a specific tag against working directory
/gobreaker:check v0.0.1

# Compare two git refs
/gobreaker:check v0.0.1 v0.0.2

# Compare filesystem paths
/gobreaker:check -p /old/pkg /new/pkg

The skill runs gobreaker on your Go project and returns a structured summary: compatible/breaking status, list of changes, semver bump recommendation, and migration hints.

Note: The gobreaker binary must be in your PATH. Install it with go install github.com/flaticols/gobreaker/cmd/gobreaker@latest.

License

See LICENSE file for details.