jdx diff

IDE equivalent: Public-API diff + binary-compat warnings (upgrades)

Compare the public API of two artifacts and report every difference, most breaking first: removed members, narrowed visibility, changed descriptors, final/abstract/static flips, throws clauses and Kotlin-visible changes. Each finding names one rule (MEMBER_REMOVED, RETURN_TYPE_CHANGED, ...) so a caller can filter on the rule rather than on prose. Exits 0 whenever the comparison ran, whatever it found — add --fail-on breaking (or --fail-on any) to exit 1 in a pipeline. Exits 3 on a bad spec or flag, 5 when an artifact cannot be read. Each spec is a jar file, class directory, glob, or Maven coordinate (with --fetch). No workspace is needed.

Usage#

jdx diff [<options>] <oldartifact> <newartifact>

Example#

$ jdx diff com.google.code.gson:gson:2.11.0 com.google.code.gson:gson:2.14.0 --fetch
api diff com.google.code.gson:gson:2.11.0 -> com.google.code.gson:gson:2.14.0 (public surface)
info  TYPE_ADDED  com.google.gson.internal.GsonTypes
info  TYPE_ADDED  com.google.gson.internal.bind.JsonElementTypeAdapter
info  MEMBER_ADDED  com.google.gson.FieldNamingStrategy#alternateNames(java.lang.reflect.Field)
info  MEMBER_ADDED  com.google.gson.internal.ConstructorConstructor#get(com.google.gson.reflect.TypeToken, boolean)
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#BIG_DECIMAL_FACTORY
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#BIG_INTEGER_FACTORY
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#DOUBLE_STRICT
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#FLOAT_STRICT
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#LAZILY_PARSED_NUMBER_FACTORY
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#LONG_AS_STRING
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#atomicLongAdapter(com.google.gson.TypeAdapter)
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#atomicLongArrayAdapter(com.google.gson.TypeAdapter)
info  MEMBER_ADDED  com.google.gson.internal.bind.TypeAdapters#javaTimeTypeAdapterFactory()
info  MEMBER_ADDED  com.google.gson.internal.sql.SqlTypesSupport#SQL_TYPE_FACTORIES
info  MEMBER_ADDED  com.google.gson.stream.JsonReader#getNestingLimit()
info  MEMBER_ADDED  com.google.gson.stream.JsonReader#setNestingLimit(int)
info  FIELD_CONSTANT_VALUE_CHANGED  com.google.gson.internal.GsonBuildConfig#VERSION: "2.11.0" -> "2.14.0"
0 breaking · 0 suspicious · 17 informational · 2 types added · 0 types removed
warning MULTI_RELEASE_VARIANT: in com.google.code.gson:gson:2.11.0: multi-release gson-2.11.0.jar serves version-specific variants for this JDK (21)
warning MULTI_RELEASE_VARIANT: in com.google.code.gson:gson:2.14.0: multi-release gson-2.14.0.jar serves version-specific variants for this JDK (21)
warning UNNAMEABLE_CLASS: in com.google.code.gson:gson:2.11.0: unnameable class name (empty name segment in [, Gson, Preconditions]): com/google/gson/internal/$Gson$Preconditions.class
warning UNNAMEABLE_CLASS: in com.google.code.gson:gson:2.11.0: unnameable class name (empty name segment in [, Gson, Types]): com/google/gson/internal/$Gson$Types.class
warning UNNAMEABLE_CLASS: in com.google.code.gson:gson:2.11.0: unnameable class name (empty name segment in [, Gson, Types, GenericArrayTypeImpl]): com/google/gson/internal/$Gson$Types$GenericArrayTypeImpl.class
warning UNNAMEABLE_CLASS: in com.google.code.gson:gson:2.11.0: unnameable class name (empty name segment in [, Gson, Types, ParameterizedTypeImpl]): com/google/gson/internal/$Gson$Types$ParameterizedTypeImpl.class
warning UNNAMEABLE_CLASS: in com.google.code.gson:gson:2.11.0: unnameable class name (empty name segment in [, Gson, Types, WildcardTypeImpl]): com/google/gson/internal/$Gson$Types$WildcardTypeImpl.class
source: com.google.code.gson:gson:2.11.0 (bytecode)
source: com.google.code.gson:gson:2.14.0 (bytecode)
next: jdx members com.google.gson.internal.GsonTypes

Real output — this example ran against the current jdx when the page was built.

Options#

Option	Description
`--visibility=(public\|all)`	Which declarations to compare: public (the default — public and protected types and members, the surface a consumer compiles against) or all (every declared type and member, for refactors and mod/mixin work).
`--include-synthetic`	Compare bridge/synthetic members too, hidden by default.
`--severity=(all\|suspicious\|breaking)`	How much of the report to print: all (the default), suspicious (breaking and suspicious), or breaking only. The per-severity tally always describes the whole comparison, never only what was printed.
`--fail-on=(none\|breaking\|any)`	Turn the report into a process status: breaking exits 1 when a breaking change is present, any exits 1 on any difference. Without it a successful comparison always exits 0.
`--limit=<int>`	Maximum findings shown (default 200); the rest become a truncation footer. The tail this cuts is by construction the least severe.
`--fetch`	Allow downloading a Maven coordinate from Maven repositories (Central by default, --repo to add mirrors). Without it, coordinates resolve from ~/.gradle/caches and ~/.m2 only.
`--repo=<text>`	Maven repository base URL for --fetch (repeatable). Tried in flag order before Maven Central, which stays last as the fallback.
`--json`	Emit machine-readable JSON instead of human-readable text (same information, D-007).
`--no-color`	Disable ANSI colors even on a TTY (piped output is always plain).
`-h, --help`	Show this message and exit

Arguments#

Argument	Description
`<oldartifact>`	Baseline artifact: jar, class dir, glob, or group:artifact:version.
`<newartifact>`	Candidate artifact, compared against the baseline.

Full help text#

Show jdx diff --help

$ jdx diff --help
Usage: jdx diff [<options>] <oldartifact> <newartifact>

  Compare the public API of two artifacts and report every difference, most breaking first: removed members, narrowed visibility, changed descriptors, final/abstract/static flips, throws clauses and Kotlin-visible changes. Each finding names one rule (MEMBER_REMOVED, RETURN_TYPE_CHANGED, ...) so a caller can filter on the rule rather than on prose. Exits 0 whenever the comparison ran, whatever it found — add --fail-on breaking (or --fail-on any) to exit 1 in a pipeline. Exits 3 on a bad spec or flag, 5 when an artifact cannot be read. Each spec is a jar file, class directory, glob, or Maven coordinate (with --fetch). No workspace is needed.

Options:
  --visibility=(public|all)             Which declarations to compare: public (the default — public and protected types and members, the surface a consumer compiles against) or all (every declared type and member, for refactors and mod/mixin work).
  --include-synthetic                   Compare bridge/synthetic members too, hidden by default.
  --severity=(all|suspicious|breaking)  How much of the report to print: all (the default), suspicious (breaking and suspicious), or breaking only. The per-severity tally always describes the whole comparison, never only what was printed.
  --fail-on=(none|breaking|any)         Turn the report into a process status: breaking exits 1 when a breaking change is present, any exits 1 on any difference. Without it a successful comparison always exits 0.
  --limit=<int>                         Maximum findings shown (default 200); the rest become a truncation footer. The tail this cuts is by construction the least severe.
  --fetch                               Allow downloading a Maven coordinate from Maven repositories (Central by default, --repo to add mirrors). Without it, coordinates resolve from ~/.gradle/caches and ~/.m2 only.
  --repo=<text>                         Maven repository base URL for --fetch (repeatable). Tried in flag order before Maven Central, which stays last as the fallback.
  --json                                Emit machine-readable JSON instead of human-readable text (same information, D-007).
  --no-color                            Disable ANSI colors even on a TTY (piped output is always plain).
  -h, --help                            Show this message and exit

Arguments:
  <oldartifact>  Baseline artifact: jar, class dir, glob, or group:artifact:version.
  <newartifact>  Candidate artifact, compared against the baseline.

Real output — this example ran against the current jdx when the page was built.

Learn more#

Guide: API diff for upgrades · All commands