Maven Dependency Analysis & Convergence

Source: dependency:tree parameters

By default the tree shows only the winners. With -Dverbose the losers of mediation appear in parentheses, with the reason. On tidepool-report:

The plain tree shows only commons-io:2.11.0 below Commons FileUpload and nothing below Commons CSV except Commons Codec; the verbose tree shows that Commons CSV wanted 2.20.0 and lost. Both versions sit at depth 2, so the tie is broken by declaration order: Commons FileUpload is declared first, so its Commons IO wins. Commons CSV 1.14.1 will run against a Commons IO two minor lines older than the one it was built and tested with. The three Maven releases print exactly the same verbose tree: the output above was identical on 3.10.0, 3.9.16 and 4.0.0-rc-7.

On a real project the tree has hundreds of lines. -Dincludes keeps only the paths that lead to the artifact you ask about:

-Dincludes=... takes a comma-separated list, and each entry is a full filter pattern, so commons-io matches by group and org.apache.commons matches the Commons CSV group. The complementary -Dexcludes removes noise, such as the whole JUnit subtree, when it is the test scope you do not care about; -Dscope=runtime does it more simply by not resolving test dependencies at all.

-DoutputType renders the same tree for other tools. dot is a Graphviz digraph; tgf is Trivial Graph Format (a node list, a # line, then the edges); graphml and json (3.7.0) are for graph viewers and scripts. For the runtime scope of the CLI:

(Trailing spaces on the console lines were trimmed.) Add -DoutputFile=graph.dot to write the graph without the [INFO] prefix. With -DoutputType=tgf the same graph is printed as seven numbered nodes followed by # and six from to scope edges, each node number being a hash of the coordinates.

Source: dependency:tree parameters, outputType

Run over the whole tidepool reactor (output reduced to the plugin lines and warnings; the compiler and resources lines of the forked test-compile were left out):

Three real findings, and one that is not a finding:

The same warnings, in the same order, were produced by Maven 3.9.16 and by 4.0.0-rc-7. (4.0.0-rc-7 additionally prints Unable to find the root directory. Create a .mvn directory... when the project has no .mvn directory.)

Source: Dependency plugin usage: dependency:analyze

-Dverbose also prints the used declared dependencies, and under each used undeclared dependency the classes that were found:

(The two trailing Ignored ... groups that -Dverbose adds were omitted; with no ignore settings they repeat the warnings.) -DoutputXML prints the <dependency> element to paste for the missing dependencies, and -DscriptableOutput prints machine-readable lines starting with a marker (-DscriptableFlag, default $$$%%%) for scripts:

By default the report is only advice. -DfailOnWarning=true (or <failOnWarning> in the POM) turns it into an error:

For a permanent gate bind analyze-only to verify, and ignore the known false positives. The configuration below was added to the parent POM; the two ignore lists name the aggregator and its API (the pattern is groupId:artifactId, with the same optional type:version tail and * wildcards as the other filters):

With the fault in tidepool-cli still there, mvn verify stops exactly at the real problem and the false positives are silent:

The fix is one command, described in Editing the POM from the command line: add and remove; afterwards the same mvn verify prints BUILD SUCCESS and the analyze-only (analyze) execution is silent in all four modules.

Source: Failing the build on dependency analysis warnings

Source: Exclude dependencies from dependency analysis

The plugin does not warn about a few dependencies where bytecode analysis is known to be unreliable, SLF4J being the example the documentation gives. Two causes of false positives are named in the documentation: annotations with source retention, which do not appear in bytecode, and classes loaded by reflection at runtime. For those use usedDependencies or the ignore lists. Because the analysis is on bytecode, it cannot see a dependency that is only needed at runtime (a JDBC driver, a logging backend); declare those with runtime scope and add ignoreUnusedRuntime.

Source: dependency:analyze parameters

Source: dependency:analyze-only parameters

Source: Dependency plugin FAQ: Unused declared dependencies

dependency:copy-dependencies copies the project’s dependency JARs into a directory (default target/dependency, set with -DoutputDirectory); it binds by default to process-sources and is the usual way to assemble a lib/ directory for a distribution (the alternative is an assembly or shade, see Uber JARs with Shade & Assembly). Runtime-scope dependencies of the CLI:

The parameters (the same filter family is shared with unpack-dependencies, go-offline and build-classpath):

Because all files go to one directory, two dependencies with the same file name overwrite each other. graphRoots is the newest addition. Configured in the plugin as a list of <graphRoot> elements with groupId and artifactId, it restricted the copy of tidepool-report to the Commons CSV subtree, and -DincludeScope=compile then produced:

Without graphRoots the same command copies the project’s own four JARs (commons-codec-1.19.0.jar, commons-csv-1.14.1.jar, commons-fileupload-1.5.jar, commons-io-2.11.0.jar). Note that the subtree resolution includes the compile-scope dependencies that the root artifact itself declares and that are not part of the project’s resolved classpath (here two annotation JARs); the output was not analysed further.

dependency:build-classpath prints, or writes with -Dmdep.outputFile=target/cp.txt, the classpath in java -cp form, using the local repository paths. For tidepool-report the file holds four entries separated by the platform separator: commons-fileupload/commons-fileupload/1.5/commons-fileupload-1.5.jar, commons-io/commons-io/2.11.0/commons-io-2.11.0.jar, org/apache/commons/commons-csv/1.14.1/commons-csv-1.14.1.jar and commons-codec/commons-codec/1.19.0/commons-codec-1.19.0.jar (listed relative to the local repository). dependency:resolve lists the resolved files with their Java module names:

list, resolve-sources and resolve-plugins are close relatives. dependency:sources is deprecated in favour of resolve-sources and will be removed.

Source: Dependency plugin usage: dependency:copy-dependencies

Source: dependency:copy-dependencies parameters

Source: dependency:build-classpath parameters

dependency:list-repositories collects the dependencies and prints the repositories the build and its transitive dependencies' POMs use. The documentation says it shows repositories "defined in your settings, poms, and declared in transitive dependency poms":

apache.snapshots is not in the example POM or in settings.xml. It comes from a transitive dependency’s parent chain: the Commons CSV POM inherits from commons-parent, which inherits from the Apache parent POM, and the versions of that parent in the local repository (30 to 32, checked) declare https://repository.apache.org/snapshots as a snapshots-only repository. It is harmless here (snapshots only, never asked for a release) but it is the kind of silently inherited repository that the repository chapter explains how to block; see Repositories, Mirrors & Repository Managers. (central is listed twice; that is how 3.10.0 reports the default and the effective entry.)

Source: Dependency plugin usage: dependency:list-repositories

dependency:go-offline resolves "everything this project is dependent on (dependencies, plugins, reports)" so that mvn -o can run later. The usage page says it is exactly dependency:resolve dependency:resolve-plugins. To show the effect without touching ~/.m2, a private local repository was used (-Dmaven.repo.local=...). With an empty one, an offline build fails at the first thing it needs, the JUnit BOM:

After mvn -Dmaven.repo.local=... dependency:go-offline (BUILD SUCCESS, 160 JARs and 51 MB downloaded in the fresh repository, including the compiler, resources, surefire, jar, clean, install, deploy, enforcer, dependency and even the site plugin) the build gets further, but it still fails offline, at the tests:

go-offline cannot know which Surefire provider a test run will pick, because the provider is chosen at run time from the test classpath and downloaded then. This is the classic reason why "go-offline" builds still reach out to the network. The remedy is to make the runtime download explicit: declare the provider as a dependency of the plugin, and (JUnit 6 on Surefire 3.6.0) the launcher as a test dependency:

Adding only the provider moved the failure to org.junit.platform:junit-platform-launcher:jar:6.1.3 (absent) (165 JARs). With the provider plugin dependency and org.junit.platform:junit-platform-launcher as a test dependency (its version comes from the junit-bom import), a fresh go-offline (166 JARs, 52 MB) was followed by a fully offline build:

Other limits: excludeReactor (default true) skips modules of the current reactor, so the first multi-module build still has to build them; and the site or release plugins resolve their own tools only when they run. The pragmatic alternative, used by many CI pipelines, is to run one full online mvn verify into a cached local repository and reuse that. Gradle’s --offline works from the dependency cache in the same way (see Dependency Locking, Verification & Caching).

Source: Dependency plugin usage: dependency:go-offline

Source: Introduction to repositories: Building Offline

Source: Surefire: JUnit Platform, Provider Selection

dependency:purge-local-repository removes the project’s dependencies from the local repository and, by default, resolves them again (reResolve=true), which is the way to check that a corrupted or half-downloaded artifact is not the problem. It is the one goal here that can destroy data, so the example again uses a private repository. After dependency:resolve into it, the four dependencies of tidepool-report were present (commons-fileupload/1.5, commons-io/2.11.0, commons-csv/1.14.1, commons-codec/1.19.0, plus other Commons IO versions required by the plugins):

(<repo> stands for the private repository path.) The version directories of those four artifacts were gone afterwards; the other Commons IO versions (2.17.0, 2.20.0, 2.21.0) that the plugins use stayed. The same goal with -DresolutionFuzziness=file -Dexclude=commons-io:commons-io deleted only the three JAR files of the other artifacts and left the .pom, checksum and _remote.repositories files, and Commons IO untouched.

Outside a project, -DmanualInclude=commons-io:commons-io:2.11.0 printed Deleting 1 manual dependency from <repo> and removed the 2.11.0 directory. Never run these goals with -Dmaven.repo.local pointing at your shared ~/.m2 unless you mean it.

Source: Dependency plugin usage: dependency:purge-local-repository

Source: dependency:purge-local-repository parameters

The same failing POM was changed in four ways, each time re-running both rules.

The direct-dependency result is the one that surprises people: declaring the version you want does not make the tree converge. Only dependency management or an exclusion removes the competing path. A fifth option, upgrading the stale library, helps only if the newer release has caught up: commons-fileupload 1.6.0 depends on Commons IO 2.19.0, which is still below Commons CSV’s 2.20.0, and both rules still failed.

With <excludes><exclude>commons-io:commons-io</exclude></excludes> inside each rule, both rules passed on the failing POM: that is the "known and accepted" escape hatch; keep such lists short and commented. The rules also run on a test scope only if you remove test from excludedScopes. Other rules that guard the graph (bannedDependencies, banDuplicatePomDependencyVersions, requireReleaseDeps, requirePluginVersions) are covered on The Enforcer Plugin.

Source: Enforcer: dependencyConvergence, filtering