https://github.com/siom79/japicmp
Comparison of two versions of a jar archive
https://github.com/siom79/japicmp
api-documentation api-management change-management change-tracker comparison java
Last synced: about 6 hours ago
JSON representation
Comparison of two versions of a jar archive
- Host: GitHub
- URL: https://github.com/siom79/japicmp
- Owner: siom79
- License: apache-2.0
- Created: 2013-09-29T11:28:08.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2026-05-21T19:16:56.000Z (2 months ago)
- Last Synced: 2026-05-22T02:50:24.279Z (2 months ago)
- Topics: api-documentation, api-management, change-management, change-tracker, comparison, java
- Language: Java
- Homepage: https://siom79.github.io/japicmp
- Size: 12.3 MB
- Stars: 769
- Watchers: 24
- Forks: 114
- Open Issues: 70
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
The website is located at [https://siom79.github.io/japicmp](https://siom79.github.io/japicmp/).
japicmp is a tool to compare two versions of a jar archive:
``` bash
java -jar japicmp-.0-jar-with-dependencies.jar -n new-version.jar -o old-version.jar
```
It can also be used as a library:
```java
JarArchiveComparatorOptions comparatorOptions = new JarArchiveComparatorOptions();
JarArchiveComparator jarArchiveComparator = new JarArchiveComparator(comparatorOptions);
List jApiClasses = jarArchiveComparator.compare(oldArchives, newArchives);
```
japicmp is available in the Maven Central Repository:
[](https://central.sonatype.com/artifact/com.github.siom79.japicmp/japicmp)
``` xml
com.github.siom79.japicmp
japicmp
0.26.1
```
A maven plugin allows you to integrate the checks into your build:
``` xml
com.github.siom79.japicmp
japicmp-maven-plugin
0.26.1
japicmp
japicmp-test-v1
${oldversion}
jar
${project.build.directory}/${project.artifactId}-${project.version}.${project.packaging}
verify
cmp
```
A Sonar Qube plugin integrates the results from the japicmp analysis into your code quality report: [sonar-japicmp-plugin](https://github.com/siom79/sonar-japicmp-plugin).
By using the available Ant task, you can also integrate japicmp into your Ant build files:
``` xml
```
[melix](https://github.com/melix) has developed a [gradle plugin](https://github.com/melix/japicmp-gradle-plugin) for japicmp.
## Online-Version
There is an online version of japicmp that lets you compare two artifacts from the maven central repository
without installing the tool first. Just click [this](https://www.japicmp.de) link and give it a try.
## MCP-Server
The [japicmp MCP server](https://github.com/siom79/japicmp-mcp-server) exposes japicmp's API comparison capabilities as
a tool for AI assistants that support the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
It allows AI agents such as Claude to compare two versions of a Maven artifact directly from a conversation — resolving
both JARs from Maven Central and returning a structured Markdown compatibility report, including binary and source
compatibility status, a semantic versioning verdict, and a detailed diff of every changed class, method, constructor,
and field.
## Motivation
Every time you release a new version of a library or a product, you have to tell your clients or customers what
has changed in comparison to the last release. Without the appropriate tooling, this task is tedious and error-prone.
This tool/library helps you to determine the differences between the java class files that are contained in two given
jar archives.
This library does not use the Java Reflection API to compute the differences, as the usage of the Reflection API makes
it necessary to include all classes the jar archive under investigation depends on are available on the classpath.
To prevent the inclusion of all dependencies, which can be a lot of work for bigger applications, this library makes
use of the [javassist](https://www.javassist.org/) library to inspect the class files.
This way you only have to provide the two jar archives on the command line (and eventually libraries that contain
classes/interfaces you have extended/implemented).
This approach also detects changes in instrumented and generated classes. You can even evaluate changes in class file attributes (like synthetic) or annotations.
The comparison of annotations makes this approach suitable for annotation-based APIs like JAXB, JPA, JAX-RS, etc.
The goal of this project is to provide a fast and easy to use API comparison for Java. Therefore it does not aim
to integrate change tracking of other types of artifacts (configuration files, etc.) as a generic implementation means
to make compromises in terms of performance and ease of usage. japicmp for example compares two archives with about 1700 classes each
in less than one second and therewith can be easily integrated in each build.
## Features
* Comparison of two jar archives without the need to add all of their dependencies to the classpath.
* Differences are printed on the command line in a simple diff format.
* Differences can optionally be printed as [Markdown](https://www.markdownguide.org/), XML or HTML file.
* Per default private and package protected classes and class members are not compared. If necessary, the access modifier of the classes and class members to be
compared can be set to public, protected, package or private.
* Per default all classes are tracked. If necessary, certain packages, classes, methods or fields can be excluded or explicitly included. Inclusion and exclusion is also possible based on annotations.
* All changes between all classes/methods/fields are compared. japicmp differentiates between source and binary compatible changes (as described in the [Java Language Specification](http://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html) and the [OpenJDK-Wiki](https://wiki.openjdk.org/spaces/csr/pages/32342052/Kinds+of+Compatibility)).
* All changes between annotations are compared, hence japicmp can be used to track annotation-based APIs like JAXB, JPA, JAX-RS, etc.
* A maven plugin is available that allows you to compare the current artifact version with some older version from the repository.
* The option `--semantic-versioning` tells you which part of the version you have to increment in order to follow [semantic versioning](http://semver.org/).
* If a class is serializable, changes are evaluated regarding the [Java Object Serialization Specification](http://docs.oracle.com/javase/7/docs/platform/serialization/spec/serialTOC.html).
* Per default synthetic classes and class members (e.g. [bridge methods](https://docs.oracle.com/javase/tutorial/java/generics/bridgeMethods.html)) are hidden. They can be listed by using the option `--include-synthetic`.
* The maven plugin allows project-specific filtering and reports using a custom [Groovy](https://groovy-lang.org/) script.
## Downloads
You can download the latest version from the [release page](https://github.com/siom79/japicmp/releases) or directly from the [maven central repository](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22japicmp%22).
## Buy me a coffee
If you like japicmp and would like to do me a favor for all the work I've done over
the years, please consider buying me a coffee [here](https://www.buymeacoffee.com/mmois).
# Development
## Reports
Use the maven site plugin (`mvn site`) to generate the following reports:
* findbugs
* checkstyle
* japicmp
## Release
This is the release procedure:
* Create a branch named release-v0.XX.X
* Update ReleaseNotes.md.
* If necessary: Set the release version in maven using [this Action](https://github.com/siom79/japicmp/actions/workflows/mvn-set-version.yml) on the release branch
* Increment version in README.md / Site-Report by running [this Action](https://github.com/siom79/japicmp/actions/workflows/increment-version.yml) on the release branch
* Run release [Action](https://github.com/siom79/japicmp/actions/workflows/release.yml)
* Login to [Central repository](https://central.sonatype.com/publishing)
* Download released artifact from staging repository.
* Close and release staging repository if sanity checks are successful.
* Update maven site report with [Action](https://github.com/siom79/japicmp/actions/workflows/mvn-site.yml) on the release branch
* Run Github Release [Action](https://github.com/siom79/japicmp/actions/workflows/gh-release.yml) on the tag
* Merge release branch into master
If the release fails, the version must be reverted and the tag created during the release has to be deleted:
```bash
mvn versions:set -DnewVersion=-SNAPSHOT
mvn versions:commit
git push
git push --delete origin japicmp-base-
```
Afterward, the release action can be executed again.
## Contributions
Pull requests are welcome, but please follow these rules:
* The basic editor settings (indentation, newline, etc.) are described in the `.editorconfig` file (see [EditorConfig](http://editorconfig.org/)).
* Provide a unit test for every change.
* Name classes/methods/fields expressively.
* Fork the repo and create a pull request (see [GitHub Flow](https://guides.github.com/introduction/flow/index.html)).
## Website
The website can be generated by running this github [Action](https://github.com/siom79/japicmp/actions/workflows/mvn-site.yml)
on the tag.
It uses the [maven-scm-publish-plugin](https://maven.apache.org/plugins/maven-scm-publish-plugin/index.html) to
generate the site report and push it to the [gh-pages](https://github.com/siom79/japicmp/tree/gh-pages) branch.