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 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
https://git.eclipse.org/r/p/jgit/jgit.git
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 org.eclipse.jgit.target 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.target — 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.
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 metadata 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.
- Extras for Eclipse: Neon Update - 6. July 2016
- What’s the Difference? Creating Diffs with JGit - 16. June 2016
- Terminate and Relaunch in Eclipse - 19. April 2016
[…] An Introduction to the JGit Sources […]
[…] An Introduction to the JGit Sources […]
It seems the “org.eclipse.jgit.target” project is no more.
The article reads: …
org.eclipse.jgit.target
hides in theorg.eclipse.jgit.packaging
folder …And there it is: https://github.com/eclipse/jgit/tree/master/org.eclipse.jgit.packaging
You are right. Sorry for my inattentiveness.
Also, the link to JGit Forum is dead.
I can’t see a problem with the link to the JGit forum either. It points to the JGIt’s support page and from there the first link opens the form page.
Strange. When I follow the link http://www.eclipse.org/jgit/support/, I get an empty page with “Can’t open file” words, and its HTML is broken.
Strange indeed. The direct link to the JGit/EGit forum is http://www.eclipse.org/forums/index.php?t=thread&frm_id=48
If you would like to file a bug to make the JGit maintainer aware that their web page can’t be seen from everywhere, follow this link: https://bugs.eclipse.org/bugs/enter_bug.cgi?product=JGit&rep_platform=All&op_sys=All
Thank you. Now the link seems to be working, so it must have been a temporary perturbation. Sorry for bothering you :)