An Introduction to the JGit Sources

JGit is a pure Java library implementing the Git version control system. It is an Eclipse project and started out as the Git library for EGit, which provides a Git integration into Eclipse. Meanwhile JGit has further adopters like in Gerrit, GitBlit, GitClient Plugin for Jenkins (work in progress), …

Its permissive license, few dependencies and low requirements make it easy to embed JGit in any Java application. The core library requires Java 1.5, JSch to make SSH connections and JavaEWAH for fast bit array manipulations. The latest release is 3.1 and was released last June. The New & Noteworthy gives more details of the new version.

Where to get it

The download page lists different ways to obtain and integrate the library. Probably the most common way is to obtain JGit from the Maven repository. If you prefer OSGi bundles, then there is a p2 repository for you. And finally you can download the JGit core library, grab a copy of JSch and JavaEWAH and manually add the jars to your build path.

While the binaries are just fine to develop your software against, you may be interested in the sources as well. Be it because you found a bug to fix or a feature to implement or just out of curiosity…

Working from Source

package-explorer-jgitWhile JGit can be consumed in various forms, it is developed as a set of OSGi bundles. This requires that PDE is installed in the development IDE.

The source code resides — guess what — in a Git repository. Thus, the first step is obvious: clone the repository from

The code of the core library resides in a single project: org.eclipse.jgit. If you use Java 7, then org.eclipse.jgit.java7 may also be of interest. This fragment project integrates the Java 7 file system API so that JGit can benefit from the improved portability of file operations (e.g. symlinks).

To provide the dependencies, set the current target platform to the target defintion that is contained in the project (it hides in the org.eclipse.jgit.packaging folder). In summary, for the core library you would want to import these projects:

  • org.eclipse.jgit — the core library itself
  • org.eclipse.jgit.java7 — support for Java 7 file system
  • — contains the target platform definition

If you see error markers complaining about a missing API baseline, tell PDE to ignore that for now (Window > Preferences > Plug-in Development > API Baselines).

Running the Tests

Now that the code compiles, let’s run the tests to validate the setup. Therefore, three projects are of interest. org.eclipse.jgit.junit provides utilities to set up and tear down test scenarios. org.eclipse.jgit.test and org.eclipse.jgit.java7.test hold the tests for the respective code projects. Unless you don’t have Java 7 installed, import all three of them.

launch-config-jgitWith the JGit sources come predefined launch configurations to run all tests. Select the ‘All Tests’ configuration that matches your JRE version and run it. The ‘All-External-Tests’ configurations run all regular tests plus currently one further test that interacts with native Git. Therefore they require native Git to be installed and on your executable search path.

If you see testMaliciousPathEmpty fail, you are likely running on Windows and hit by bug 396662.

The Core Library Structure

Git can be divided into two layers, the porcelain and the plumbing layer. The plumbing layer offers commands to do the low-level work. On top of that build the porcelain commands with which end users usually interact such as checkout, branch, commit, etc. Similarly JGit also has two layers. The command API closely models the Git command line. For each Git verb (commit, branch, checkout, etc.) there is a corresponding JGit command in the org.eclipse.jgit.api package.

The use cases that brought you to JGit make it likely that you will also come in touch with the plumbing layer. For example, the RevWalk lets you itrate over commits and represents them in a RevCommit which holds the meta data of a commit. A TreeWalk can then be used to list files within a commit and finally an ObjectLoader helps you to read a specific revision.

What else is there

While the core library is what most users seek, JGit has more to offer. The following is a list of add-ons to the core library:

  • org.eclipse.jgit.pgm is a self-contained command line executable with most of the commands that native git offers.
  • There are a few helper classes for AWT and Swing in the org.eclipse.jgit.ui jar to help with user/password authentication and rendering commit graphs.
  • A few Ant tasks (add, checkout, clone, and init) are also available through the org.eclipse.jgit.ant jar.
  • Common archive formats can be found in org.eclipse.jgit.archive. They can be registered with the ArchiveCommand to archive the contents of a certain commit in different formats.
  • Last but not least, org.eclipse.jgit.http.server provides a servlet that handles repository access over HTTP.

Now that you are set up you can start exploring the JGit APIs. The documentation is fairly basic, but there is a large number of tests. They are a good source if you want to learn how to use a certain JGit API. And then there is Stackoverflow, the JGit Form and a helpful community.

Reference: An Introduction to the JGit Sources from our JCG partner Rudiger Herrmann at the Code Affine blog.
Related Whitepaper:

Software Architecture

This guide will introduce you to the world of Software Architecture!

This 162 page guide will cover topics within the field of software architecture including: software architecture as a solution balancing the concerns of different stakeholders, quality assurance, methods to describe and evaluate architectures, the influence of architecture on reuse, and the life cycle of a system and its architecture. This guide concludes with a comparison between the professions of software architect and software engineer.

Get it Now!  

Leave a Reply

+ one = 5

Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

15,153 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books