Versioner

Usage:

# gradle.build
apply plugin: 'com.sarhanm.versioner'

You'll need to add the plugin to your buildscript dependencies. Follow these instructions

Options

There are many options to configuring the project version. Look at com.sarhanm.versioner.VersionerOptions for a complete list of options.

Example:

apply plugin: 'com.sarhanm.versioner'
versioner{
  omitBranchMetadata=true
}

GitData

The plugin adds an object gitdata to your build that contains the metadata of the version. This can help in identifying which branch you are on or the current commit hash, amongst other things.

Example:

apply plugin: 'com.sarhanm.versioner'
def branch = gitdata.branch
println "The branch is ${branch}"

Scheme

The version scheme:

For branch named master, release/.* or hotfix/.*

{major}.{minor}.{#-of-commits-from-tag}[.{hotfix-number}].{branch-name}.{short-commit-hash}

All other branches

0.0.{#-of-commits-from-beginning-of-time}.{hotfix-number}.{branch-name}.{short-commit-hash}

NOTE: in this case, we name space out the version string and prepend with 0.0. More on this and how to configure it below.

Snapshot versions for branches named master, release/.* and hotfix/.*

{major}.{minor}.{branch-name}-SNAPSHOT

Snapshot versions for all other branches

0.0.{branch-name}-SNAPSHOT

{major}.{minor}:

The major and minor parts of the version are derived from the newest git tag that starts with a 'v'.

Example tags:

v1.0
v2.3

This value will be used only for branch names master, hotfix/.* and release/.*.

All other branches get a major.minor of 0.0. This helps keep the version scheme uploaded to nexus clean (or any other artifact repository ).

This can be configured via com.sarhanm.versioner.VersionerOptions:solidBranchRegex, so you could configure the plugin to always use the git tag for all branches.

{#-of-commits-from-tag}:

The is the number of commits from the most recent v{major}.{minor} tag.

{#-of-commits-from-beginning-of-time}

This is the number of commits since the inception of the git repo.

{hotfix-number}:

This is the number of commits in the current branch that do not yet exist in the master branch. This assumes that hotfix branches are forked from master.

This is configurable via com.sarhanm.versioner.VersionerOptions:commonHotfixBranch

This value ONLY exists if the branch name contains the word hotfix

{branch-name}:

This is the branch name of the repo.

Branch name is cleansed to remove origin/ and remote/ and converts / and . to -

On build boxes, the branch name is derived from environment variables.

Jenkins --> $GIT_BRANCH
Travis --> $TRAVIS_BRANCH

For other build systems, you'll need to configure the env key that contains the branchName. Use the com.sarhanm.versioner.VersionerOptions:branchEnvName

NOTE: The reason we use environment variables to determine the branch name is that most build systems checkout a repo at a commit, which is a detached head. In this case, we have no way to determine what the branch name is without the help of the build system.

{short-commit-hash}

This is the short commit hash. Super useful to look at an artifact and know how to get to it to start a hotfix or development.

Shallow Clones

For any shallow clone of the repo:

1. {#-of-commits-from-beginning-of-time} will be based on the depth of your clone. Therefore the value is always wrong in a shallow clone.

2. {#-of-commits-from-tag} will only work if the clone is deep enough to retrieve the latest tag. Otherwise the {#-of-commits-from-beginning-of-time} is useds

Travis CI has a default git depth of 50. Make sure to set your depth based on the above information

Example .travis file

git:
  depth: 100