great-docs api-diff

Compare the public API between two versions.

great-docs api-diff [OPTIONS] OLD_VERSION NEW_VERSION

Analyzes how the API surface changed between OLD_VERSION and NEW_VERSION (git tags). Detects added, removed, and changed symbols, tracks parameter changes, and flags breaking changes with migration hints.

Use HEAD as NEW_VERSION to compare against the working tree.

Full --help output

Usage: great-docs api-diff [OPTIONS] OLD_VERSION NEW_VERSION

  Compare the public API between two versions.

  Analyzes how the API surface changed between 'OLD_VERSION' and 'NEW_VERSION'
  (git tags). Detects added, removed, and changed symbols, tracks parameter
  changes, and flags breaking changes with migration hints.

  Use 'HEAD' as 'NEW_VERSION' to compare against the working tree.

  Examples:
    great-docs api-diff v0.1.0 v0.2.0
    great-docs api-diff v1.0.0 HEAD
    great-docs api-diff v0.9.0 v1.0.0 --json
    great-docs api-diff v0.1.0 v0.2.0 --graph
    great-docs api-diff v0.1.0 HEAD --timeline
    great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs
    great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --changes-only
    great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --table
    great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --table --html

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --package TEXT            Python package name (auto-detected from
                            pyproject.toml if omitted)
  --json                    Output results as JSON
  --graph                   Show dependency graph as Mermaid diagram for the
                            NEW version
  --timeline                Show API surface growth timeline across all
                            version tags
  --symbol TEXT             Track a single symbol across versions (shows
                            signature history)
  --changes-only            With --symbol, show only versions where the symbol
                            changed
  --table                   With --symbol, show parameter evolution as a table
  --html                    With --symbol --table, output HTML (with
                            disclosure wrapper)
  --help                    Show this message and exit.

Arguments

OLD_VERSION: TEXT

Required.

NEW_VERSION: TEXT

Required.

Options

--project-path: DIRECTORY

Path to your project root directory (default: current directory)

--package: TEXT

Python package name (auto-detected from pyproject.toml if omitted)

--json

Output results as JSON

--graph

Show dependency graph as Mermaid diagram for the NEW version

--timeline

Show API surface growth timeline across all version tags

--symbol: TEXT

Track a single symbol across versions (shows signature history)

--changes-only

With --symbol, show only versions where the symbol changed

--table

With --symbol, show parameter evolution as a table

--html

With --symbol --table, output HTML (with disclosure wrapper)

Examples

  great-docs api-diff v0.1.0 v0.2.0
  great-docs api-diff v1.0.0 HEAD
  great-docs api-diff v0.9.0 v1.0.0 --json
  great-docs api-diff v0.1.0 v0.2.0 --graph
  great-docs api-diff v0.1.0 HEAD --timeline
  great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs
  great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --changes-only
  great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --table
  great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --table --html