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
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. 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 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.java7 — support for Java 7 file system
- 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, 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.
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 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.
Hi, I am trying to use Java list all the files that are present in a git repository by the number of commits. For this, I am using the JGit library. String filename = “/a/b/c.java”; String localPath = localPath; Repository localRepo = new FileRepository(localPath + “/.git”); Git git = new Git(localRepo); ObjectId head = localRepo.resolve(Constants.HEAD); Iterable logs = git.log().add(head).addPath(filename).call(); for (RevCommit revCommit : logs) { count++; } However, I am getting count as 0 always. When I use a file that is existing in the repo home directory I am getting the correct answer: String filename = “d.java”; String localPath… Read more »
This question was already raised (and replied to) on [Stackoverflow](http://stackoverflow.com/questions/23973284/using-jgit-to-count-the-number-of-commits-on-a-file). I don’t think that cross-posting will help getting an answer.