release:prepare – Maven Release plugin
release:prepare
Full name
org.apache.maven.plugins:maven-release-plugin:3.3.1:prepare
Description
Prepare for a release in SCM. Steps through several phases to ensure the POM is ready to be released and then prepares SCM to eventually contain a tagged version of the release and a record in the local copy of the parameters used. This can be followed by a call to
release:perform
. For more info see
Attributes
Requires a Maven project to be executed.
Executes as an aggregator goal.
The goal is not marked as thread-safe and thus does not support parallel builds.
Optional Parameters
Name
Type
Since
Description
boolean
Whether to add a schema to the POM if it was previously missing on release.
Default
true
User Property
addSchema
boolean
2.0-beta-7
Whether to allow timestamped SNAPSHOT dependencies. Default is to fail when finding any SNAPSHOT.
Default
false
User Property
ignoreSnapshots
String
Additional arguments to pass to the Maven executions, separated by spaces.
User Property
arguments
Alias
prepareVerifyArgs
String
3.0.0-M4
Specifies whether unresolved SNAPSHOT dependencies should automatically be resolved. If this is set, then this specifies the default answer to be used when unresolved SNAPSHOT dependencies should automatically be resolved ( 0:All 1:Project Dependencies 2:Plugins 3:Reports 4:Extensions ). Possible values are:
"all" or "0": resolve all kinds of snapshots, ie. project, plugin, report and extension dependencies
"dependencies" or "1": resolve project dependencies
"plugins" or "2": resolve plugin dependencis
"reports" or "3": resolve report dependencies
"extensions" or "4": resolve extension dependencies
User Property
autoResolveSnapshots
boolean
2.0-beta-5
Whether to automatically assign submodules the parent version. If set to false, the user will be prompted for the version of each submodules.
Default
false
User Property
autoVersionSubmodules
String
2.1
Command-line version of checkModificationExcludes.
User Property
checkModificationExcludeList
String[]
2.1
A list of additional exclude filters that will be skipped when checking for modifications on the working copy. Is ignored, when checkModificationExcludes is set.
boolean
2.0-beta-5
Commits to do are atomic or by project.
Default
false
User Property
commitByProject
String
2.2
Goals to run on completion of the preparation step, after transformation back to the next development version but before committing. Space delimited.
User Property
completionGoals
String
2.0-beta-8
Default version to use for new local working copy.
User Property
developmentVersion
boolean
Dry run: don't checkin or tag anything in the scm repository, or modify the checkout. Running
mvn -DdryRun=true release:prepare
is useful in order to check that modifications to poms and scm operations (only listed on the console) are working as expected. Modified POMs are written alongside the originals without modifying them.
Default
false
User Property
dryRun
boolean
Deprecated.
Please use release:prepare-with-pom instead.
No description.
Default
false
User Property
generateReleasePoms
File
2.0-beta-8
The Java home parameter to use for forked Maven invocations.
Default
${java.home}
String
3.0.0-M6
Specifies the line separator to format pom.xml. The following properties are available:
system
- Use the system line separator.
lf
- Use \n as line separator.
cr
- Use \r as line separator.
crlf
- Use \r\n as line separator.
source
- Use the same line separator as it is specified in the current pom.xml.
Default
source
User Property
lineSeparator
File
2.0-beta-8
The command-line local repository directory in use for this build (if specified).
Default
${maven.repo.local}
String
2.0-beta-8
Role hint of the
org.apache.maven.shared.release.exec.MavenExecutor
implementation to use.
Default
invoker
User Property
mavenExecutorId
File
2.0-beta-8
The Maven home parameter to use for forked Maven invocations.
Default
${maven.home}
String
The password to use for authentication with the SCM.
See also:
SCM Authentication
User Property
password
boolean
3.0.0-M4
Currently only implemented with svn scm. Enable the
--pin-externals
option in
svn copy
command which is new in Subversion 1.9.
Default
false
User Property
pinExternals
String
The file name of the POM to execute any goals against. As of version 3.0.0, this defaults to the name of POM file of the project being built.
Default
${project.file.name}
User Property
pomFileName
String
Goals to run as part of the preparation step, after transformation but before committing. Space delimited.
Default
clean verify
User Property
preparationGoals
String
3.0.0
Comma separated profiles to enable on release prepare, in addition to active profiles for project execution.
User Property
preparationProfiles
File
3.2.0
The path to the SSH private key to use for authentication with the SCM.
See also:
SCM Authentication
User Property
privateKey
String
3.0.0-M1
The role-hint for the
org.apache.maven.shared.release.policy.naming.NamingPolicy
implementation used to calculate the project branch and tag names.
See also:
org.apache.maven.shared.release.policies.DefaultNamingPolicy
User Property
projectNamingPolicyId
PlexusConfiguration
3.0.0
Optional config for the VersionPolicy implementation used to calculate the project versions.
User Property
projectVersionPolicyConfig
String
2.5.1
The role-hint for the
org.apache.maven.shared.release.policy.version.VersionPolicy
implementation used to calculate the project versions.
See also:
Versioning Policies
Default
default
User Property
projectVersionPolicyId
Map
2.0-beta-6
Add a new or overwrite the default implementation per provider. The key is the scm prefix and the value is the role hint/provider id of the
org.apache.maven.scm.provider.ScmProvider
See also:
org.apache.maven.scm.manager.ScmManager.setScmProviderImplementation(java.lang.String,java.lang.String)
SCM Providers
boolean
2.1
Whether to push changes to the upstream repository or not. Only applicable to distributed version control like Git. Is set to
true
by default to preserve backward compatibility.
Default
true
User Property
pushChanges
String
3.0.0-M5
The role-hint for the
org.apache.maven.shared.release.strategy.Strategy
implementation used to specify the phases per goal.
See also:
org.apache.maven.shared.release.strategies.DefaultStrategy
Default
default
User Property
releaseStrategyId
String
2.0-beta-8
Default version to use when preparing a release or a branch.
User Property
releaseVersion
boolean
2.0-beta-9
Currently only implemented with svn scm.
Enables a workaround to prevent issue due to svn client > 1.5.0 (fixed in 1.6.5) (https://issues.apache.org/jira/browse/SCM-406)
You may not want to use this in conjunction with
suppressCommitBeforeTag
, such that no poms with released versions are committed to the working copy ever.
Default
true
User Property
remoteTagging
boolean
Resume a previous release attempt from the point where it was stopped.
Default
true
User Property
resume
String
2.0-beta-5
The message prefix to use for all SCM changes.
Default
[maven-release-plugin]
User Property
scmCommentPrefix
String
3.0.0-M1
The SCM commit comment for the commit setting pom.xml back to development version. Defaults to "@{prefix} prepare for next development iteration".
Property interpolation is performed on the value, but in order to ensure that the interpolation occurs during release, you must use
@{...}
to reference the properties rather than
${...}
. The following properties are available:
prefix
- The comment prefix.
groupId
- The groupId of the root project.
artifactId
- The artifactId of the root project.
releaseLabel
- The release version of the root project.
Default
@{prefix} prepare for next development iteration
User Property
scmDevelopmentCommitComment
String
3.0.0-M1
The SCM commit comment for the commit setting pom.xml to release version. Defaults to "@{prefix} prepare release @{releaseLabel}".
Property interpolation is performed on the value, but in order to ensure that the interpolation occurs during release, you must use
@{...}
to reference the properties rather than
${...}
. The following properties are available:
prefix
- The comment prefix.
groupId
- The groupId of the root project.
artifactId
- The artifactId of the root project.
releaseLabel
- The release version of the root project.
Default
@{prefix} prepare release @{releaseLabel}
User Property
scmReleaseCommitComment
boolean
When cloning a repository if it should be a shallow clone or a full clone.
Default
true
User Property
scmShallowClone
String
3.2.0
The server id of the server which provides the credentials for the SCM in the
settings.xml
file. If not set the default lookup uses the SCM URL to construct the server id like this:
server-id=scm-host[":"scm-port]
Currently the POM does not allow to specify a server id for the SCM section.
Explicit authentication information provided via
username
password
or
privateKey
will take precedence.
See also:
SCM Authentication
Default
${project.scm.id}
User Property
project.scm.id
boolean
3.0.0-M4
Signs SCM tag when possible, for example when using the git-exe the '--sign' argument is used.
User Property
signTag
boolean
2.1
Whether to suppress a commit of changes to the working copy before the tag is created.
This requires
remoteTagging
to be set to false.
suppressCommitBeforeTag
is useful when you want to avoid poms with released versions in all revisions of your trunk or development branch.
Default
false
User Property
suppressCommitBeforeTag
String
The SCM tag to use.
User Property
tag
Alias
releaseLabel
String
The tag base directory in SVN, you must define it if you don't use the standard svn layout (trunk/tags/branches). For example,
. The URL is an SVN URL and does not include the SCM provider and protocol.
User Property
tagBase
String
2.2.0
Format to use when generating the tag name if none is specified. Property interpolation is performed on the tag, but in order to ensure that the interpolation occurs during release, you must use
@{...}
to reference the properties rather than
${...}
. The following properties are available:
groupId
or
project.groupId
- The groupId of the root project.
artifactId
or
project.artifactId
- The artifactId of the root project.
version
or
project.version
- The release version of the root project.
Default
@{project.artifactId}-@{project.version}
User Property
tagNameFormat
boolean
2.0-beta-5
Whether to update dependencies version to the next development version.
Default
true
User Property
updateDependencies
boolean
2.1
Whether to bump the working copy versions to
developmentVersion
Default
true
User Property
updateWorkingCopyVersions
boolean
Whether to use "edit" mode on the SCM, to lock the file for editing during SCM operations.
Default
false
User Property
useEditMode
String
The username to use for authentication with the SCM.
See also:
SCM Authentication
User Property
username
int
2.2
Wait the specified number of seconds before creating the tag.
waitBeforeTagging
is useful when your source repository is synced between several instances and access to it is determined by geographical location, like the SVN repository at the Apache Software Foundation.
Default
User Property
waitBeforeTagging
String
3.0.0-M5
A workItem for SCMs like RTC, TFS etc, that may require additional information to perform a pushChange operation.
User Property
workItem
Parameter Details
Whether to add a schema to the POM if it was previously missing on release.
Type
boolean
Required
No
User Property
addSchema
Default
true
Whether to allow timestamped SNAPSHOT dependencies. Default is to fail when finding any SNAPSHOT.
Type
boolean
Since
2.0-beta-7
Required
No
User Property
ignoreSnapshots
Default
false
Additional arguments to pass to the Maven executions, separated by spaces.
Type
java.lang.String
Required
No
User Property
arguments
Alias
prepareVerifyArgs
Specifies whether unresolved SNAPSHOT dependencies should automatically be resolved. If this is set, then this specifies the default answer to be used when unresolved SNAPSHOT dependencies should automatically be resolved ( 0:All 1:Project Dependencies 2:Plugins 3:Reports 4:Extensions ). Possible values are:
"all" or "0": resolve all kinds of snapshots, ie. project, plugin, report and extension dependencies
"dependencies" or "1": resolve project dependencies
"plugins" or "2": resolve plugin dependencis
"reports" or "3": resolve report dependencies
"extensions" or "4": resolve extension dependencies
Type
java.lang.String
Since
3.0.0-M4
Required
No
User Property
autoResolveSnapshots
Whether to automatically assign submodules the parent version. If set to false, the user will be prompted for the version of each submodules.
Type
boolean
Since
2.0-beta-5
Required
No
User Property
autoVersionSubmodules
Default
false
Command-line version of checkModificationExcludes.
Type
java.lang.String
Since
2.1
Required
No
User Property
checkModificationExcludeList
A list of additional exclude filters that will be skipped when checking for modifications on the working copy. Is ignored, when checkModificationExcludes is set.
Type
java.lang.String[]
Since
2.1
Required
No
Commits to do are atomic or by project.
Type
boolean
Since
2.0-beta-5
Required
No
User Property
commitByProject
Default
false
Goals to run on completion of the preparation step, after transformation back to the next development version but before committing. Space delimited.
Type
java.lang.String
Since
2.2
Required
No
User Property
completionGoals
Default version to use for new local working copy.
Type
java.lang.String
Since
2.0-beta-8
Required
No
User Property
developmentVersion
Dry run: don't checkin or tag anything in the scm repository, or modify the checkout. Running
mvn -DdryRun=true release:prepare
is useful in order to check that modifications to poms and scm operations (only listed on the console) are working as expected. Modified POMs are written alongside the originals without modifying them.
Type
boolean
Required
No
User Property
dryRun
Default
false
Deprecated.
Please use release:prepare-with-pom instead.
No description.
Type
boolean
Required
No
User Property
generateReleasePoms
Default
false
The Java home parameter to use for forked Maven invocations.
Type
java.io.File
Since
2.0-beta-8
Required
No
Default
${java.home}
Specifies the line separator to format pom.xml. The following properties are available:
system
- Use the system line separator.
lf
- Use \n as line separator.
cr
- Use \r as line separator.
crlf
- Use \r\n as line separator.
source
- Use the same line separator as it is specified in the current pom.xml.
Type
java.lang.String
Since
3.0.0-M6
Required
No
User Property
lineSeparator
Default
source
The command-line local repository directory in use for this build (if specified).
Type
java.io.File
Since
2.0-beta-8
Required
No
Default
${maven.repo.local}
Role hint of the
org.apache.maven.shared.release.exec.MavenExecutor
implementation to use.
Type
java.lang.String
Since
2.0-beta-8
Required
No
User Property
mavenExecutorId
Default
invoker
The Maven home parameter to use for forked Maven invocations.
Type
java.io.File
Since
2.0-beta-8
Required
No
Default
${maven.home}
The password to use for authentication with the SCM.
See also:
SCM Authentication
Type
java.lang.String
Required
No
User Property
password
Currently only implemented with svn scm. Enable the
--pin-externals
option in
svn copy
command which is new in Subversion 1.9.
Type
boolean
Since
3.0.0-M4
Required
No
User Property
pinExternals
Default
false
The file name of the POM to execute any goals against. As of version 3.0.0, this defaults to the name of POM file of the project being built.
Type
java.lang.String
Required
No
User Property
pomFileName
Default
${project.file.name}
Goals to run as part of the preparation step, after transformation but before committing. Space delimited.
Type
java.lang.String
Required
No
User Property
preparationGoals
Default
clean verify
Comma separated profiles to enable on release prepare, in addition to active profiles for project execution.
Type
java.lang.String
Since
3.0.0
Required
No
User Property
preparationProfiles
The path to the SSH private key to use for authentication with the SCM.
See also:
SCM Authentication
Type
java.io.File
Since
3.2.0
Required
No
User Property
privateKey
The role-hint for the
org.apache.maven.shared.release.policy.naming.NamingPolicy
implementation used to calculate the project branch and tag names.
See also:
org.apache.maven.shared.release.policies.DefaultNamingPolicy
Type
java.lang.String
Since
3.0.0-M1
Required
No
User Property
projectNamingPolicyId
Optional config for the VersionPolicy implementation used to calculate the project versions.
Type
org.codehaus.plexus.configuration.PlexusConfiguration
Since
3.0.0
Required
No
User Property
projectVersionPolicyConfig
The role-hint for the
org.apache.maven.shared.release.policy.version.VersionPolicy
implementation used to calculate the project versions.
See also:
Versioning Policies
Type
java.lang.String
Since
2.5.1
Required
No
User Property
projectVersionPolicyId
Default
default
Add a new or overwrite the default implementation per provider. The key is the scm prefix and the value is the role hint/provider id of the
org.apache.maven.scm.provider.ScmProvider
See also:
org.apache.maven.scm.manager.ScmManager.setScmProviderImplementation(java.lang.String,java.lang.String)
SCM Providers
Type
java.util.Map
Since
2.0-beta-6
Required
No
Whether to push changes to the upstream repository or not. Only applicable to distributed version control like Git. Is set to
true
by default to preserve backward compatibility.
Type
boolean
Since
2.1
Required
No
User Property
pushChanges
Default
true
The role-hint for the
org.apache.maven.shared.release.strategy.Strategy
implementation used to specify the phases per goal.
See also:
org.apache.maven.shared.release.strategies.DefaultStrategy
Type
java.lang.String
Since
3.0.0-M5
Required
No
User Property
releaseStrategyId
Default
default
Default version to use when preparing a release or a branch.
Type
java.lang.String
Since
2.0-beta-8
Required
No
User Property
releaseVersion
Currently only implemented with svn scm.
Enables a workaround to prevent issue due to svn client > 1.5.0 (fixed in 1.6.5) (https://issues.apache.org/jira/browse/SCM-406)
You may not want to use this in conjunction with
suppressCommitBeforeTag
, such that no poms with released versions are committed to the working copy ever.
Type
boolean
Since
2.0-beta-9
Required
No
User Property
remoteTagging
Default
true
Resume a previous release attempt from the point where it was stopped.
Type
boolean
Required
No
User Property
resume
Default
true
The message prefix to use for all SCM changes.
Type
java.lang.String
Since
2.0-beta-5
Required
No
User Property
scmCommentPrefix
Default
[maven-release-plugin]
The SCM commit comment for the commit setting pom.xml back to development version. Defaults to "@{prefix} prepare for next development iteration".
Property interpolation is performed on the value, but in order to ensure that the interpolation occurs during release, you must use
@{...}
to reference the properties rather than
${...}
. The following properties are available:
prefix
- The comment prefix.
groupId
- The groupId of the root project.
artifactId
- The artifactId of the root project.
releaseLabel
- The release version of the root project.
Type
java.lang.String
Since
3.0.0-M1
Required
No
User Property
scmDevelopmentCommitComment
Default
@{prefix} prepare for next development iteration
The SCM commit comment for the commit setting pom.xml to release version. Defaults to "@{prefix} prepare release @{releaseLabel}".
Property interpolation is performed on the value, but in order to ensure that the interpolation occurs during release, you must use
@{...}
to reference the properties rather than
${...}
. The following properties are available:
prefix
- The comment prefix.
groupId
- The groupId of the root project.
artifactId
- The artifactId of the root project.
releaseLabel
- The release version of the root project.
Type
java.lang.String
Since
3.0.0-M1
Required
No
User Property
scmReleaseCommitComment
Default
@{prefix} prepare release @{releaseLabel}
When cloning a repository if it should be a shallow clone or a full clone.
Type
boolean
Required
No
User Property
scmShallowClone
Default
true
The server id of the server which provides the credentials for the SCM in the
settings.xml
file. If not set the default lookup uses the SCM URL to construct the server id like this:
server-id=scm-host[":"scm-port]
Currently the POM does not allow to specify a server id for the SCM section.
Explicit authentication information provided via
username
password
or
privateKey
will take precedence.
See also:
SCM Authentication
Type
java.lang.String
Since
3.2.0
Required
No
User Property
project.scm.id
Default
${project.scm.id}
Signs SCM tag when possible, for example when using the git-exe the '--sign' argument is used.
Type
boolean
Since
3.0.0-M4
Required
No
User Property
signTag
Whether to suppress a commit of changes to the working copy before the tag is created.
This requires
remoteTagging
to be set to false.
suppressCommitBeforeTag
is useful when you want to avoid poms with released versions in all revisions of your trunk or development branch.
Type
boolean
Since
2.1
Required
No
User Property
suppressCommitBeforeTag
Default
false
The SCM tag to use.
Type
java.lang.String
Required
No
User Property
tag
Alias
releaseLabel
The tag base directory in SVN, you must define it if you don't use the standard svn layout (trunk/tags/branches). For example,
. The URL is an SVN URL and does not include the SCM provider and protocol.
Type
java.lang.String
Required
No
User Property
tagBase
Format to use when generating the tag name if none is specified. Property interpolation is performed on the tag, but in order to ensure that the interpolation occurs during release, you must use
@{...}
to reference the properties rather than
${...}
. The following properties are available:
groupId
or
project.groupId
- The groupId of the root project.
artifactId
or
project.artifactId
- The artifactId of the root project.
version
or
project.version
- The release version of the root project.
Type
java.lang.String
Since
2.2.0
Required
No
User Property
tagNameFormat
Default
@{project.artifactId}-@{project.version}
Whether to update dependencies version to the next development version.
Type
boolean
Since
2.0-beta-5
Required
No
User Property
updateDependencies
Default
true
Whether to bump the working copy versions to
developmentVersion
Type
boolean
Since
2.1
Required
No
User Property
updateWorkingCopyVersions
Default
true
Whether to use "edit" mode on the SCM, to lock the file for editing during SCM operations.
Type
boolean
Required
No
User Property
useEditMode
Default
false
The username to use for authentication with the SCM.
See also:
SCM Authentication
Type
java.lang.String
Required
No
User Property
username
Wait the specified number of seconds before creating the tag.
waitBeforeTagging
is useful when your source repository is synced between several instances and access to it is determined by geographical location, like the SVN repository at the Apache Software Foundation.
Type
int
Since
2.2
Required
No
User Property
waitBeforeTagging
Default
A workItem for SCMs like RTC, TFS etc, that may require additional information to perform a pushChange operation.
Type
java.lang.String
Since
3.0.0-M5
Required
No
User Property
workItem
US