gobreaker - Breaking Change Detection for Go APIs

About

Install

Usage

Features

Examples

Changelog

   __ _  ___  ___ _ __ ___  __ _| | _____ _ __
  / _` |/ _ \| _ \ '__/ _ \/ _` | |/ / _ \ '__|
 | (_| | (_) |  _/ | |  __/ (_| |   <  __/ |
  \__, |\___/|_| |_|  \___|\__,_|_|\_\___|_|
  |___/

gobreaker@v0.1.0:~$ gobreaker --help

gobreaker - Breaking Change Detection for Go APIs

Gobreaker is a Go tool that helps you detect breaking changes in Go APIs using
the golang.org/x/exp/apidiff package. It analyzes Go packages and reports
incompatible changes between versions, helping you maintain API stability and
follow semantic versioning principles.

USAGE:
    gobreaker --old [ref] [OPTIONS]

For more information, see other tabs or visit:
https://github.com/flaticols/gobreaker

gobreaker@v0.1.0:~$ gobreaker --old v1.0.0 --new v1.1.0

• analyzing repository: ./
• comparing v1.0.0 -> v1.1.0
• found 2 incompatible changes
• found 5 compatible changes

Incompatible changes:
  - Removed: func OldFunction()
  - Changed: type Config field Name: changed from string to []string

• breaking changes detected (exit code: 1)

Installation

gobreaker@v0.1.0:~$ # Install using Homebrew

gobreaker@v0.1.0:~$ brew tap flaticols/apps

gobreaker@v0.1.0:~$ brew install flaticols/apps/gobreaker

• Tapping flaticols/apps
• Installing gobreaker from flaticols/apps
• gobreaker 0.1.0 is installed

gobreaker@v0.1.0:~$ # Or install using Go

gobreaker@v0.1.0:~$ go install github.com/flaticols/gobreaker@latest

go: downloading github.com/flaticols/gobreaker v0.1.0
• Successfully installed gobreaker

gobreaker@v0.1.0:~$ # Or build from source

gobreaker@v0.1.0:~$ git clone https://github.com/flaticols/gobreaker.git

gobreaker@v0.1.0:~$ cd gobreaker

gobreaker@v0.1.0:~$ go build -o gobreaker ./cmd/gobreaker

gobreaker@v0.1.0:~$ # Download binary releases from:

https://github.com/flaticols/gobreaker/releases

Usage

gobreaker@v0.1.0:~$ gobreaker --help

USAGE:
    gobreaker [OPTIONS]

OPTIONS:
    -r, --repo       Path to git repository (default: current directory)
    -o, --old        Old reference (branch, tag, or commit) to compare from,
                     or 'latest' to compare latest against HEAD (required)
    -n, --new        New reference (branch, tag, or commit) to compare to (default: HEAD)
    -f, --format     Output format (text, json, markdown) (default: text)
    -q, --quiet      Suppress output
    -v, --version    Print version information and exit
    -h, --help       Show help message

EXIT CODES:
    0 - No breaking changes detected
    1 - Breaking changes found

EXAMPLES:
    # Compare latest tag against HEAD in current directory
    gobreaker --old latest

    # Compare two tags in a specific repository
    gobreaker --repo /path/to/repo --old v1.0.0 --new v2.0.0

    # Compare specific commits
    gobreaker --old abc123 --new def456

    # Compare branch against tag with quiet mode
    gobreaker --old v1.0.0 --new feature-branch --quiet

    # Check breaking changes from main branch
    gobreaker --old main --new HEAD

Features

▸ API Analysis Powered by golang.org/x/exp/apidiff for accurate breaking change detection

▸ Git Reference Compare Compare any two git references: tags, branches, or commits in a repository

▸ Breaking Changes Identifies removed functions, changed signatures, and incompatible changes

▸ Safe Changes Reports compatible additions and improvements to your API

▸ Text Output Clear text-based reports with proper categorization

▸ Clear Reports Well-formatted output with proper indentation and categorization

▸ Latest Tag Support Special 'latest' reference to automatically compare against the most recent tag

▸ CI/CD Ready Exit codes and structured output perfect for automated pipelines

Examples

## Basic Repository Analysis

gobreaker@v0.1.0:~$ gobreaker --old v1.0.0 --new v1.1.0

• analyzing repository: ./
• comparing v1.0.0 -> v1.1.0
• found 0 incompatible changes
• found 3 compatible changes

Compatible changes:
  + Added: func NewHelper(config Config) (*Helper, error)
  + Added: method (*Client) GetTimeout() time.Duration
  + Added: const DefaultTimeout

• no breaking changes detected

## Detecting Breaking Changes

gobreaker@v0.1.0:~$ gobreaker --old v1.0.0 --new v2.0.0

• analyzing repository: ./
• comparing v1.0.0 -> v2.0.0
• found 3 incompatible changes
• found 5 compatible changes

Incompatible changes:
  - Removed: func DeprecatedFunction(s string) error
  - Changed: func Process(input string) error
      to: func Process(ctx context.Context, input string) error
  - Changed: type Config field Timeout: changed from int to time.Duration

Compatible changes:
  + Added: func ProcessWithContext(ctx context.Context, input string) error
  + Added: method (*Client) Close() error
  + Added: field Config.MaxRetries int
  + Added: var ErrTimeout = errors.New("operation timed out")
  + Added: interface Processor

• breaking changes detected (exit code: 1)

## Compare Latest Tag with HEAD

gobreaker@v0.1.0:~$ gobreaker --old latest

• analyzing repository: ./
• comparing v0.1.0 -> HEAD
• found 0 incompatible changes
• found 2 compatible changes

Compatible changes:
  + Added: func ValidateRequest(r *Request) error
  + Added: const MaxRetries = 3

• no breaking changes detected

## CI/CD Integration

gobreaker@v0.1.0:~$ # In your CI/CD pipeline

gobreaker@v0.1.0:~$ gobreaker --repo ./api --old v1.5.0 --new HEAD || {

> echo "Breaking changes detected! Major version bump required."

> exit 1

> }

• analyzing repository: ./api
• comparing v1.5.0 -> HEAD
• found 0 incompatible changes
• found 2 compatible changes
• no breaking changes detected

Changelog

v0.1.0 Initial Release

Added

Core breaking change detection using golang.org/x/exp/apidiff
Support for comparing Go packages between versions, commits, or branches
Multiple output formats: text, JSON, and Markdown
Git integration for analyzing repository changes
Detailed reporting of both compatible and incompatible changes
CLI with comprehensive flags for different use cases
Exit codes for CI/CD integration
Custom diff report writer with proper indentation