Usage

The plugin offers goals for updating the versions of artifacts referenced in a Maven pom.xml file.

Basic Usage

Maven 2.0 does not currently support re-reading modifications of the pom.xml within one invocation of Maven.

The following goals:

modify the pom.xml file, you need to run these goals separately from any other goals or life-cycle phases.

Note: The first time any of the goals that modify the pom.xml file run, they will create a local backup copy pom.xml.versionsBackup. Subsequent modifications will leave this backup unchanged. The versions:commit goal will remove the backup copy, while the versions:revert goal will restore the backup copy. It is best practice to use a Source Code Management system and not rely on the pom.xml.versionsBackup files created by the versions-maven-plugin. The versions:commit and versions:revert goals are only a "Poor Man's SCM".

Reverting modifications to the pom.xml files (Note: modifies pom.xml files)

To restore your pom.xml files to their initial state, before you started modifying it with the versions-maven-plugin, invoke the revert goal. Note that it is best practice to use a Source Code Management system and not rely on the pom.xml.versionsBackup files created by the versions-maven-plugin.

mvn versions:revert

Accepting modifications to the pom.xml files

To accept the modifications made to your pom.xml files by the versions-maven-plugin invoke the commit goal. This will have the effect of removing any pom.xml.versionsBackup files. Note that it is best practice to use a Source Code Management system and not rely on the pom.xml.versionsBackup files created by the versions-maven-plugin.

mvn versions:commit

Updating the parent version (Note: modifies pom.xml files)

To update the parent version of your POM to the latest available, just invoke the update-parent goal.

mvn versions:update-parent

A more detailed example of the update-parent goal.

Fixing a multi-module build (Note: modifies pom.xml files)

If you have a multi-module build where the aggregator pom (i.e. the one with packaging of pom and the modules section) is also the parent referenced by its child modules, and the aggregator version does not match the version specified in the parent section of the child modules, Maven will not let you build the project. To fix all the child modules, use the versions:update-child-modules goal and invoke Maven in non-recursive mode.

mvn -N versions:update-child-modules

A more detailed example of the update-child-modules goal.

Checking for new versions of plugins

To get information about newer versions of plugins that you are using in your build, just invoke the display-plugin-updates goal.

mvn versions:display-plugin-updates

A more detailed example of the display-plugin-updates goal.

Checking for new versions of dependencies

To get information about newer versions of dependencies that you are using in your build, just invoke the display-dependency-updates goal.

mvn versions:display-dependency-updates

A more detailed example of the display-dependency-updates goal.

Updating versions specified by properties (Note: modifies pom.xml files)

This goal helps when you use properties to define versions. Please see the update-properties example.

Resolving version ranges (Note: modifies pom.xml files)

If a pom contains version ranges in one or more dependencies, it can be useful to collapse those ranges to the specific versions used during the build, just invoke the resolve-ranges goal.

mvn versions:resolve-ranges

More examples of the resolve-ranges goal.

Locking and unlocking -SNAPSHOT versions (Note: modifies pom.xml files)

If your pom contains a lot of -SNAPSHOT dependencies and those -SNAPSHOT dependencies are a moving target, it can sometimes be helpful to temporarily replace the -SNAPSHOT with a locked -YYYYMMDD.HHMMSS-NNN snapshot. In the long term, you will need to return to the -SNAPSHOT dependencies and then replace them with their release version, but if you need a short term semi-reproducible build, locked -SNAPSHOTs can sometimes be a useful hack.

To replace -SNAPSHOT dependencies with their current locked snapshot equivalents, just invoke the lock-snapshots goal.

mvn versions:lock-snapshots

More examples of the lock-snapshots goal.

To return to regular -SNAPSHOT dependencies, i.e. replace 1.9.6-20090103.152537-3 with 1.9.6-SNAPSHOT, just invoke the unlock-snapshots goal.

mvn versions:unlock-snapshots

More examples of the unlock-snapshots goal.

Picking up releases of -SNAPSHOT dependencies (Note: modifies pom.xml files)

It is better to depend on a released version of a dependency, rather than the -SNAPSHOT of that version. For example, it is better to depend on version 1.3.4 rather than 1.3.4-SNAPSHOT. Of course if you are waiting for 1.3.4 to be released, you will have had to add 1.3.4-SNAPSHOT as a dependency.

The use-releases goal will look at your project dependencies and see if any -SNAPSHOT versions have been released, replacing the -SNAPSHOT version with the corresponding release version.

To replace -SNAPSHOT dependencies with their corresponding release version, just invoke the use-releases goal.

mvn versions:use-releases

More examples of the lock-snapshots goal.

Report Usage

The plugin also offers a reporting view; it makes no changes to your project, but makes it easy for reviewers to survey available updates without even having to launch Maven themselves. Updates are further categorized as major, minor, and incremental, to make it easier to decide which updates to take.

To add this report to your project's site, add the following snippet to your POM:

<reporting>
  <plugins>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>versions-maven-plugin</artifactId>
      <version>1.0-alpha-3</version>
    </plugin>
  </plugins>
</reporting>