Running Maven (CLI)

compiler, dependency, jar and help are plugin prefixes. Maven resolves a prefix by looking, in order, at the plugins already declared in the POM and its parents, and then at the pluginGroups of settings.xml, which by default contain org.apache.maven.plugins and org.codehaus.mojo, using the repository metadata of those groups. A prefix that cannot be found fails with a message that lists exactly where Maven looked:

(Only the first error line is shown; it is followed by the standard hint lines.) The tilde stands for the home directory. Plugin prefixes are explained, with the pluginGroups setting, in the Maven guide.

Source: Maven guide: Introduction to Plugin Prefix Mapping

A typo in a phase name is reported together with the full list of valid phases, which is the quickest way to see them all:

(Only the first error line is shown.) The Maven help page behind [Help 1] is LifecyclePhaseNotFoundException. A real prefix with a wrong goal name lists the goals the plugin does have:

(Again the first error line.) The third mistake comes from using an option on a release that does not have it. The -UA option of Maven 3.10 (below) does not exist on Maven 3.9.16, and that release does not reject it as an unknown option: it reads -UA as -U followed by -A, and the second letter is taken as a phase name:

(First error line only.)

Source: Maven guide: Introduction to the Build Lifecycle, Lifecycle Reference

Source: Maven guide: Introduction to Plugin Prefix Mapping

-B (--batch-mode) runs Maven non-interactively: it never prompts, it disables the coloured output, and it makes the output suitable for a log file. It is the first option of every CI command. -ntp (--no-transfer-progress) suppresses the per-file download progress that otherwise fills a CI log with Downloading from and Downloaded from lines; it does not hide failures. -V (--show-version) prints the version banner and then continues with the build, which is what you want at the top of a CI log:

(The banner is what mvn -v prints, here shown as printed except that the scratch path of the Maven installation is <tools> in the later listings, and the build footer was cut. The 3.10.0 release notes list the time zone in the banner as new.) -v (--version), in lower case, prints the banner and stops. The "Maven home" and "Java version" lines are the first thing to check when a CI build behaves differently from a laptop build: they say which Maven and which JDK answered.

Source: Maven 3.10.0 release notes

-q (--quiet) shows errors only. A successful build prints nothing at all, and the exit code carries the result:

On failure it prints just the errors, including the failed test and the stack frame that failed it (this ran tidepool-engine with -DfailEngine=true, which makes the extra test fail; the output was cut after the first lines of the Maven error):

-e (--errors) adds the Java stack trace of the build failure, which is what you attach to an issue against a plugin. A build error that is caused by a plugin exception, here an impossible compiler release (-Dmaven.compiler.release=99), prints a one-line message without -e, and with -e:

(The stack was cut at the ellipsis line and after the first Caused by frames; the whole output of the run was 151 lines.) A failure of the kind "there are test failures" is a MojoFailureException, which has no stack trace to show, so -e adds nothing there; use it when the cause is an exception, such as a plugin crash, an unreadable file or a bad configuration.

-X (--debug) produces debug output: 397 lines for a single compiler:compile goal run with -B -ntp, against 18 without it. It includes where each settings and toolchains file was read from, the lifecycle definitions, the complete class-realm setup (the Imported: lines), and for each plugin execution the value of every parameter. The parameter dump is the most useful part: it answers "which value did the plugin actually get", and (f) or (s) says whether Maven injected it into a field or through a setter:

(Filtered with grep, and the long Lifecycle default line cut short.) The release = 21 line is the maven.compiler.release property of the parent POM, reaching the plugin; source and target are the plugin’s own defaults, which release takes precedence over. The debug log of the same run also shows, for example, that the maven-default-http-blocker mirror is applied to plain-HTTP repositories. In Maven 4 the same option is spelled --verbose and -X is kept as an alias; see Maven 4.

Source: Maven 3.10.0 reference: Maven CLI Options Reference

-l file (--log-file) sends all output to a file instead of the console and disables the colour. The console stays empty and the exit code is unchanged:

Colour is off when the output is piped or redirected (measured below) and when -B or -l is given. To force it back on (for a CI system that renders ANSI colours), use the system property style.color or the --color option, which takes auto, always or never. The count below is the number of lines of the output that contain an ANSI escape character, measured with grep -c on a piped run (so, without colour by default):

Two things to take from the table. First, -B wins over the colour options: do not combine -B with a request for colour. Second, the space-separated form --color always did not turn the colour on in any of the three releases; use --color=always or the property -Dstyle.color=always. The reason was not investigated here.

Source: Maven 3.10.0 reference: Maven CLI Options Reference

-Dname=value defines a user property. User properties have the highest precedence: they override a <properties> entry of the POM and are visible to every plugin, so they are how a build is parameterised from the outside. -Dname with no value defines the property as true, and a value with spaces needs quoting for the shell:

(The first two were run in the tidepool parent, the last two in a scratch POM without a foo property; help:evaluate is the quickest way to see what an expression resolves to, and -DforceStdout prints only the value.) The first two lines show a POM property and the command-line override of it. Settings of the JVM that Maven runs in (the heap size, -Dfile.encoding) belong in MAVEN_OPTS, which is on Configuring Maven.

Properties that plugins read are documented per plugin. Three are used constantly, and they are different in a way people regularly confuse:

(The two outputs were produced by two separate runs, labelled with the ## lines added here, and filtered to the test-related lines.) -DskipTests compiles the tests and does not run them; -Dmaven.test.skip=true does not even compile them (Not compiling test sources), so no test classes exist to package. Prefer -DskipTests unless the test sources do not compile.

To run one test, -Dtest=HeightTest selects by class name (-Dtest=HeightTest#methodName selects a method). On a multi-module build the pattern matches in one module only, and Surefire fails the other modules for finding nothing to run:

(Filtered to the reactor summary and the first error line.) Adding -Dsurefire.failIfNoSpecifiedTests=false makes the other modules skip quietly, and the run succeeds with Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.018 s — in io.tidepool.model.HeightTest. The alternative is to select the module with -pl, below. Surefire itself is on Testing with Surefire.

Source: Maven Surefire Plugin: Running a single test

Source: Maven Surefire Plugin: Skipping tests

-P id1,id2 activates profiles by id. Profiles are covered in depth on Profiles; for the command line the useful facts are these. The ids are comma-separated with no spaces. Selecting a profile that does not exist is a warning, not an error, which is how a typo silently disables a CI profile:

(Printed twice, once while reading the POM and once at the start of the build; shown once.) The profile fast of the scratch project sets skipTests:

(Two runs, filtered; help:active-profiles lists what is active and where the profile was defined.) A profile can also be deactivated from the command line by prefixing the id with ! or -. Because ! is special to the shell and a leading - looks like an option, the guide recommends quoting the first and writing -P=-id for the second. A profile marked activeByDefault is switched off when another profile is selected with -P, which is a classic surprise; a scratch POM with the profiles lenient (activeByDefault) and ci shows it:

(The four runs, filtered to the profile lines and separated by ## lines added here.) The second run is the surprise: asking for ci did not add to lenient, it replaced it.

Source: Maven guide: Deactivating a profile

-f path (--file) runs against another POM; the path may be the POM file or the directory that contains it. It lets a script build a project without cding into it:

(The first command printed the Building lines and its BUILD SUCCESS; the second printed only its own BUILD SUCCESS in the filter, with the same project built.) -N (--non-recursive) builds the project in the current directory and does not descend into <modules>. It is the natural option for goals that act on a single POM, for example help:evaluate above, and for installing a parent POM on its own:

(Filtered to two lines: only tidepool-parent was built.) In Maven 4 -N combined with -pl also stops at the selected aggregators; see below.

Source: Maven 3.10.0 reference: Maven CLI Options Reference

-pl (--projects) takes a comma-separated list of the reactor projects to build instead of all of them. A project can be written as a directory relative to the aggregator (tidepool-cli, ./tidepool-cli), as :artifactId or as groupId:artifactId; all four forms selected the module in a run:

(Each command printed one Building line followed by BUILD SUCCESS; only the build lines are shown.) A name that is not in the reactor is an error, naming it:

(From mvn -B -ntp -pl nope validate; first error line only.) A project can be excluded by prefixing it with ! (quoted in the shell): -pl '!tidepool-data,!tidepool-cli' built the parent, tidepool-model and tidepool-engine only, as its summary shows:

(The command was mvn -B -ntp -pl '!tidepool-data,!tidepool-cli' test-compile; the footer was cut.) The prefix ?, which makes a project optional so that a missing one is not an error, is not available in 3.10.0 or 3.9.16, which answered Could not find the selected project in the reactor: ?nope, but is accepted by Maven 4.0.0-rc-7 (run: -pl '?nope,tidepool-model' built tidepool-model and ignored ?nope).

The module you select usually needs other modules, which are not on your list, or the other way round. -am (--also-make) adds the modules the selection depends on; -amd (--also-make-dependents) adds the modules that depend on it:

(The first four Building lines are from the first command: -am added the parent, tidepool-model and tidepool-engine, everything tidepool-cli needs. The summary is from the second: -amd added the modules that depend on tidepool-engine, here only tidepool-cli. Without -am, a build of -pl tidepool-cli takes tidepool-engine from the local repository, or fails if it is not installed there.) The two options can be combined to add both directions.

Source: Maven guide: Guide to Working with Multiple Modules, Command Line Options

When a module in the middle of a long reactor fails, -rf :artifactId (--resume-from) restarts the build at that module, skipping the earlier ones. Maven prints the exact suggestion at the end of a failed build, as shown in the failure section below. Resuming at tidepool-engine skips tidepool-parent and tidepool-model, and the build continues in reactor order, so the later modules (tidepool-cli and tidepool-data) are included:

(Filtered.) The earlier modules are not built, so their artifacts must be available: either in the local repository from a previous install, or by building them in the same invocation. An unknown project is an error that lists the projects of the reactor:

(From mvn -B -ntp -rf :nope validate.) Maven 4 adds -r (--resume), which reads the project to resume at from a file that the failed build wrote; see below.

Source: Maven guide: Guide to Working with Multiple Modules, Command Line Options

-T (--threads) builds modules in parallel. -T 4 uses four threads and -T 1C one thread per CPU core (C is the number of cores, and 2.5C is allowed). Maven announces the change of builder:

(The first block is from the first command, filtered; the last line is from the second command on a machine with ten cores. The [n/5] numbers are the order in which modules were started: tidepool-data has no dependencies, so the reactor started it alongside tidepool-model instead of last.) -T appeared in Maven 3.0. A plugin must be thread-safe to be used safely in a parallel build; whether the plugins of a build are is not something this page tested. The builder can also be chosen by id with -b (--builder): an unknown id fails with The builder requested using id = nope cannot be found. Parallel builds, the mvnd daemon and the build cache are on Build Performance: Cache, Parallel Builds & mvnd.

Source: Maven wiki: Parallel builds in Maven 3

Source: Maven 3.10.0 reference: Maven CLI Options Reference

-o (--offline) stops Maven from using the network. Anything already in the local repository still works; anything missing is an error, and it names the repository that Maven would have asked. With an empty local repository (the property maven.repo.local points Maven at another one, here empty-repo):

(Filtered; the same command without -o downloaded the plugin and succeeded.) With a warm repository, -o works as expected: mvn -B -ntp -o -pl tidepool-model test ended in BUILD SUCCESS. Offline mode is the cheap way to find out which dependencies a project needs in a network-less environment, and the usual way to run a build in a container with a pre-filled repository. The dependency:go-offline goal is the usual way to try to fill that repository beforehand (not run here). Offline mode can also be switched on with <offline>true</offline> in settings.xml.

Source: Maven 3.10.0 reference: Maven CLI Options Reference

Maven remembers what it could not find. If a dependency is missing from a remote repository, the failure is cached in the local repository, and Maven does not ask again until the repository’s update interval (daily by default) has elapsed. Publishing the missing artifact does not help until then. -U (--update-snapshots) forces Maven to check, and despite its name it also retries the cached failures of releases, not just snapshots. Maven 3.10.0 adds two finer options:

and the matching long options --artifacts-update-policy and --metadata-update-policy, each taking always, daily or never; -UA and -UM override them with always. All of this is from the 3.10.0 release notes.

Source: Maven 3.10.0 release notes

To see the difference, a scratch project depends on io.tidepool.demo:late-lib:1.0, which is declared in a file:// repository named team. The artifact is absent at first, then published into that repository, with a fresh local repository each time. The first build fails, as it should (dependency:resolve stands for any goal that needs the dependency):

After the artifact is published, the same command fails again, now from the cache and with a different message:

And the options, each tried from that same cached-failure state:

(Each row is from a real run. The first three were run one after the other in the same cached-failure state, -UA last; -UM and the plain command were repeated in the second copy, with the same result, before -U.) Use -U when you do not know what changed, -UA when you know a missing artifact is now there, and -UM when a plugin prefix or a version range or a -SNAPSHOT timestamp is stale. The ancient -up and -cpu ("check plugin updates") options and -npu and -npr are accepted by 3.10.0 but documented as "Ineffective, only kept for backward compatibility"; they do nothing, and they are not in the Maven 4.0.0-rc-7 option list. -nsu (--no-snapshot-updates) suppresses the check for updated snapshots (not run here).

Checksums are another cause of a failed download: -C (--strict-checksums) fails the build when a checksum does not match and -c (--lax-checksums) only warns. These were not run here; the default is set by the repository’s checksumPolicy, and the two options override it for the run. -itr (--ignore-transitive-repositories) ignores the remote repositories that dependencies declare in their own POMs, so only the repositories of the build and the settings are used; it was not run here.