Fork me on GitHub
Built by Maven

buildnumber:create

Full name:

org.codehaus.mojo:buildnumber-maven-plugin:3.2.1: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: ${basedir}/buildNumber.properties
<buildNumberPropertyName> String 1.0-beta-1 You can rename the buildNumber property name to another property name if desired.
Default: buildNumber
User Property: 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: buildIsTainted
User Property: 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 changes
Default: false
User Property: 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: false
User Property: maven.buildNumber.doUpdate
<failTheBuild> boolean 3.0.0 This will fail the build in cases where doCheck is set to true.
Default: true
User Property: 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: 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: false
User Property: maven.buildNumber.getRevisionOnlyOnce
<ignoreEmptyScmUrl> boolean 3.2.1 Ignore error when scm url from pom is empty and replace by scm:scmProvider scmProvider
Default: false
User Property: maven.buildNumber.ignoreEmptyScmUrl
<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: maven.buildNumber.locale
<password> String 1.0-beta-1 The password that is used when connecting to the SCM system.
User Property: 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: maven.buildNumber.revisionOnScmFailure
<scmBranchPropertyName> String 1.0-beta-4 You can rename the buildScmBranch property name to another property name if desired.
Default: scmBranch
User Property: maven.buildNumber.scmBranchPropertyName
<scmDirectory> File 1.0-beta-1 Issue SCM actions at this local directory
Default: ${basedir}
User Property: maven.buildNumber.scmDirectory
<scmProvider> String 3.2.1 When scm url is empty, scm provider is needed ignoreEmptyScmUrl
Default: git
User Property: maven.buildNumber.scmProvider
<shortRevisionLength> int 1.1 Max length of a revision id (GIT only)
Default: 0
User Property: maven.buildNumber.shortRevisionLength
<skip> boolean 1.3 Whether to skip this execution.
Default: false
User Property: 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: maven.buildNumber.timestampFormat
<timestampPropertyName> String 1.0-beta-1 You can rename the timestamp property name to another property name if desired.
Default: timestamp
User Property: maven.buildNumber.timestampPropertyName
<timezone> String 3.0.0 The timezone of the generated timestamp. If blank will default to TimeZone#getDefault()
User Property: 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: false
User Property: maven.buildNumber.useLastCommittedRevision
<username> String 1.0-beta-1 The username that is used when connecting to the SCM system.
User Property: 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

<ignoreEmptyScmUrl>

Ignore error when scm url from pom is empty and replace by scm:scmProvider scmProvider
  • Type: boolean
  • Since: 3.2.1
  • Required: No
  • User Property: maven.buildNumber.ignoreEmptyScmUrl
  • 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}

<scmProvider>

When scm url is empty, scm provider is needed ignoreEmptyScmUrl
  • Type: java.lang.String
  • Since: 3.2.1
  • Required: No
  • User Property: maven.buildNumber.scmProvider
  • Default: git

<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