generates a project version for the given git project to distinguish between builds
Switch branches/tags
Nothing to show
Clone or download
passsy Merge pull request #14 from passsy/custom_short_name
Add closure to config to generate a custom short name
Latest commit 84bab63 Dec 13, 2016

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. This is not possible 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 in history is clear. This projects aims to bring the SVN simplicity and more back to git for your gradle (android) project.

####Read the story behind on medium


Just count the commits of the main 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 insights of 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. This means that the revision count increases 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 you have uncommited files it adds the count of the uncommited files and "-SNAPSHOT"

Reading the Version

Normal build number


1083: number of commits + time component. this revision is in the master branch.

On a feature branch


-dm4: 4 commits since branching from revision 1083. First two [a-z] chars of the base64 encoded 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


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

Get it

Configure the plugin in you 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: ''

// 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 inforamtion 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;


Display the version in your android app

app build.gradle

android {
    defaultConfig {

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

in your Activity

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


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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.