gradle-android-git-version

A gradle plugin to calculate Android-friendly version names and codes from git tags. If you are tired of manually updating your Android build files for each release, or generating builds that you can't trace back to code, then this plugin is for you!

Usage

Add the plugin the top of your app/build.gradle (or equivalent):

plugins {
    id 'com.gladed.androidgitversion' version '0.2.21'
}

Set versionName and versionCode from plugin results:

android {
    // ...
    defaultConfig {
        // ...
        versionName androidGitVersion.name()
        versionCode androidGitVersion.code()

Use a git tag to specify your version number (see Semantic Versioning)

$ git tag 1.2.3
$ gradle --quiet androidGitVersion
androidGitVersion.name	1.2.3
androidGitVersion.code	1002003

Any suffix after the version number in the tag (such as -release4 in 1.2.3-release4) is included in the version name, but is ignored when generating the version code.

Intermediate Versions

For builds from commits that are not explicitly tagged, name() will return a build of this form:

1.2.3-2-93411ff-fix_issue5-dirty

The components in the example above are as follows:

1.2.3	-2	-93411ff	-fix_issue5	-dirty
Most recent tag	Number of commits since tag	Commit prefix	Branch name, if branch is not listed in `hideBranches`	Present only there are uncommitted changes

Version Codes

Version codes are calculated relative to the most recent tag.

The code is generated by combining each version part with a multiplier. Unspecified version parts are assumed to be zero even if not supplied. So version 1.22 becomes 1022000, while version 2.4.11 becomes 2004011. This allows successive versions to have incrementing version codes.

Intermediate versions do not produce a new code. The code only advances when a new version tag is specified.

You can configure this behavior with multiplier and parts properties, but be warned that changing the version code scheme for a released Android project can cause problems if your new version code does not increase monotonically.

Methods

name() returns the current version name.

code() returns the current version code.

flush() flushes the internal cache of information about the git repo, in the event you have a gradle task that makes changes.

Tasks

androidGitVersion prints the name and code, as shown above.

androidGitVersionName prints only the name.

androidGitVersionCode prints only the code.

Configuration Properties

An androidGitVersion block in your project's build.gradle file can supply optional properties to configure this plugin's behavior, e.g.:

androidGitVersion {
    prefix 'lib-'
    onlyIn 'my-library'
    multiplier 10000
    parts 2
    baseCode 2000
    hideBranches = [ 'develop' ]
    format = '%tag%%.count%%<commit>%%-branch%%...dirty%'
}

prefix (string)

prefix sets the required prefix for any relevant version tag. For example, with prefix 'lib', the tag lib-1.5 is used to determine the version, while tags 1.0 are app-2.4.2 are ignored.

The default prefix is '', which matches all numeric version tags.

onlyIn (string)

onlyIn sets the required path for relevant files. Commits that change files in this path will count, while other commits will not.

For example, consider this directory tree:

+-- my-app/
    +-- .git/
    +-- build.gradle
    +-- app/
    |   +-- build.gradle
    |   +-- src/
    +-- lib/
        +-- build.gradle
        +-- src/

If my-app/lib/build.gradle is configured with onlyIn 'lib', then changes to files in other paths (like my-app/build.gradle or my-app/app/src) will not affect the version name.

The default onlyIn path is '', which includes all paths.

multiplier (int)

multiplier sets the space allowed each part of the version when calculating the version code.

For example, if you want version 1.2.3 to have a version code of 100020003 (allowing for 9999 patch increments), use multiplier 10000.

Use caution when increasing this value, as the maximum version code is 2147483647 (the maximum integer).

The default multiplier is 1000.

parts (int)

parts sets the number of parts the version number will have.

For example, if you know your product will only ever use two version number parts (1.2) then use parts 2.

Use caution when increasing this value, as the maximum version code is 2147483647 (the maximum integer).

The default number of parts is 3.

baseCode (int)

baseCode sets a floor for all generated version codes. Use this when you have already released a version with a code, and don't want to go backwards.

The default baseCode is 0.

hideBranches (list of strings)

hideBranches describes which branches which should not be mentioned explicitly when building intermediate versions (that is, versions without a tag). This will result in cleaner intermediate version names when the branch name is obvious.

The default hideBranches are [ 'master', 'release' ], meaning that intermediate builds will not show these branch names.

Note that each element of hideBranches is interpreted as a regex, for example, [ 'master', 'feature/.*' ].

format (string)

format defines the form of the version name.

Parts include tag (the last tag), count (number of commits, if any, since last tag), commit (most recent commit prefix, if any, since the last tag), branch (branch name, if current branch is not in hideBranches), and dirty (inserting the word "dirty" if the build was made with uncommitted changes).

Parts are delimited as %PARTNAME%. Other characters appearing between % marks are preserved. Parts may be omitted in which case they will not appear in the version name.

arkty / gradle-android-git-version