An Introduction to the JGit Sources

Home  >>  Eclipse  >>  An Introduction to the JGit Sources

An Introduction to the JGit Sources

On October 28, 2013, Posted by , In Eclipse, By ,, , With 2 Comments

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 the Eclipse IDE. 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.7, JSch to make SSH connections, JavaEWAH for fast bit array manipulations and SLF4J.

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, JavaEWAH, and SLF4J 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

While 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.

To provide the dependencies, set the current target platform to the target definition 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
  • — 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, two projects are of interest. org.eclipse.jgit.junit provides utilities to set up and tear down test scenarios and org.eclipse.jgit.test holds the actual tests. Import both of them.

With 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 iterate 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 Forum and a helpful community.

Follow me

Rüdiger Herrmann

Routined programmer, team lead, presenter, blog writer, and convinced open source contributor with two decades experience in the field.

Strong focus on quality backed up by agile methods like test driven development, modularization, pair programming, clean code, continuous integration.

Specialized in Java with JEE, REST, OSGi, RCP, RAP and building developer tools based on the Eclipse IDE (or any other platform if an opportunity arises).
Follow me

Latest posts by Rüdiger Herrmann (see all)

2 Comments so far:

  1. […] An Introduction to the JGit Sources […]

Leave a Reply

Your email address will not be published. Required fields are marked *