buildnumber:create

Full name:

org.codehaus.mojo:buildnumber-maven-plugin:1.3: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.
doCheck boolean 1.0-beta-1 If this is made true, we check for modified files, and if there are any, we fail the build. Note that this used to be inverted (skipCheck), but needed to be changed to allow releases to work. This corresponds to 'svn status'.
Default 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.
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 Locale.toString(). The default locale is the platform default returned by 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 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 substitition 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- Local directory to be used to issue SCM actions
Default value is: ${basedir}.
User property is: maven.buildNumber.scmDirectory.
shortRevisionLength int 1.1 Max length of a revision id (used only for git)
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.MessageFormat 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.
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

doCheck:

If this is made true, we check for modified files, and if there are any, we fail the build. Note that this used to be inverted (skipCheck), but needed to be changed to allow releases to work. This corresponds to 'svn status'.
  • 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

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 Locale.toString(). The default locale is the platform default returned by 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 substitition mapping for SCM providers.
  • Type: java.util.Map
  • 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:

Local directory to be used to issue SCM actions
  • Type: java.io.File
  • Since: 1.0-beta-
  • Required: No
  • User Property: maven.buildNumber.scmDirectory
  • Default: ${basedir}

shortRevisionLength:

Max length of a revision id (used only for git)
  • Type: int
  • Since: 1.1
  • Required: No

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.MessageFormat 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

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