SCM Version Plugin

Table of Contents

Summary
Version Information from the SCM
Configuration with a Static Version
- Git Version Calculation
Usage
Tasks
Project Extension 'scm'
- Methods
- Properties
Example Configurations
Contribute
License

Note	Version 7.0 (and later) of this plugin will only work with JDK 17, Gradle 8.5 and later.

Summary

Based on the used SCM (Source Control Management) this plugin provides project configuration handling and specific tasks regarding the version handling of the project. The information of the used SCM is identified by special directories in the project directory ('.git'). Only Git is full supported and all others uses a file implementation. But the "file" support is limited.

Git Branches and tags are used for the calculation of the project version.

Note	A file-based project does not support the calculation of the version based on previous versions.

It is also possible to identify the changes between the current working copy and the previous version. This functionality can also be used on a CI server during the creation of a new tag. In this case the changes between two versions are written to a file.

Version Information from the SCM

This plugin adds the possibility to calculate version information of a project from the used SCM structure. It initializes a project property useSCMVersionConfig. The value of this property is true, if the plugin was applied and can be used by the own build logic and other plugins.

Configuration with a Static Version

This configuration is also working without any remote access, but project specific, because the replacement for the version information is stored in the build directory of the project. If <project build dir>/scmversion/static.version exists and the content is not empty, the content of this is used for the version.

If the first call of a project task is started with a parameter staticVersion and a version information, the file will be created with the version information.

gradlew -PstaticVersion=TRUNKVER publish

This will set the version to TRUNKVER. The project runs now always with this version. It is possible to remove this configuration with an empty string for staticVersion or if exists with the task clean.

gradlew -PstaticVersion= publish

Git Version Calculation

The version can be calculated from the local clone without access to the remote repository. The plugin assumes, that the default branch is called 'master'.

The plugin detects tags and branches with version information on special prefixes. These prefixes are configured based on the configuration 'prefixes'. For parsing, calculation and sorting a library for an extended version object is used. The library supports version numbers with three or four decimal numbers. Furthermore a special pattern is supported.

<prefix>_<version>[-<featurebranch name>][-<build extension>]

Therefore branch names must comply with the following patterns. All examples use the default configuration. If no prefix is specified the plugin assumes that the branch is a feature branch. If the version is not part of the branch name, the version is taken from the last tag.

Feature Branches, Hotfix Branches and Bugfix Branches

<feature, hotfix or bugfix branch prefix>_<version>-<branch name>

These are the default values

Branch Type	Default value
Feature Branch	`'FB'`
Hotfix Branch	`'HB'`
Bugfix Branch	`'BB'`

The version is the original version of the master/trunk.

Example

FB_1.0.0-JIRA-4711
FB_1.0.0-FeatureBranchName

Stabilization branch

<stabilization branch prefix>_<version>

The default stabilization branch prefix is 'SB'. The version is the base version for this branch. In most cases, it is the major version of the master/trunk, before the branch was created.

Example

SB_1        Stabilization branch for version 1.0.0 to 1.X.X
SB_1.0      Stabilization branch for version 1.0.0 to 1.0.X

Release Tag

<release prefix>_<version>[-<featurebranch name>][-<build extension>]

The default release prefix is 'RELEASE'. The version is the base version of the branch. In the most cases, it is the major version of the master/trunk, before the branch was created.

Example

RELEASE_1.1.0                   Release tag for version 1.1.0
RELEASE_1.1.0-dev.1             Tag of a development milestone release for version 1.1.0
RELEASE_1.1.0-rc.1              Tag of a release candidate for version 1.1.0
RELEASE_1.0.0-JIRA-4711-dev.1   Tag of a development milestone release of a feature branch version 1.0.0-JIRA-4711

Version Calculation on Git - Summary

Default Branch (master)
The plugin is looking for a tag on the branch. If there is no tag the default value is used and extended with SNAPSHOT.
Branch / Feature,Hotfix,Bugfix Branch
The plugin is looking for a tag on the branch. If there is no valid tag on the branch, the version is taken from the name of the branch. The version will be always extended with SNAPSHOT on the CI server.
Tags
Without local changes the plugin tries to calculate the name from the tag name.

A checkout of a single commit (detached head) without a tag name will be specially treated. The last found version is used for the version string. This is extended by the short hash value and 'SNAPSHOT', e.g. 2.0.0-rev.id.ad73b69-SNAPSHOT. If the environment variable 'CONTINUOUSRELEASE' or the project variable 'continuousRelease' is set, the extension SNAPSHOT is not added.

Usage

To use the Gradle SCM Version plugin provided by Intershop, include the following in your build script of your root project:

Groovy

build.gradle

plugins {
    id 'com.intershop.gradle.scmversion' version '7.0.0'
}

scm {
    prefixes {
        //default is 'SB'
        stabilizationPrefix = 'SBP'

        //default is 'FB'
        featurePrefix = 'FBP'

        //default is 'HB'
        hotfixPrefix = 'HBP'

        //default is 'BB'
        bugfixPrefix = 'BBP'

        //default is Release
        tagPrefix = 'RBP'
    }

    version {
        type = 'threeDigits'
        initialVersion = '1.0.0'
    }

    changelog {
        targetVersion = '1.0.0'
        changelogFile = new File(project.buildDir, 'changelog/changelogset.asciidoc')
    }
}

version = scm.version.version

Kotlin

build.gradle.kts

plugins {
    id("com.intershop.gradle.scmversion") version "7.0.0"
}

scm {
    prefixes {
        //default is "SB"
        stabilizationPrefix = "SBP"

        //default is "FB"
        featurePrefix = "FBP"

        //default is "HB"
        hotfixPrefix = "HBP"

        //default is "BB"
        bugfixPrefix = "BBP"

        //default is Release
        tagPrefix = "RBP"
    }

    version {
        type = "threeDigits"
        initialVersion = "1.0.0"
    }

    changelog {
        previousVersion = "1.0.0"
        changelogFile = File(project.buildDir, "changelog/changelogset.asciidoc")
    }
}

version = scm.version.version

Tasks

The Intershop SCM Version plugin adds the following tasks to the project:

Task name	Type	Description
showVersion	ShowVersion	This task shows the current version of the working copy.
tag	CreateTag	This task creates a tag based on the current working copy. It makes changes to the SCM.
branch	CreateBranch	This task creates a branch based on the current working copy. It makes changes to the SCM. For creating a feature branch it is necessary to specify a short name for the feature. This can be done over the commandline parameter `--feature`.
toVersion	ToVersion	This task moves the working copy to a target version. This version must be specified in a configuration or on the commandline with the paramater `--version`. It is also possible to specify the short name of a feature (command line parameter `--feature`) and the kind of branch (command line parameter `--branchType`), that should be used. It changes the working copy.
release	PrepareRelease	This task creates a tag, if necessary, and move the the working copy to the version. It changes the working copy.
changelog	CreateChangeLog	This task creates a change log with all changes between the latest commit of the current working copy and the previous version. It is possible to specify a 'previous' version with the command line variable `--prevVersion`. The tag for this version is mandatory.

The tasks tag, branch, toVersion, release and changelog can be started with the commandline parameter --dryRun. If this parameters is specified no changes on the remote or local repsotiroy will be done. Only the output will provide information over posible changes.

All task are part of the package 'com.intershop.gradle.scm.task'

Project Extension 'scm'

This plugin adds an extension scm to the root project. This extension contains all plugin configurations.

Methods

Method	Values	Description
user(Closure<ScmUser>) user(Action<in ScmUser>)	ScmUser	This extension is used for the SCM user authentication. This extension can be configured over environment variables and project properties.
key(Closure<ScmUser>) key(Action<in ScmKey>)	ScmKey	This is also used for the SCM user authentication. This extension can be configured over environment variables and project properties.
prefixes(Closure<PrefixConfig>) prefixes(Action<in PrefixConfig>)	PrefixConfig	This is the extension object for the configuration of branch prefixes.
version(Closure<VersionExtension>) version(Action<in VersionExtension>)	VersionExtension	This extension contains settings for version calculation and reads properties for the current version and previous version.
changelog(Closure<ChangeLogExtension>) changelog(Action<in ChangeLogExtension>)	ChangeLogExtension	This extension contains settings for change log configuration.

Properties

Property	Type	Description
user	ScmUser	This property contains the complete user configuration.
key	ScmKey	This property contains the complete SSH key configuration.
prefixes	PrefixConfig	This is the container for the prefix configuration.
scmType	ScmType	This is the value for the identified SCM ( GIT, FILE )
localService	ScmLocalService	This sevices contains all main necessary methods for the working copy.
version	VersionExtension	This is the configuration for the version calculation.
changelog	ChangeLogExtension	This is the configuration for the change log task.

Authentication

User object 'user' (`ScmUser`)

Property	Type	Default value	Description
name	`String`	''	Username or token This can be overwritten by the environment variable `SCM_USERNAME` or project or system property `scmUserName`.
password	`String`	''	Password This can be overwritten by the environment variable `SCM_PASSWORD` or project or system property `scmUserPasswd`.

SSH Key object 'key' (`ScmKey`) (only for Git)

Property	Type	Default value	Description
file	`File`	`null`	Private key for SCM authentication This can be overwritten by the environment variable `SCM_KEYFILE` or project or system property `scmKeyFile`. The plugin uses per default for ssh access <user_home>/.ssh/id_rsa or <user_home>/.ssh/id_dsa without passphrase.
passphrase	`String`	''	passphrase for private key This can be overwritten by the environment variable `SCM_KEYPASSPHRASE` or project or system property `scmKeyPassphrase`.

Prefix configuration 'prefixes' (`PrefixConfig`)

Property	Type	Default value	Description
stabilizationPrefix	`String`	`SB`	Prefix for stabilization branches
featurePrefix	`String`	`FB`	Prefix for feature branches
hotfixPrefix	`String`	`HB`	Prefix for hotfix branches
bugfixPrefix	`String`	`BB`	Prefix for bugfix branches
tagPrefix	`String`	`RELEASE`	Prefix for release tags
prefixSeperator	`String`	`_`	Separator between prefix and version
branchPrefixSeperator	`String`	`null`	Separator between prefix and branch version
tagPrefixSeperator	`String`	`null`	Separator between prefix and tag version

Version object 'version' (`VersionExtension`)

Property	Type	Default value	Values	Description
versionService	`ScmVersionService`			This service contains methods and properties for the calculation of version objects from the working copy.
type	`String`	`threeDigits`	`fourDigits` `threeDigits`	The number of used decimal numbers for a version number.
versionType	`VersionType`		read only	Get the VersionType object from the configured type.
versionExt	`String`	''	read only	see description for `disableSCM`. The environment variable `SCMVERSIONEXT` or the system property `scmVersionExt` is used for the return value.
versionBranch	`String`	'TAG'	'TAG' + 'BRANCH'	Set the version branch configuration of the version calculation. The branch which is primarily used for the version calculation. This can be branch or tag.
versionBranchType	`BranchType`	'BranchType.TAG'	read only	This get the calculated BranchType object from versionBranch configuration.
version	`String`	initialVersion	read only	Returns the version of the working copy
previousVersion	`String`	''	read only	Returns the previous version of the working copy.
branchName	`String`	''	read only	Returns the branch name only (String after last /)
increment	`String`	`null`	`MAJOR` `MINOR` `PATCH` `HOTFIX`	If this property is set, the configured position is used for incrementing the version. This can be overwritten by the environment variable `INCREMENT`, or system property `increment`.
initialVersion	`String`	`'1.0.0.0'` `'1.0.0'`		The inital version if a calculation from SCM is not possible.
branchType	`String`	`tag`	`branch` `tag`	The branch which is primarily used for the version calculation.
patternDigits	`int`	`2`	`1` `2` `3` (available only if ScmVersion `type` is `fourDigits`)	Determines the number of digit blocks of the version number that will be used for calculating the version filter from branches.
defaultMetadata	`String`	''		This is used for releases of feature branches.
useBuildExtension	`boolean`	`false`	`false` `true`	Build extension will be removed for SNAPSHOT extensions if this property is false.
majorVersionOnly	`boolean`	`true`		This property affects only GIT based repositories. If this property is true, the version is always only the major version. If the increment property is always configure for MAJOR the version will be increased.
disableSCM	`boolean`	`false`	`false` `true`	If this property is `true`, the initial version is always used and the SCM usage is disabled. The environment variable `'SCMVERSIONEXT'` or the project variable `'scmVersionExt'` will be used on the CI server for special extensions. If set to: `'SNAPSHOT'` - `'SNAPSHOT'` will be added to the version. `'RELEASE'` - intial version is used without any extension. If no value is specified a time stamp will be added.
disableRevExt		`boolean`	`false`	`false` `true`
With this configuration the extension of the rev id in special cases can be disabled. It is possible to set this configuration with the environment variable 'SCM_DISABLE_REVIDEXT' or the system or project property 'scmDisableRevIdExt'.	continuousRelease	`boolean`	`false`	`false` `true`
For continuous releases it is helpful to use an version extension with an relation to the source control. It is possible to enable this configuration also over the environment variable `'CONTINUOUSRELEASE'` or the system property `'continuousRelease'`.	continuousReleaseBranches	`List<String>`	`[]`	Branchnames

Changelog Object 'changeLog' (`ScmChangeLog`)

Property	Type	Default value	Description
previousVersion	`String`	version.previousVersion	Any version with tag for change log calculation. It is possible to override the value with the enviroment variable `PREV_VERSION`
changelogFile	`File`	`<buildDir>/changelog/ changelog.asciidoc`	The change log will be written to this file. The log file is empty, if the previous version does not exists.

Method	Values	Description

Example Configurations

Simple Configuration

plugins {
    id 'com.intershop.gradle.scmversion' version '7.0.0'
}


scm {
    version {
        type = 'threeDigits'
        initialVersion = '1.0.0'
    }
}

version = scm.version.version

gradle.properties with Authentication Configuration

This configuration works for Git [http(s)]. It is necessary to specify username and password for this kind of repositories.

scmUserName = username
scmUserPasswd = password

This configuration works for Git [ssh] with a private key and if necessary with a passphrase. There is no default value for the key.

# without passphrase
scmKeyFile = /user/home/.ssh/id_rsa

# with passphrase
scmKeyFile = /user/home/.ssh/id_rsa
scmKeyPassphrase = passphrase

To use ssh keys you have to switch your repository from https to ssh with the following command:

git remote set-url origin git@gitlab.coporate.com:yourname/yourrepo.git

Simple Configuration Without SCM

This configuration can be used when a different version control system is used in the project or another version schema is set in the project.

Note	Using this configuration a lot of the features are no longer available.

plugins {
    id 'com.intershop.gradle.scmversion' version '7.0.0'
}

scm {
    version {
        disableSCM = true
        initialVersion = '1.0.0'
    }
}

version = scm.version.version

On a CI server some properties must be transfered via the command line:

snapshot build:

./gradlew publish -PscmVersionExt=SNAPSHOT

release build:

./gradlew publish -PscmVersionExt=RELEASE

Note	After a release it is necessary to change the version manually.

Test

The integration tests use test repositories. Therefore, it is necessary to specify project properties for the test execution.

Table 1. Git test configuration

Test Property	Description	Value
giturl	URL of the test project	Must be specified with environment variable `GITURL`
gituser	User name of Git test user	Must be specified with environment variable `GITUSER`
gitpasswd	Password for Git test user	Must be specified with environment variable `GITPASSWD`

Contribute

See here for details.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.asciidoc

README.asciidoc

SCM Version Plugin

Summary

Version Information from the SCM

Configuration with a Static Version

Git Version Calculation

Feature Branches, Hotfix Branches and Bugfix Branches

Stabilization branch

Release Tag

Version Calculation on Git - Summary

Usage

Tasks

Project Extension 'scm'

Methods

Properties

Authentication

User object 'user' (`ScmUser`)

SSH Key object 'key' (`ScmKey`) (only for Git)

Prefix configuration 'prefixes' (`PrefixConfig`)

Version object 'version' (`VersionExtension`)

Changelog Object 'changeLog' (`ScmChangeLog`)

Example Configurations

Simple Configuration

gradle.properties with Authentication Configuration

Simple Configuration Without SCM

Test

Contribute

License

Files

README.asciidoc

Latest commit

History

README.asciidoc

File metadata and controls

SCM Version Plugin

Summary

Version Information from the SCM

Configuration with a Static Version

Git Version Calculation

Feature Branches, Hotfix Branches and Bugfix Branches

Stabilization branch

Release Tag

Version Calculation on Git - Summary

Usage

Tasks

Project Extension 'scm'

Methods

Properties

Authentication

User object 'user' (ScmUser)

SSH Key object 'key' (ScmKey) (only for Git)

Prefix configuration 'prefixes' (PrefixConfig)

Version object 'version' (VersionExtension)

Changelog Object 'changeLog' (ScmChangeLog)

Example Configurations

Simple Configuration

gradle.properties with Authentication Configuration

Simple Configuration Without SCM

Test

Contribute

License

User object 'user' (`ScmUser`)

SSH Key object 'key' (`ScmKey`) (only for Git)

Prefix configuration 'prefixes' (`PrefixConfig`)

Version object 'version' (`VersionExtension`)

Changelog Object 'changeLog' (`ScmChangeLog`)