buildnumber:create

Full name:

org.codehaus.mojo:buildnumber-maven-plugin:1.2: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 only works with subversion, currently. 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 reflected in your artifact's filename (automatically), 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 do 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.
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.
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.
format String 1.0-beta-1 Specify a message as specified by java.text.MessageFormat. This triggers "items" configuration to be read
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.
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().
password String 1.0-beta-1 The password that is used when connecting to the SCM system.
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.
scmBranchPropertyName String 1.0-beta-4 You can rename the buildScmBranch property name to another property name if desired.
Default value is: scmBranch.
scmDirectory File 1.0-beta- Local directory to be used to issue SCM actions
Default value is: ${basedir}.
shortRevisionLength int 1.1 Max length of a revision id (used only for git)
timestampFormat String 1.0-beta-2 Apply this java.text.MessageFormat to the timestamp only (as opposed to the format parameter).
timestampPropertyName String 1.0-beta-1 You can rename the timestamp property name to another property name if desired.
Default value is: timestamp.
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.
username String 1.0-beta-1 The username that is used when connecting to the SCM system.

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
  • Expression: ${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
  • Expression: ${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
  • Expression: ${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

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
  • 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
  • Expression: ${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
  • Expression: ${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

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
  • Expression: ${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
  • Expression: ${maven.buildNumber.scmDirectory}
  • Default: ${basedir}

shortRevisionLength:

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

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

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
  • Expression: ${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
  • Expression: ${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
  • Expression: ${username}