feature: add configurable settings

README.md

@@ -3,7 +3,12 @@ A Gradle plugin for applying project version from Git tags.
 
 [![Build Status](https://travis-ci.com/Widen/gradle-versioning.svg?token=UKs7oqY6xCy4WamxJFLH&branch=master)](https://travis-ci.com/Widen/gradle-versioning)
 
-This plugin moves your project version out of the `build.gradle` file, and instead uses Git tags as the canonical source of truth for version numbers.
+## Overview
+This plugin moves your project version out of the `build.gradle` file, and instead uses Git tags as the canonical source of truth for version numbers. This makes it easier to maintain nice version numbers and eliminate "Bump version" commits.
+
+Version numbers that are generated are based off of the output of running `git describe --tags` in your repository with a few minor changes. Generally the version number syntax follows the below scheme:
+
+> (last tagged version) `+` (commits since last tag) `-` (current commit hash) (`-dirty` if dirty)
 
 ## Usage
 Add the private repository to the list of plugin repositories in `settings.gradle`:
@@ -33,6 +38,23 @@ plugins {
 
 Once the plugin is applied, your project will now infer the current project version automatically based on the most recent release in your Git repository. Be sure to remove any `version '<version>'` lines in your `build.gradle`, or the version number will get overwritten.
 
+### Configuration
+The default settings should be good enough for most projects, but there are a couple of settings you can set to change how versions are generated if you need them. For example, if your Git tags are prefixed with a `v`, you can have versions generated only from such tags and then have the prefix removed using the `tagPrefix` setting:
+
+```groovy
+versioning {
+    tagPrefix = 'v'
+}
+```
+
+Below are all the available settings and what they do.
+
+| Name        | Default value | Description |
+| ----------- | ------------- | ----------- |
+| tagPrefix   | `null`        | A prefix that tags must start with in order to be considered a version tag. The prefix is removed from the final version string. |
+| excludeTags | `null`        | A regular expression for tags that should be ignored. |
+| dirtyMark   | `true`        | Whether a `-dirty` suffix should be added to the version string if the Git working directory is dirty. |
+
 ### Automatic publishing
 If you are using Travis, the following configuration works quite nicely:
 

src/main/java/com/widen/versioning/Settings.java

@@ -0,0 +1,7 @@
+package com.widen.versioning;
+
+public class Settings {
+    public String tagPrefix;
+    public String excludeTags;
+    public boolean dirtyMark = true;
+}

src/main/java/com/widen/versioning/VersionGenerator.java

@@ -3,28 +3,55 @@
 import org.apache.commons.io.IOUtils;
 
 import java.nio.charset.Charset;
+import java.util.ArrayList;
 
 public class VersionGenerator {
-    public static String generateFromGit() {
+    public static String generateFromGit(Settings settings) {
+        ArrayList<String> args = new ArrayList<>();
+        args.add("git");
+        args.add("describe");
+        args.add("--tags");
+
+        if (settings.tagPrefix != null) {
+            args.add("--match");
+            args.add(settings.tagPrefix + '*');
+        }
+
+        if (settings.excludeTags != null) {
+            args.add("--exclude");
+            args.add(settings.excludeTags);
+        }
+
+        if (settings.dirtyMark) {
+            args.add("--dirty");
+        }
+
         try {
-            Process process = Runtime.getRuntime().exec("git describe --tags");
+            Process process = Runtime.getRuntime().exec(args.toArray(new String[0]));
             String output = IOUtils.toString(process.getInputStream(), Charset.forName("UTF-8"));
 
             process.waitFor();
             if (process.exitValue() != 0 || output.isEmpty()) {
-                throw new RuntimeException("Could not determine version from Git");
+                return null;
             }
 
-            return generateFromString(output.trim());
+            return generateFromString(output.trim(), settings);
         } catch (Exception e) {
             throw new RuntimeException(e);
         }
     }
 
-    public static String generateFromString(String describe) {
+    public static String generateFromString(String describe, Settings settings) {
         if (describe == null) {
-            return "";
+            return null;
         }
-        return describe.replaceFirst("-", "+");
+
+        String version = describe.replaceFirst("-", "+");
+
+        if (settings.tagPrefix != null && version.startsWith(settings.tagPrefix)) {
+            version = version.substring(settings.tagPrefix.length());
+        }
+
+        return version;
     }
 }

src/main/java/com/widen/versioning/VersioningPlugin.java

@@ -6,12 +6,21 @@
 
 public class VersioningPlugin implements Plugin<Project> {
     @Override
-    public void apply(Project project) {
-        project.setVersion(VersionGenerator.generateFromGit());
+    public void apply(final Project project) {
+        // Make settings available to build script.
+        final Settings settings = project.getExtensions().create("versioning", Settings.class);
 
         Task task = project.getTasks().create("printVersion");
         task.setGroup("Versioning");
         task.setDescription("Prints the project\'s configured version");
         task.doLast(t -> System.out.println(project.getVersion()));
+
+        // Defer setting the version until after the build script is evaluated.
+        project.afterEvaluate(p -> {
+            String version = VersionGenerator.generateFromGit(settings);
+            if (version != null) {
+                p.setVersion(version);
+            }
+        });
     }
 }

src/test/groovy/com/widen/versioning/VersionGeneratorTest.groovy

@@ -7,12 +7,13 @@ class VersionGeneratorTest extends Specification {
     @Unroll("git describe '#describe' should become '#version'")
     def "parse git describe to version"() {
         expect:
-        VersionGenerator.generateFromString(describe) == version
+        VersionGenerator.generateFromString(describe, new Settings(tagPrefix: prefix)) == version
 
         where:
-        describe           | version
-        null               | ""
-        ""                 | ""
-        "0.1.0-4-ge7426f0" | "0.1.0+4-ge7426f0"
+        prefix | describe           | version
+        null   | null               | null
+        null   | ""                 | ""
+        null   | "0.1.0-4-ge7426f0" | "0.1.0+4-ge7426f0"
+        "v"    | "v1.2.3"           | "1.2.3"
     }
 }