buildnumber:create
Full name:
org.codehaus.mojo:buildnumber-maven-plugin:3.1.0:create
Description:
This mojo is designed to give you a build number. So when you might make 100 builds of version 1.0-SNAPSHOT, you can differentiate between them all.
The build number is based on the revision number retrieved from SCM. It is known to work with Subversion, GIT, and Mercurial.
This mojo can also check to make sure that you have checked everything into SCM, before issuing the build number. That behaviour can be suppressed, and then the latest local build number is used.
Build numbers are not automatically reflected in your artifact's filename, but can be added to the metadata. You can access the build number in your pom with ${buildNumber}. You can also access ${timestamp} and the SCM branch of the build (if applicable) in ${scmBranch}
Note that there are several doFoo parameters. These parameters (doCheck, doUpdate, etc) are the first thing evaluated. If there is no matching expression, we get the default-value. If there is (ie -Dmaven.buildNumber.doUpdate=false), we get that value. So if the XML contains <doCheck>true</doCheck>, then normally that's the final value of the param in question. However, this mojo reverses that behaviour, such that the command line parameters get the last say.
Attributes:
- Requires a Maven project to be executed.
- The goal is thread-safe and supports parallel builds.
- Binds by default to the lifecycle phase:
initialize.
Optional Parameters
| Name | Type | Since | Description |
|---|---|---|---|
<buildNumberPropertiesFileLocation> |
File |
1.0-beta-2 |
Properties file to be created when "format" is not null and item has "buildNumber". See Usage for details Default value is: ${basedir}/buildNumber.properties. |
<buildNumberPropertyName> |
String |
1.0-beta-1 |
You can rename the buildNumber property name to another property name if desired. Default value is: buildNumber.User property is: maven.buildNumber.buildNumberPropertyName. |
<buildTaintedPropertyName> |
String |
- |
In cases where the doCheck shows that there are changes in the current working copy this property will be set with the value tainted otherwise it will be ok.Default value is: buildIsTainted.User property is: maven.buildNumber.buildTaintedPropertyName. |
<doCheck> |
boolean |
1.0-beta-1 |
If this is made true, we check for modified files but does not fail the build. If you like to fail the build such cases you have to set the failTheBuild property as well. Settings doCheck to true a property is set to true if there are changesDefault value is: false.User property is: maven.buildNumber.doCheck. |
<doUpdate> |
boolean |
1.0-beta-1 |
If this is made true, then the revision will be updated to the latest in the repo, otherwise it will remain what it is locally. Note that this used to be inverted (skipUpdate), but needed to be changed to allow releases to work. This corresponds to 'svn update'. Default value is: false.User property is: maven.buildNumber.doUpdate. |
<failTheBuild> |
boolean |
3.0.0 |
This will fail the build in cases where doCheck is set to true. Default value is: true.User property is: maven.buildNumber.failTheBuild. |
<format> |
String |
1.0-beta-1 |
Specify a message as specified by java.text.MessageFormat. This triggers "items" configuration to be read User property is: maven.buildNumber.format. |
<getRevisionOnlyOnce> |
boolean |
1.0-beta-3 |
If set to true, will get the scm revision once for all modules of a multi-module project instead of fetching once for each module. Default value is: false.User property is: maven.buildNumber.getRevisionOnlyOnce. |
<items> |
List<?> |
1.0-beta-1 |
Specify the corresponding items for the format message, as specified by java.text.MessageFormat. Special item values are "scmVersion", "timestamp" and "buildNumber[digits]", where [digits] are optional digits added to the end of the number to select a property. |
<locale> |
String |
1.0-beta-2 |
The locale used for date and time formatting. The locale name should be in the format defined in java.util.Locale.toString(). The default locale is the platform default returned by java.util.Locale.getDefault().User property is: maven.buildNumber.locale. |
<password> |
String |
1.0-beta-1 |
The password that is used when connecting to the SCM system. User property is: password. |
<providerImplementations> |
Map<String,String> |
1.0-beta-3 |
Selects alternative SCM provider implementations. Each map key denotes the original provider type as given in the SCM URL like "cvs" or "svn", the map value specifies the provider type of the desired implementation to use instead. In other words, this map configures a substitution mapping for SCM providers. |
<revisionOnScmFailure> |
String |
1.0-beta-2 |
Setting this value allows the build to continue even in the event of an SCM failure. The value set will be used as the revision string in the event of a failure to retrieve the revision it from the SCM. User property is: maven.buildNumber.revisionOnScmFailure. |
<scmBranchPropertyName> |
String |
1.0-beta-4 |
You can rename the buildScmBranch property name to another property name if desired. Default value is: scmBranch.User property is: maven.buildNumber.scmBranchPropertyName. |
<scmDirectory> |
File |
1.0-beta-1 |
Issue SCM actions at this local directory Default value is: ${basedir}.User property is: maven.buildNumber.scmDirectory. |
<shortRevisionLength> |
int |
1.1 |
Max length of a revision id (GIT only) Default value is: 0.User property is: maven.buildNumber.shortRevisionLength. |
<skip> |
boolean |
1.3 |
Whether to skip this execution. Default value is: false.User property is: maven.buildNumber.skip. |
<timestampFormat> |
String |
1.0-beta-2 |
Apply this java.text.SimpleDateFormat to the timestamp only (as opposed to the format parameter).User property is: maven.buildNumber.timestampFormat. |
<timestampPropertyName> |
String |
1.0-beta-1 |
You can rename the timestamp property name to another property name if desired. Default value is: timestamp.User property is: maven.buildNumber.timestampPropertyName. |
<timezone> |
String |
3.0.0 |
The timezone of the generated timestamp. If blank will default to TimeZone#getDefault()User property is: maven.buildNumber.timestampTimeZone. |
<useLastCommittedRevision> |
boolean |
1.0-beta-2 |
whether to retrieve the revision for the last commit, or the last revision of the repository. Default value is: false.User property is: maven.buildNumber.useLastCommittedRevision. |
<username> |
String |
1.0-beta-1 |
The username that is used when connecting to the SCM system. User property is: username. |
Parameter Details
<buildNumberPropertiesFileLocation>
Properties file to be created when "format" is not null and item has "buildNumber". See Usage for details
- Type:
java.io.File - Since:
1.0-beta-2 - Required:
No - Default:
${basedir}/buildNumber.properties
<buildNumberPropertyName>
You can rename the buildNumber property name to another property name if desired.
- Type:
java.lang.String - Since:
1.0-beta-1 - Required:
No - User Property:
maven.buildNumber.buildNumberPropertyName - Default:
buildNumber
<buildTaintedPropertyName>
In cases where the doCheck shows that there are changes in the current working copy this property will be set with the value
tainted otherwise it will be ok.- Type:
java.lang.String - Required:
No - User Property:
maven.buildNumber.buildTaintedPropertyName - Default:
buildIsTainted
<doCheck>
If this is made true, we check for modified files but does not fail the build. If you like to fail the build such cases you have to set the
failTheBuild property as well. Settings doCheck to true a property is set to true if there are changes- Type:
boolean - Since:
1.0-beta-1 - Required:
No - User Property:
maven.buildNumber.doCheck - Default:
false
<doUpdate>
If this is made true, then the revision will be updated to the latest in the repo, otherwise it will remain what it is locally. Note that this used to be inverted (skipUpdate), but needed to be changed to allow releases to work. This corresponds to 'svn update'.
- Type:
boolean - Since:
1.0-beta-1 - Required:
No - User Property:
maven.buildNumber.doUpdate - Default:
false
<failTheBuild>
This will fail the build in cases where doCheck is set to true.
- Type:
boolean - Since:
3.0.0 - Required:
No - User Property:
maven.buildNumber.failTheBuild - Default:
true
<format>
Specify a message as specified by java.text.MessageFormat. This triggers "items" configuration to be read
- Type:
java.lang.String - Since:
1.0-beta-1 - Required:
No - User Property:
maven.buildNumber.format
<getRevisionOnlyOnce>
If set to true, will get the scm revision once for all modules of a multi-module project instead of fetching once for each module.
- Type:
boolean - Since:
1.0-beta-3 - Required:
No - User Property:
maven.buildNumber.getRevisionOnlyOnce - Default:
false
<items>
Specify the corresponding items for the format message, as specified by java.text.MessageFormat. Special item values are "scmVersion", "timestamp" and "buildNumber[digits]", where [digits] are optional digits added to the end of the number to select a property.
- Type:
java.util.List<?> - Since:
1.0-beta-1 - Required:
No
<locale>
The locale used for date and time formatting. The locale name should be in the format defined in
java.util.Locale.toString(). The default locale is the platform default returned by java.util.Locale.getDefault().- Type:
java.lang.String - Since:
1.0-beta-2 - Required:
No - User Property:
maven.buildNumber.locale
<password>
The password that is used when connecting to the SCM system.
- Type:
java.lang.String - Since:
1.0-beta-1 - Required:
No - User Property:
password
<providerImplementations>
Selects alternative SCM provider implementations. Each map key denotes the original provider type as given in the SCM URL like "cvs" or "svn", the map value specifies the provider type of the desired implementation to use instead. In other words, this map configures a substitution mapping for SCM providers.
- Type:
java.util.Map<java.lang.String, java.lang.String> - Since:
1.0-beta-3 - Required:
No
<revisionOnScmFailure>
Setting this value allows the build to continue even in the event of an SCM failure. The value set will be used as the revision string in the event of a failure to retrieve the revision it from the SCM.
- Type:
java.lang.String - Since:
1.0-beta-2 - Required:
No - User Property:
maven.buildNumber.revisionOnScmFailure
<scmBranchPropertyName>
You can rename the buildScmBranch property name to another property name if desired.
- Type:
java.lang.String - Since:
1.0-beta-4 - Required:
No - User Property:
maven.buildNumber.scmBranchPropertyName - Default:
scmBranch
<scmDirectory>
Issue SCM actions at this local directory
- Type:
java.io.File - Since:
1.0-beta-1 - Required:
No - User Property:
maven.buildNumber.scmDirectory - Default:
${basedir}
<shortRevisionLength>
Max length of a revision id (GIT only)
- Type:
int - Since:
1.1 - Required:
No - User Property:
maven.buildNumber.shortRevisionLength - Default:
0
<skip>
Whether to skip this execution.
- Type:
boolean - Since:
1.3 - Required:
No - User Property:
maven.buildNumber.skip - Default:
false
<timestampFormat>
Apply this
java.text.SimpleDateFormat to the timestamp only (as opposed to the format parameter).- Type:
java.lang.String - Since:
1.0-beta-2 - Required:
No - User Property:
maven.buildNumber.timestampFormat
<timestampPropertyName>
You can rename the timestamp property name to another property name if desired.
- Type:
java.lang.String - Since:
1.0-beta-1 - Required:
No - User Property:
maven.buildNumber.timestampPropertyName - Default:
timestamp
<timezone>
The timezone of the generated timestamp. If blank will default to
TimeZone#getDefault()- Type:
java.lang.String - Since:
3.0.0 - Required:
No - User Property:
maven.buildNumber.timestampTimeZone
<useLastCommittedRevision>
whether to retrieve the revision for the last commit, or the last revision of the repository.
- Type:
boolean - Since:
1.0-beta-2 - Required:
No - User Property:
maven.buildNumber.useLastCommittedRevision - Default:
false
<username>
The username that is used when connecting to the SCM system.
- Type:
java.lang.String - Since:
1.0-beta-1 - Required:
No - User Property:
username