diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt new file mode 100644 index 0000000000..e95618a672 --- /dev/null +++ b/src/site/apt/index.apt @@ -0,0 +1,174 @@ + ~~ Licensed to the Apache Software Foundation (ASF) under one + ~~ or more contributor license agreements. See the NOTICE file + ~~ distributed with this work for additional information + ~~ regarding copyright ownership. The ASF licenses this file + ~~ to you under the Apache License, Version 2.0 (the + ~~ "License"); you may not use this file except in compliance + ~~ with the License. You may obtain a copy of the License at + ~~ + ~~ http://www.apache.org/licenses/LICENSE-2.0 + ~~ + ~~ Unless required by applicable law or agreed to in writing, + ~~ software distributed under the License is distributed on an + ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~~ KIND, either express or implied. See the License for the + ~~ specific language governing permissions and limitations + ~~ under the License. + + ------ + Introduction + ------ + Stephen Connolly + ------ + 2009-04-21 + ------ + + +Versions Maven Plugin + + The Versions Plugin is used when you want to manage the versions of artifacts in a project's POM. + +* Goals Overview + + The Versions Plugin has the following goals. + + * {{{./compare-dependencies-mojo.html}versions:compare-dependencies}} compares the dependency versions of the current + project to the dependency management section of a remote project. + + * {{{./display-dependency-updates-mojo.html}versions:display-dependency-updates}} scans a project's dependencies and + produces a report of those dependencies which have newer versions available. + + * {{{./display-plugin-updates-mojo.html}versions:display-plugin-updates}} scans a project's plugins and produces a + report of those plugins which have newer versions available, taking care of Maven version prerequisites. + + * {{{./display-property-updates-mojo.html}versions:display-property-updates}} scans a project and produces a report of + those properties which are used to control artifact versions and which properties have newer versions available. + + * {{{./update-parent-mojo.html}versions:update-parent}} updates the parent section of a project so that it references the + newest available version. For example, if you use a corporate root POM, this goal can be helpful if you need + to ensure you are using the latest version of the corporate root POM. + + * {{{./update-properties-mojo.html}versions:update-properties}} updates properties defined in a project so that they + correspond to the latest available version of specific dependencies. This can be useful if a suite of dependencies + must all be locked to one version. + + * {{{./update-property-mojo.html}versions:update-property}} Sets a property to the latest version in a given range of + associated artifacts. + + * {{{./update-child-modules-mojo.html}versions:update-child-modules}} updates the parent section of the child modules + of a project so the version matches the version of the current project. For example, if you have an aggregator pom + that is also the parent for the projects that it aggregates and the children and parent versions get out of sync, this + mojo can help fix the versions of the child modules. (Note you may need to invoke Maven with the -N option in order to + run this goal if your project is broken so badly that it cannot build because of the version mis-match). + + * {{{./lock-snapshots-mojo.html}versions:lock-snapshots}} searches the pom for all -SNAPSHOT versions and replaces them + with the current timestamp version of that -SNAPSHOT, e.g. -20090327.172306-4 + + * {{{./unlock-snapshots-mojo.html}versions:unlock-snapshots}} searches the pom for all timestamp locked snapshot versions + and replaces them with -SNAPSHOT. + + * {{{./resolve-ranges-mojo.html}versions:resolve-ranges}} finds dependencies using version ranges and resolves the range + to the specific version being used. + + * {{{./set-mojo.html}versions:set}} can be used to set the project version from the command line. + + * {{{./set-property-mojo.html}versions:set-property}} can be used to set one or multiple properties to a given version from the command line. + + * {{{./use-releases-mojo.html}versions:use-releases}} searches the pom for all -SNAPSHOT versions which have been + released and replaces them with the corresponding release version. + + * {{{./use-next-releases-mojo.html}versions:use-next-releases}} searches the pom for all non-SNAPSHOT versions which + have been a newer release and replaces them with the next release version. + + * {{{./use-latest-releases-mojo.html}versions:use-latest-releases}} searches the pom for all non-SNAPSHOT versions which + have been a newer release and replaces them with the latest release version. + + * {{{./use-next-snapshots-mojo.html}versions:use-next-snapshots}} searches the pom for all non-SNAPSHOT versions which + have been a newer -SNAPSHOT version and replaces them with the next -SNAPSHOT version. + + * {{{./use-latest-snapshots-mojo.html}versions:use-latest-snapshots}} searches the pom for all non-SNAPSHOT versions + which have been a newer -SNAPSHOT version and replaces them with the latest -SNAPSHOT version. + + * {{{./use-next-versions-mojo.html}versions:use-next-versions}} searches the pom for all versions which + have been a newer version and replaces them with the next version. + + * {{{./use-latest-versions-mojo.html}versions:use-latest-versions}} searches the pom for all versions which + have been a newer version and replaces them with the latest version. + + * {{{./use-dep-version-mojo.html}versions:use-dep-version}} updates a dependency to a specific version. + + * {{{./commit-mojo.html}versions:commit}} removes the <<>> files. Forms one half of the + built-in "Poor Man's SCM". + + * {{{./revert-mojo.html}versions:revert}} restores the <<>> files from the <<>> files. + Forms one half of the built-in "Poor Man's SCM". + +* Reporting goals overview + + The Versions Plugin has the following reporting goals. + + * {{{./dependency-updates-report-mojo.html}versions:dependency-updates-report}} produces a report of those + project dependencies which have newer versions available. + + * {{{./plugin-updates-report-mojo.html}versions:plugin-updates-report}} produces a report of those plugins which have + newer versions available. + + * {{{./property-updates-report-mojo.html}versions:property-updates-report}} produces a report of + those properties which are used to control artifact versions and which properties have newer versions available. + + * {{{./parent-updates-report-mojo.html}versions:parent-updates-report}} produces a report on possible parent artifact + upgrades. + +* Usage + + General instructions on how to use the Versions Plugin can be found on the {{{./usage.html}usage page}}. Some more + specific use cases are described in the examples given below. Last but not least, users occasionally contribute + additional examples, tips or errata to the + {{{http://docs.codehaus.org/display/MAVENUSER/Versions+Plugin}plugin's wiki page}}. + + In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel + free to contact the {{{./mail-lists.html}user mailing list}}. The posts to the mailing list are archived and could + already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching + the {{{./mail-lists.html}mail archive}}. + + If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our + {{{./issue-tracking.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your + concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, + entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. + Of course, patches are welcome, too. Contributors can check out the project from our + {{{./source-repository.html}source repository}} and will find supplementary information in the + {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. + +* Examples + + To provide you with better understanding of some usages of the Plugin Name, + you can take a look into the following examples: + + * {{{./examples/advancing-dependency-versions.html}Advancing dependency versions}} + + * {{{./examples/compare-dependencies.html}Compare project dependencies to a remote project}} + + * {{{./examples/display-dependency-updates.html}Checking for new dependency updates}} + + * {{{./examples/display-plugin-updates.html}Checking for new plugin updates}} + + * {{{./examples/display-property-updates.html}Checking for new property-linked updates}} + + * {{{./examples/update-parent.html}Updating the Parent version}} + + * {{{./examples/update-properties.html}Updating a version specified in a property}} + + * {{{./examples/update-child-modules.html}Fixing a multi-module build}} + + * {{{./examples/resolve-ranges.html}Resolve version ranges}} + + * {{{./examples/lock-snapshots.html}Locking snapshot dependencies}} + + * {{{./examples/unlock-snapshots.html}Unlocking snapshot dependencies}} + + * {{{./examples/use-releases.html}Replacing -SNAPSHOT versions with their corresponding releases}} + + * {{{./examples/set.html}Changing the project version}} + + * {{{./examples/recording-changes.html}Recording version changes}} + diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm deleted file mode 100644 index c159979237..0000000000 --- a/src/site/apt/usage.apt.vm +++ /dev/null @@ -1,272 +0,0 @@ - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - - ----- - Usage - ----- - Stephen Connolly - ------ - 2008-09-02 - ------ - -Usage - - The plugin offers goals for updating the versions of artifacts referenced in - a Maven <<>> file. - -* Basic Usage - - Maven 2.0, 2.1, 2.2 and 3.0 do not currently support re-reading modifications of the <<>> within one - invocation of Maven. - - The following goals: - - * {{{./set-mojo.html}versions:set}} - - * {{{./lock-snapshots-mojo.html}versions:lock-snapshots}} - - * {{{./resolve-ranges-mojo.html}versions:resolve-ranges}} - - * {{{./unlock-snapshots-mojo.html}versions:unlock-snapshots}} - - * {{{./update-child-modules-mojo.html}versions:update-child-modules}} - - * {{{./update-parent-mojo.html}versions:update-parent}} - - * {{{./update-properties-mojo.html}versions:update-properties}} - - * {{{./set-property-mojo.html}versions:set-property}} - - * {{{./use-latest-releases-mojo.html}versions:use-latest-releases}} - - * {{{./use-latest-snapshots-mojo.html}versions:use-latest-snapshots}} - - * {{{./use-latest-versions-mojo.html}versions:use-latest-versions}} - - * {{{./use-next-releases-mojo.html}versions:use-next-releases}} - - * {{{./use-next-snapshots-mojo.html}versions:use-next-snapshots}} - - * {{{./use-next-versions-mojo.html}versions:use-next-versions}} - - * {{{./use-releases-mojo.html}versions:use-releases}} - - modify the <<>> 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 <<>> file run, they will create a local backup copy - <<>>. Subsequent modifications will leave this backup unchanged. The - {{{./accept-mojo.html}versions:commit}} goal will remove the backup copy, while the - {{{./revert-mojo.html}versions:revert}} goal will restore the backup copy. It is best practice - to use a Source Code Management system and not rely on the <<>> files created by the - versions-maven-plugin. The {{{./accept-mojo.html}versions:commit}} and {{{./revert-mojo.html}versions:revert}} goals are - only a "Poor Man's SCM". - -* Goals that modify the <<>> - - Executing any of the following goals may modify your <<>> file. - -** Reverting modifications to the <<>> files (Note: modifies <<>> files) - - To restore your <<>> files to their initial state, before you started modifying it with the - versions-maven-plugin, invoke the <<>> goal. Note that it is best practice - to use a Source Code Management system and not rely on the <<>> files created by the - versions-maven-plugin. - ---- -mvn versions:revert ---- - -** Accepting modifications to the <<>> files - - To accept the modifications made to your <<>> files by the versions-maven-plugin invoke the <<>> - goal. This will have the effect of removing any <<>> files. Note that it is best practice - to use a Source Code Management system and not rely on the <<>> files created by the - versions-maven-plugin. - ---- -mvn versions:commit ---- - -** Updating the parent version (Note: modifies <<>> files) - - To update the parent version of your POM to the latest available, just invoke the <<>> goal. - ---- -mvn versions:update-parent ---- - - {{{./examples/update-parent.html} A more detailed example of the <<>> goal}}. - -** Fixing a multi-module build (Note: modifies <<>> files) - - If you have a multi-module build where the aggregator pom (i.e. the one with packaging of <<>> and the - <<>> 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 {{{./update-child-modules-mojo.html}versions:update-child-modules}} goal and - invoke Maven in non-recursive mode. - ---- -mvn -N versions:update-child-modules ---- - - {{{./examples/update-child-modules.html} A more detailed example of the <<>> goal}}. - -** Updating versions specified by properties (Note: modifies <<>> files) - - This goal helps when you use properties to define versions. Please see the - {{{./examples/update-properties.html}<<>> example}}. - -** Updating versions of dependencies (Note: modifies <<>> files) - - There are a set of goals to help with advancing dependency versions: <<>>, - <<>>, <<>>, <<>>, <<>>, and - <<>>. - - Please see the {{{./examples/advancing-dependency-versions.html}advancing dependency versions example}}. - -** Resolving version ranges (Note: modifies <<>> 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 <<>> goal. - ---- -mvn versions:resolve-ranges ---- - - More examples of the {{{./examples/resolve-ranges.html} <<>>}} goal. - -** Locking and unlocking -SNAPSHOT versions (Note: modifies <<>> 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 <<>> - goal. - ---- -mvn versions:lock-snapshots ---- - - More examples of the {{{./examples/lock-snapshots.html} <<>>}} goal. - - To return to regular -SNAPSHOT dependencies, i.e. replace 1.9.6-20090103.152537-3 with 1.9.6-SNAPSHOT, just invoke - the <<>> goal. - ---- -mvn versions:unlock-snapshots ---- - - More examples of the {{{./examples/unlock-snapshots.html} <<>>}} goal. - -** Picking up releases of -SNAPSHOT dependencies (Note: modifies <<>> 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 <<>> 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 <<>> - goal. - ---- -mvn versions:use-releases ---- - - More examples of the {{{./examples/use-releases.html} <<>>}} goal. - -** Setting the project version - - To set the project version to a specific version, just invoke the <<>> goal. - ---- -mvn versions:set -DnewVersion=1.0.1-SNAPSHOT ---- - - More examples of the {{{./examples/set.html} <<>>}} goal. - -* Goals that do not modify the <<>> - - Executing any of the following goals will not modify your <<>> file. - -** Checking for new versions of plugins - - To get information about newer versions of plugins that you are using in your build, just invoke the - <<>> goal. - ---- -mvn versions:display-plugin-updates ---- - - {{{./examples/display-plugin-updates.html} A more detailed example of the <<>> 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 - <<>> goal. - ---- -mvn versions:display-dependency-updates ---- - - {{{./examples/display-dependency-updates.html} A more detailed example of the <<>> goal}}. - -** Checking for new versions of specified by properties - - To get information about newer versions of dependencies that you are using in your build, just invoke the - <<>> goal. - ---- -mvn versions:display-property-updates ---- - - {{{./examples/display-property-updates.html} A more detailed example of the <<>> goal}}. - -* Report Usage - - The plugin also offers some reporting views; these make 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 these reports to your project's site, add the following snippet to your POM: - -+---+ - - - - org.codehaus.mojo - versions-maven-plugin - ${pluginVersion} - - - - dependency-updates-report - plugin-updates-report - property-updates-report - - - - - - -+---+ - diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md deleted file mode 100644 index f3d14bada3..0000000000 --- a/src/site/markdown/index.md +++ /dev/null @@ -1,125 +0,0 @@ -title: Introduction -autor: Stephen Connolly -date: 2009-04-21 - - - -# Versions Maven Plugin - -The Versions Plugin is used when you want to manage the versions of artifacts in a project's POM. - -## Goals Overview - -The Versions Plugin has the following goals. -* [versions:compare-dependencies](./compare-dependencies-mojo.html) compares the dependency versions of the current - project to the dependency management section of a remote project. -* [versions:display-dependency-updates](./display-dependency-updates-mojo.html) scans a project's dependencies and - produces a report of those dependencies which have newer versions available. -* [versions:display-plugin-updates](./display-plugin-updates-mojo.html) scans a project's plugins and produces a - report of those plugins which have newer versions available, taking care of Maven version prerequisites. -* [versions:display-property-updates](./display-property-updates-mojo.html) scans a project and produces a report of - those properties which are used to control artifact versions and which properties have newer versions available. -* [versions:update-parent](./update-parent-mojo.html) updates the parent section of a project so that it references the - newest available version. For example, if you use a corporate root POM, this goal can be helpful if you need - to ensure you are using the latest version of the corporate root POM. -* [versions:update-properties](./update-properties-mojo.html) updates properties defined in a project so that they - correspond to the latest available version of specific dependencies. This can be useful if a suite of dependencies - must all be locked to one version. -* [versions:update-property](./update-property-mojo.html) Sets a property to the latest version in a given range of - associated artifacts. -* [versions:update-child-modules](./update-child-modules-mojo.html) updates the parent section of the child modules - of a project so the version matches the version of the current project. For example, if you have an aggregator pom - that is also the parent for the projects that it aggregates and the children and parent versions get out of sync, this - mojo can help fix the versions of the child modules. (Note you may need to invoke Maven with the -N option in order to - run this goal if your project is broken so badly that it cannot build because of the version mis-match). -* [versions:lock-snapshots](./lock-snapshots-mojo.html) searches the pom for all -SNAPSHOT versions and replaces them - with the current timestamp version of that -SNAPSHOT, e.g. -20090327.172306-4 -* [versions:unlock-snapshots](./unlock-snapshots-mojo.html) searches the pom for all timestamp locked snapshot versions - and replaces them with -SNAPSHOT. -* [versions:resolve-ranges](./resolve-ranges-mojo.html) finds dependencies using version ranges and resolves the range - to the specific version being used. -* [versions:set](./set-mojo.html) can be used to set the project version from the command line. -* [versions:set-property](./set-property-mojo.html) can be used to set one or multiple properties to a given version from the command line. -* [versions:use-releases](./use-releases-mojo.html) searches the pom for all -SNAPSHOT versions which have been - released and replaces them with the corresponding release version. -* [versions:use-next-releases](./use-next-releases-mojo.html) searches the pom for all non-SNAPSHOT versions which - have been a newer release and replaces them with the next release version. -* [versions:use-latest-releases](./use-latest-releases-mojo.html) searches the pom for all non-SNAPSHOT versions which - have been a newer release and replaces them with the latest release version. -* [versions:use-next-snapshots](./use-next-snapshots-mojo.html) searches the pom for all non-SNAPSHOT versions which - have been a newer -SNAPSHOT version and replaces them with the next -SNAPSHOT version. -* [versions:use-latest-snapshots](./use-latest-snapshots-mojo.html) searches the pom for all non-SNAPSHOT versions - which have been a newer -SNAPSHOT version and replaces them with the latest -SNAPSHOT version. -* [versions:use-next-versions](./use-next-versions-mojo.html) searches the pom for all versions which - have been a newer version and replaces them with the next version. -* [versions:use-latest-versions](./use-latest-versions-mojo.html) searches the pom for all versions which - have been a newer version and replaces them with the latest version. -* [versions:use-dep-version](./use-dep-version-mojo.html) updates a dependency to a specific version. -* [versions:commit](./commit-mojo.html) removes the `pom.xml.versionsBackup` files. Forms one half of the - built-in "Poor Man's SCM". -* [versions:revert](./revert-mojo.html) restores the `pom.xml` files from the `pom.xml.versionsBackup` files. - Forms one half of the built-in "Poor Man's SCM". - -## Reporting goals overview - -The Versions Plugin has the following reporting goals. -* [versions:dependency-updates-report](./dependency-updates-report-mojo.html) produces a report of those - project dependencies which have newer versions available. -* [versions:plugin-updates-report](./plugin-updates-report-mojo.html) produces a report of those plugins which have - newer versions available. -* [versions:property-updates-report](./property-updates-report-mojo.html) produces a report of - those properties which are used to control artifact versions and which properties have newer versions available. -* [versions:parent-updates-report](./parent-updates-report-mojo.html) produces a report on possible parent artifact - upgrades. - -## Usage - -General instructions on how to use the Versions Plugin can be found on the [usage page](./usage.html). Some more -specific use cases are described in the examples given below. - -In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel -free to contact the [user mailing list](./mail-lists.html). The posts to the mailing list are archived and could -already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching -the [mail archive](./mail-lists.html). - -If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our -[issue tracker](./issue-tracking.html). When creating a new issue, please provide a comprehensive description of your -concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, -entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. -Of course, patches are welcome, too. Contributors can check out the project from our -[source repository](./source-repository.html) and will find supplementary information in the -[guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html). - -## Examples - -To provide you with better understanding of some usages of the Plugin Name, -you can take a look into the following examples: -* [Advancing dependency versions](./examples/advancing-dependency-versions.html) -* [Compare project dependencies to a remote project](./examples/compare-dependencies.html) -* [Checking for new dependency updates](./examples/display-dependency-updates.html) -* [Checking for new plugin updates](./examples/display-plugin-updates.html) -* [Checking for new property-linked updates](./examples/display-property-updates.html) -* [Updating the Parent version](./examples/update-parent.html) -* [Updating a version specified in a property](./examples/update-properties.html) -* [Fixing a multi-module build](./examples/update-child-modules.html) -* [Resolve version ranges](./examples/resolve-ranges.html) -* [Locking snapshot dependencies](./examples/lock-snapshots.html) -* [Unlocking snapshot dependencies](./examples/unlock-snapshots.html) -* [Replacing -SNAPSHOT versions with their corresponding releases](./examples/use-releases.html) -* [Changing the project version](./examples/set.html) -* [Recording version changes](./examples/recording-changes.html) diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm new file mode 100644 index 0000000000..dafa245201 --- /dev/null +++ b/src/site/markdown/usage.md.vm @@ -0,0 +1,258 @@ +title: Usage +autor: Stephen Connolly +date: 2008-09-02 + + + +## Velocity uses # as a prefix for macros and ## as a prefix for comments +#set($h1 = '#') +#set($h2 = '##') +#set($h3 = '###') + +$h1 Usage + +The plugin offers goals for updating the versions of artifacts referenced in +a Maven `pom.xml` file. + +$h2 Basic Usage + +Maven 2.0, 2.1, 2.2 and 3.0 do not currently support re-reading modifications of the `pom.xml` within one +invocation of Maven. + +The following goals: +- [versions:set](./set-mojo.html) +- [versions:lock-snapshots](./lock-snapshots-mojo.html) +- [versions:resolve-ranges](./resolve-ranges-mojo.html) +- [versions:unlock-snapshots](./unlock-snapshots-mojo.html) +- [versions:update-child-modules](./update-child-modules-mojo.html) +- [versions:update-parent](./update-parent-mojo.html) +- [versions:update-properties](./update-properties-mojo.html) +- [versions:set-property](./set-property-mojo.html) +- [versions:use-latest-releases](./use-latest-releases-mojo.html) +- [versions:use-latest-snapshots](./use-latest-snapshots-mojo.html) +- [versions:use-latest-versions](./use-latest-versions-mojo.html) +- [versions:use-next-releases](./use-next-releases-mojo.html) +- [versions:use-next-snapshots](./use-next-snapshots-mojo.html) +- [versions:use-next-versions](./use-next-versions-mojo.html) +- [versions:use-releases](./use-releases-mojo.html) + +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](./commit-mojo.html) goal will remove the backup copy, while the +[versions:revert](./revert-mojo.html) 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](./commit-mojo.html) and [versions:revert](./revert-mojo.html) goals are +only a "Poor Man's SCM". + +$h2 Goals that modify the `pom.xml` + +Executing any of the following goals may modify your `pom.xml` file. + +$h3 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. + +```sh +mvn versions:revert +``` + +$h3 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. + +```sh +mvn versions:commit +``` + +$h3 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. + +```sh +mvn versions:update-parent +``` + +[A more detailed example of the `update-parent` goal](./examples/update-parent.html). + +$h3 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](./update-child-modules-mojo.html) goal and +invoke Maven in non-recursive mode. + +``` +mvn -N versions:update-child-modules +``` + +[A more detailed example of the `update-child-modules` goal](./examples/update-child-modules.html). + +$h3 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](./examples/update-properties.html). + +$h3 Updating versions of dependencies (Note: modifies `pom.xml` files) + +There are a set of goals to help with advancing dependency versions: `use-latest-releases`, +`use-latest-snapshots`, `use-latest-versions`, `use-next-releases`, `use-next-snapshots`, and +`use-next-versions`. + +Please see the [advancing dependency versions example](./examples/advancing-dependency-versions.html). + +$h3 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. + +```sh +mvn versions:resolve-ranges +``` + +More examples of the [`resolve-ranges`](./examples/resolve-ranges.html) goal. + +$h3 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. + +```sh +mvn versions:lock-snapshots +``` + +More examples of the [`lock-snapshots`](./examples/lock-snapshots.html) 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. + +```sh +mvn versions:unlock-snapshots +``` + +More examples of the [`unlock-snapshots`](./examples/unlock-snapshots.html) goal. + +$h3 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. + +```sh +mvn versions:use-releases +``` + +More examples of the [`lock-snapshots`](./examples/use-releases.html) goal. + +$h3 Setting the project version + +To set the project version to a specific version, just invoke the `set` goal. + +```sh +mvn versions:set -DnewVersion=1.0.1-SNAPSHOT +``` + +More examples of the [`set`](./examples/set.html) goal. + +$h2 Goals that do not modify the `pom.xml` + +Executing any of the following goals will not modify your `pom.xml` file. + +$h3 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. + +```sh +mvn versions:display-plugin-updates +``` + +[A more detailed example of the `display-plugin-updates` goal](./examples/display-plugin-updates.html). + +$h3 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. + +```sh +mvn versions:display-dependency-updates +``` + +[A more detailed example of the `display-dependency-updates` goal](./examples/display-dependency-updates.html). + +$h3 Checking for new versions of specified by properties + +To get information about newer versions of dependencies that you are using in your build, just invoke the +`display-property-updates` goal. + +```sh +mvn versions:display-property-updates +``` + +[A more detailed example of the `display-property-updates` goal](./examples/display-property-updates.html). + +$h2 Report Usage + +The plugin also offers some reporting views; these make 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 these reports to your project's site, add the following snippet to your POM: + +```xml + + + + org.codehaus.mojo + versions-maven-plugin + ${pluginVersion} + + + + dependency-updates-report + plugin-updates-report + property-updates-report + + + + + + +``` +