# changelog

Source: https://apigenie.pl/techdocs/reference/cli-changelog

Builds the changelog of an OpenAPI, Swagger, AsyncAPI, Protobuf or GraphQL file
from its git history.

## Usage

```sh
apigenie changelog [OPTIONS] FILE
```

## Description

This command compares the consecutive versions of an OpenAPI, Swagger,
AsyncAPI, Protobuf or GraphQL file stored in a git repository, and describes
what changed for API consumers: added, removed, deprecated and changed
operations, servers and metadata, for AsyncAPI the channels, for Protobuf the
methods, messages, enums and services, and for GraphQL the fields of the root
operation types and the types and directives of the schema. Each change is rated
as breaking, non-breaking or non-functional, with the same rules as the
`diff` command.

The command runs `git`, which must be installed. The file must be in a git
repository, and only its committed versions are compared.

### Revisions

By default, the changelog has an entry for every commit that changes the file
or one of the files it references. Commits that change neither, and commits
whose changes don't affect the API (e.g. reformatting), are left out. With
`--revisions tags`, the changelog has an entry for every release tag instead,
comparing each release with the previous one.

```sh
# every commit
apigenie changelog api/openapi.yaml

# every release tagged v1.0.0, v1.1.0, ..., and the changes made since the last one
apigenie changelog api/openapi.yaml --revisions tags --tag-pattern 'v*' --unreleased
```

Only the first parent of merge commits is followed, so a merged branch appears
as a single entry: its merge commit.

The first version of the file starts the changelog, and lists the operations
the API had then. With `--from`, the changelog starts after the given
revision instead, e.g. the last release. `--to` sets the last revision, which
is `HEAD` by default.

```sh
apigenie changelog api/openapi.yaml --from v2.0.0
```

### Files split into many documents

References to other files (e.g. `$ref: 'schemas/pet.yaml'`) are followed in
each version, so a change of a referenced file is a change of the API. By
default, the commits changing the file or the files it references in the last
revision are compared. `--path` selects the commits changing other paths
instead, e.g. files that were referenced in older versions only:

```sh
apigenie changelog api/openapi.yaml --path api
```

References to URLs and to files outside the repository aren't supported.

### Changes of operations

With `--by operation`, the changes are grouped by operation, with the history
of each one, newest first. `--operation` selects the operations to show, by
method and path, by path or by operation id, and can be repeated:

```sh
apigenie changelog api/openapi.yaml --by operation --operation 'GET /pets' --operation createPet
```

Operations are identified by their method and path, so moving an operation to
another path shows as removing it and adding a new one.

### Swagger files

Swagger 2.0 files are recognized by their `swagger` field in the last
revision. Their changelog lists the added, removed, deprecated and changed
operations, by method and path like OpenAPI ones, with the rules of the
`commands.diff.swagger` section of the configuration. Changes of the host, the
base path, the schemes, the media types and the security of the whole API are
metadata. A change of a path item other than of its operations, e.g. of the
parameters its operations share, is shown under each of its operations.
Changes of definitions, shared parameters and responses are shown under the
operations using them. Files the specification references are bundled in each
version, as for OpenAPI files.

```sh
apigenie changelog api/swagger.yaml --by operation --operation 'GET /pets'
```

### AsyncAPI files

AsyncAPI 3.x files are recognized by their `asyncapi` field in the last
revision. Their changelog lists the added, removed and changed operations,
channels and servers, and the changed metadata, with the rules of the
`commands.diff.asyncapi` section of the configuration.

An operation is shown by its action and the address of its channel, followed
by its id, e.g. `send user/signedup` (sendUserSignedUp). Messages belong to
channels, so a change of a message, e.g. of its payload, is a change of its
channel, and also of the operations using the channel. Operations are
identified by their id: renaming one shows as removing it and adding a new
one. `--operation` selects operations by id, by action and address (e.g.
`'send user/signedup'`), or by the address of their channel:

```sh
apigenie changelog api/asyncapi.yaml --by operation --operation 'receive user/signedup'
```

### Protobuf files

Protobuf (proto3) files are recognized by their `.proto` extension. Their
changelog lists the added, removed and changed methods of the services, named
by their service and their own name (e.g. `Customers.GetCustomer`), then the
messages, enums, services and extended messages declared at the top level of
the file, with the rules of the `commands.diff.protobuf` section of the
configuration. A change of the package is shown like a version change (e.g.
`shop.v1 → shop.v2`), and changes of the imports, the file options and the
comment of the syntax statement as metadata.

The file is compared on its own, as by `diff`: the files it imports aren't
read, and the types they declare are compared by their names. So by default,
only the commits changing the file are compared. A method is identified by the
names of its service and its own: renaming either shows as removing the method
and adding a new one. A change of a service other than of its methods, e.g. of
its options, is listed under the service. `--operation` selects methods by
their full name, by their own name or by the name of their service:

```sh
apigenie changelog api/shop.proto --by operation --operation Customers.GetCustomer
```

See [Protobuf files](/techdocs/reference/cli-diff#protobuf-files) of the
`diff` command for how changes are rated.

### GraphQL files

GraphQL schema files are recognized by their `.graphql`, `.graphqls` or `.gql`
extension. Their operations are the fields of the root operation types, named
by their type and their own name (e.g. `Query.books` or `Mutation.addBook`).
The changelog lists the added, removed and changed operations, then the
scalars, object types, interfaces, unions, enums, input objects and directive
definitions of the schema, with the rules of the `commands.diff.graphql`
section of the configuration. Changes of the root operation types, of the
description of the schema and of its directives are shown as metadata. A
schema has no version, so none is shown.

The file is compared on its own, as by `diff`: types defined in other files
are compared by their names. So by default, only the commits changing the file
are compared. The root operation types are those named by the schema
definition, or the types named `Query`, `Mutation` and `Subscription`. An
operation is identified by the names of its type and its field: renaming
either shows as removing the operation and adding a new one. A change of a
root operation type other than of its fields, e.g. of its description, is
listed under the object types. `--operation` selects operations by their full
name, by their field name, by the name of their type, or by their operation
type (`query`, `mutation` or `subscription`):

```sh
apigenie changelog api/schema.graphql --by operation --operation Query.books
```

See [GraphQL files](/techdocs/reference/cli-diff#graphql-files) of the
`diff` command for how changes are rated.

### Invalid versions

Versions that can't be read, e.g. because of a YAML, Protobuf or GraphQL syntax error, are skipped
with a warning, and the next version is compared with the last valid one.

## Options

| Option                         | Description                                                                                              |
| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `--revisions commits\|tags`    | Compares every commit that changes the file (default), or every release tag.                             |
| `--tag-pattern PATTERN`        | Glob pattern of the release tags, e.g. `v*`. All tags by default.                                         |
| `--tag-sort version\|date`     | Orders the release tags by version numbers in their names (default), or by date.                         |
| `--unreleased`                 | With `--revisions tags`, adds an entry with the changes made after the last release.                      |
| `--from REVISION`              | The revision the changelog starts after, e.g. a tag.                                                     |
| `--to REVISION`                | The last revision, `HEAD` by default.                                                                    |
| `--path PATH`                  | With `--revisions commits`, compares the commits changing these paths. Can be repeated. By default, the file and the files it references; for Protobuf and GraphQL, the file only. |
| `--by revision\|operation`     | Groups the changes by revision (default), or by operation (for Protobuf, by method; for GraphQL, by field of a root operation type). |
| `--operation OPERATION`        | Shows the changes of an operation only: `'GET /pets'`, a path or an operation id (OpenAPI and Swagger); for AsyncAPI, `'send ADDRESS'`, a channel address or an operation id; for Protobuf, `Service.Method`, a method name or a service name; for GraphQL, `Query.books`, a field name, a root operation type name, or `query`, `mutation` or `subscription`. Can be repeated. |
| `--formatter FORMATTER`        | `stylish` (default), `markdown`, `html` or `json`.                                                       |
| `--config FILE`                | Configuration file; its `diff` settings (`diff.swagger` for Swagger, `diff.asyncapi` for AsyncAPI, `diff.protobuf` for Protobuf, `diff.graphql` for GraphQL) decide the severity of the changes. |
| `--git PATH`                   | Path to the git program.                                                                                 |
| `-o`, `--output FILE`          | Writes the changelog to a file instead of printing it.                                                    |

## Output

The `markdown` formatter prints a changelog that can be published as is:

```markdown
## v2.0.0 (2026-01-05)

Release 2.0 (a25ac8d, Jane Doe)

**Contains breaking changes.**

Version: 1.1.0 → 2.0.0

### Removed

- `GET /pets/{id}` (getPet) **breaking**

### Deprecated

- `GET /pets` (listPets) **breaking**
```

The `json` formatter prints the full data, including every change of the
modified operations, for further processing: an object with `formatVersion`
(the version of the format, which changes only when a member is removed or
changes meaning, see [Compatibility](/techdocs/reference/cli-compatibility)),
`spec`, `warnings`, and `entries` (one per revision, newest first) or, with
`--by operation`, `operations` (`methods` for Protobuf) with the history of
each one. Its JSON Schema is
[apigenie-changelog-report.json](https://apigenie.pl/schemas/apigenie-changelog-report.json).

```json5
{
  "formatVersion": 1,
  "spec": "petstore.yaml",
  "entries": [
    {
      "revision": { "id": "a25ac8d…", "shortId": "a25ac8d", "label": "v2.0.0", "tag": "v2.0.0", "author": "Jane Doe", "date": "2026-01-05", "subject": "Release 2.0" },
      "initial": false,
      "version": "2.0.0",
      "severity": "breaking",
      … metadata, servers, operations …
    }
  ],
  "warnings": []
}
```

## Exit status

The command exits with 0 when it prints the changelog, even if it has breaking
changes, and with 2 when git can't be run, the file isn't in a git repository,
a revision doesn't exist, or no revision changes the file. See the [exit statuses](/techdocs/reference/cli-overview#exit-status) shared by the three binaries.