Git Versioner for gradle

Version numbers are hard.

It was easier with SVN where the revision number got increased for every commit. Revision 342 was clearly older than revision 401. But this is not feasible in git because branching is so common (and that's a good thing). 342 commits could mean multiple commits on different branches. Not even the latest common commit is clear in history.

This projects aims to bring the SVN simplicity and more back to git for your gradle (android) project.

Read the story behind this on Medium.

Idea

Just count the commits of the default branch (master or develop in most cases) as the base revision. The commits on the feature branch are counted too, but are shown separately.

This technique is often used and far better than just a SHA1 of the latest commit. But I think it gives too much insight into the project. Once a client knows commit count == version number they start asking why the commit count is so high/low for the latest release.

That's why this versioner adds the project age (initial commit to latest commit) as seconds part to the revision. By default, one year equals 1000 increments. This means that the revision count increases approximately every 8.67 hours. When you started your project half a year ago and you have 325 commits the revision is something around 825.

When working on a feature branch, this versioner adds a two char identifier of the branch name and the commit count since branching. When you are building and have uncommitted files, it adds the count of the uncommitted files and -SNAPSHOT.

Understanding the Version

Normal build number

1083

1083 : number of commits + time component. This revision is in the default branch.

On a feature branch

1083-dm4

-dm4 : 4 commits since branching from revision 1083. First two [a-z] chars of the SHA-1 hashed branch name. Clients don't have to know about your information and typos in branch names. But you have to be able to distinguish between different builds of different branches.

Build with local changes

1083-dm4(6)-SNAPSHOT

(6)-SNAPSHOT : 6 uncommitted but changed files. Hopefully nothing a client will ever see. But you know that your version is a work in progress with some local changes.

Usage

Configure the plugin in your top level build.gradle. This makes total sense because it's the revision of the top level project and not of a single module.

// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
    // ...
}

// Optional: configure the versioner
ext.gitVersioner = [
        defaultBranch            : "develop",                       // default "master"
        stableBranches           : ["master", "someOtherBranch"],   // default [], the feature branch postfix (-dm4(6)) will not be appended on stable branches, all commits are included into the version number calculation
        yearFactor               : 1200, 	                        // default "1000", increasing every 8.57h
        snapshotEnabled          : false,                           // default false, the "-SNAPSHOT" postfix
        localChangesCountEnabled : false,                           // default false, the (<commitCount>) before -SNAPSHOT
        shortName: { gitVersion ->                                  // optional closure to build a short name
          // allows you to add your own short name logic
          // All properties from gitVersion are available
          // can be used for CI `System.getenv("BUILD_NUMBER")`

          // i.e. use short sha1
          return gitVersion.commit.subSequence(0, 7)
        }
]

// import the script which runs the version generation
apply from: 'https://raw.githubusercontent.com/passsy/gradle-GitVersioner/master/git-versioner.gradle'

// variable `gitVersionName` can be used everywhere to get the revision name
println("versionName: $gitVersionName") // output: "versionName: 1083-dm4(6)-SNAPSHOT"

Consider using this cache plugin for offline support.

All information is not only available as a single String. You can create your own pattern using the ext.gitVersion Object

// get granular information with variable `gitVersion` of type `GitVersion`
println("version: ${gitVersion.version}") // output "version: 1083"

// see all available attributes
class GitVersion {
    String name;
    int version;
    String branchName;
    String shortBranch;
    int branchVersion;
    int localChanges;
    String commit;
}

Android

Display the version in your android app

app build.gradle

android {
    defaultConfig {
        ...

        buildConfigField 'String', 'REVISION', "\"$gitVersionName\""
    }
}

in your Activity

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    	Toast.makeText(this, BuildConfig.REVISION, Toast.LENGTH_SHORT).show();
    }

License

Copyright 2016 Pascal Welsch

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.