Ant tasks for Git using JGit

Summary

This is a set of basic Apache Ant tasks for Git to automate release processes, using the Eclipse JGit API. The goal is to leverage release management processes for Apache Ant based projects that use Git for revision control. This set of Ant tasks is currently used by the Ant Command Line Wrapper project and by the ant-git-tasks project itself!

Below is one possible workflow:

Create a branch for a fix, feature or major change.
Merge the branch after some testing.
Update the documentation/changelog and/or other notes.
Prepare a release settings with ideally semantic versioning by updating a release properties file.
Commit the changes after updating the application version.
Tag the release and push the changes to a Git repository.
Push the code to a repository (Maven/Ivy).

Apache Maven/Apache Ivy repository hosting is provided via Sonatype OSS repositories.

If you’d like to contribute, please also read the Developer Notes Wiki page.

Tasks description and documentation

Apache Ant tasks documentation.

The available ant tasks documentation is available for online browsing via the project wiki pages.
You can also generate the Ant tasks documentation locally by running the javadoc target (ant javadoc). This generates both the API javadocs and the Ant tasks documentation (generated via a custom Doclet).

The docs are more up to date via build vs. looking at the wiki.

Code samples

The available Apache AntUnit tests give a good overview of the intended usage. The ant-git-tasks project is tested with Apache Ant itself, to have a feel of what’s working and how usable the tasks are.

General information

Overview

The expectation is that you create a git tasks container where you nest commands as needed. The initial step would be to setup the Git user information and credentials prior to running git commands.

<git:settings refId="gitSettingsReference"
              username="me" password="pwd"
              name="me" email="email@email.com"/>

<git:git directory="." settingsRef="gitSettingsReference">
 <git:clone uri="someuri"/>
</git:git>

User identify and credentials

The Git settings tasks allows specifying reusable credentials and identity settings. You typically first setup settings prior to running tasks unless you’re not doing any commits’. For now if you attempt a commit without settings, a null pointer exception is thrown, TBD fix it.

<git:settings refId="git.testing"
 username="xxxtesting"
 password="xxxtesting"
 name="xxxtesting"
 email="xxxtesting@gmail.com"/>

Usage

Once the settings are initialize, you just reference them in your root git tasks container. The git user information is require to commit to a repository and sometimes to push to remote repositories.

<git:git directory="repositoryCloneFolder" verbose="true" settingsRef="git.testing">
 <git:clone uri="https://github.com/rimerosolutions/playground-repo.git"/>
 <git:checkout branchName="dummyBranch" createBranch="true"/>
</git:git>

Integration

Git namespace

You’ll need to add a reference to the git namespace to handle git related tasks.

<project name="myproject"
        xmlns:git="antlib:com.rimerosolutions.ant.git"
 // other build.xml elements
</project>

As noticed in the above lines, ant-git-tasks use Antlib to define tasks.

Inside the target(s) where you intend to call git, you’ll need to setup the classpath and initialize the custom task.

See the section below for dependency management strategies and classpath handling.

Dependency Management

You can either use Apache Ivy as dependency manager, or you can put manually files where you want.

Apache Ivy (preferred)

You’ll need the following dependencies in your ivy.xml file.

<dependency org="org.eclipse.jgit" 
            name="org.eclipse.jgit.ant" 
            rev="3.0.0.201306101825-r" conf="YOUR_IVY_CONFIGURATION"/>

<dependency org="org.eclipse.jgit" 
            name="org.eclipse.jgit" 
            rev="3.0.0.201306101825-r" conf="YOUR_IVY_CONFIGURATION"/>

<dependency org="com.jcraft" 
            name="jsch" 
            rev="0.1.50" conf="YOUR_IVY_CONFIGURATION"/>

<dependency org="com.rimerosolutions.ant" 
            name="ant-git-tasks"
            rev="0.0.1-SNAPSHOT" 
            changing="true" conf="YOUR_IVY_CONFIGURATION"/>

The versions mentionned above could be obsolete, please use the information from a site such as mvnrepository.

In your ivysettings.xml file, you need a reference to two repositories:

Maven Central for general dependencies
Sonatype snapshot repositories for ant-git-tasks

<url name="sonatype-snapshots" m2compatible="true">
 <artifact pattern="https://oss.sonatype.org/content/repositories/snapshots/[organisation]/[module]/[revision]/[artifact]-[revision](-[classifier]).[ext]"/>
</url>
<ibiblio name="central" m2compatible="true"/>

In your build.xml, initialize the task definition and its classpath.

<ivy:cachepath pathid="ant.git.tasks.classpath" conf="YOUR_IVY_CONFIGURATION"/>

<taskdef uri="antlib:com.rimerosolutions.ant.git"
         resource="com/rimerosolutions/ant/git/jgit-ant-lib.xml">
  <classpath>
    <path refid="ant.git.tasks.classpath"/>
  </classpath>
</taskdef>

Manual download (‘quicker’, but not recommended)

You can grab the files below from the Maven central and Sonatype OSS repositories:

In your build.xml, initialize the task definition and its classpath.

<taskdef uri="antlib:com.rimerosolutions.ant.git"
         resource="com/rimerosolutions/ant/git/jgit-ant-lib.xml">
 <classpath>
  <pathelement location="path/to/org.eclipse.jgit.ant-3.0.0.201306101825-r.jar"/>
  <pathelement location="path/to/org.eclipse.jgit-3.0.0.201306101825-r.jar"/>
  <pathelement location="path/to/jsch-0.1.50.jar"/>
  <pathelement location="path/to/ant-git-tasks-0.0.1.jar"/>
 </classpath>
</taskdef>

Building from source

You need JDK7 to build the code from source. While it may also work for JDK8, it hasn’t been tested.
If you don’t want to use the ant wrapper antw script at the root of this folder, you’ll need Apache Ant 1.8.0+.
JAVA_HOME is to be set for the custom Doclet compilation so that the tools.jar file can be found.

Building with Apache Ant 1.7.1 leads to some intermittent errors when deleting temporary test folders. It looks like some kind of race condition is happening.

To list available Apache Ant targets, please run ./antw -p for Unix/Linux or antw -p for Windows.

If you use an IDE, take a look at Apache Ivy IDE Integration section on the Apache Ivy website.

Maven integration

The pom.xml file at the root of this project is only meant to illustrate Maven integration:

Apache AntUnit integration tests are run as part of the test phase.
A simple Apache Ant Git task is executed to showcase integration.

Notes about Apache Ant versions:

Apache Ant 1.8.2 doesn’t seem to create any weird issues (NoSuchMethodError, ClassNotFoundException, etc.).
Apache Ant 1.7.x leads to unpredictable builds as well as possible incompatibilities, version conflicts.

License

Distributed under the Apache License version 2.0. See the file LICENSE at the root of the project.

thelegendofbrian / ant-git-tasks