# great-docs api-diff


Compare the public API between two versions.


``` bash
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.


<span class="gd-details-chevron" aria-hidden="true"></span>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

``` bash
  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
```