Ant tasks for Git using JGit
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).
The best way to contribute is via pull requests after running tests. Please also check 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.
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.
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="firstname.lastname@example.org"/>
<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="email@example.com"/>
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>
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.
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
<dependency org="org.eclipse.jgit" name="org.eclipse.jgit.ant" rev="188.8.131.52306101825-r" conf="YOUR_IVY_CONFIGURATION"/>
<dependency org="org.eclipse.jgit" name="org.eclipse.jgit" rev="184.108.40.206306101825-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.
ivysettings.xml file, you need a reference to two repositories:
- Maven Central for general dependencies
- Sonatype snapshot repositories for
<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"/>
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:
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-220.127.116.11306101825-r.jar"/> <pathelement location="path/to/org.eclipse.jgit-18.104.22.168306101825-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
antwscript at the root of this folder, you’ll need Apache Ant 1.8.0+.
JAVA_HOMEis to be set for the custom Doclet compilation so that the
tools.jarfile 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.
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.
Source Copyright 2013-2014 Rimero Solutions, Yves Zoundi and contributors.
Distributed under the Apache License version 2.0. See the file LICENSE at the root of the project.