Home Tutorials Training Consulting Products Books Company Donate Contact us









NOW Hiring

Quick links

Share

This tutorial contains examples for the usage of the JGit API.

1. JGit

JGit is a pure Java implementation of the Git version control system. It powers many Git related Java projects like EGit and Gerrit. JGit is part of the Eclipse project.

2. Using JGit in your project

JGit is a Java framework and can be integrated into your project with the usual methods.

2.1. Adding JGit to your project with Maven

The latest release of JGit is available as Maven repository.

You can find the latest release via the following link: https://mvnrepository.com/artifact/org.eclipse.jgit/org.eclipse.jgit

To add JGit as a Maven dependency, add the following to your pom.xml.

<!-- https://mvnrepository.com/artifact/org.eclipse.jgit/org.eclipse.jgit -->
<dependency>
    <groupId>org.eclipse.jgit</groupId>
    <artifactId>org.eclipse.jgit</artifactId>
    <version>4.7.0.201704051617-r</version>
</dependency>

2.2. Adding JGit to your project with Gradle

dependencies {
    compile 'org.eclipse.jgit:org.eclipse.jgit:4.5.0.201609210915-r'
}

3. Using JGit to access Git repositories

JGit implements most of the commands that come with the Git CLI. Some of the actions of JGit can be executed on a remote repository but for most methods you have to have a local copy.

3.1. Cloning a Git repository with JGit

The Git class has a static method that allows you to clone a remote repository. JGits commands are lazily evaluated to allow for configuration via method chaining. The call of Class#call() starts the execution of the command.

Git.cloneRepository()
  .setURI("https://github.com/eclipse/jgit.git")
  .setDirectory(new File("/path/to/repo"))
  .call();

By default JGit only clones the default branch. It is also possible to tell JGit to clone a specific branch.

Git.cloneRepository()
  .setURI("https://github.com/eclipse/jgit.git")
  .setDirectory(new File("/path/to/repo"))
  .setBranchesToClone(Arrays.asList("refs/heads/specific-branch"))
  .setBranch("refs/heads/specific-branch")
  .call();

JGit can also be told to clone all branches.

Git git = Git.cloneRepository()
  .setURI("https://github.com/eclipse/jgit.git")
  .setDirectory("/path/to/repo")
  .setCloneAllBranches(true)
  .call();

3.2. Opening a local repository with JGit

If you want to directly create a repository object you can use the FileRepositoryBuilder.

FileRepositoryBuilder repositoryBuilder = new FileRepositoryBuilder();
Repository repository = repositoryBuilder.setGitDir(new File("/path/to/repo/.git"))
                .readEnvironment() // scan environment GIT_* variables
                .findGitDir() // scan up the file system tree
                .setMustExist(true)
                .build();

If you also need a Git object you can call a static method on it’s class.

Git.open(new File("/path/to/repo/.git"))
    .checkout();
Repository repository = git.getRepository();

3.3. Checking out a specific commit

The example shows how to check out a specific commit. This leaves you in a detatched HEAD state.

git.checkout()
    .setCreateBranch(true)
    .setName("new-branch")
    .call();

You can also check out a commit and create a new branch with this commit.

git.checkout()
    .setCreateBranch(true)
    .setName("new-branch")
    .setStartPoint("<id-to-commit>")
    .call();

3.4. Searching and accessing a file

This example assumes that your already have opened a repository.

            // find the HEAD
            ObjectId lastCommitId = repository.resolve(Constants.HEAD);

            // a RevWalk allows to walk over commits based on some filtering that is defined
            try (RevWalk revWalk = new RevWalk(repository)) {
                RevCommit commit = revWalk.parseCommit(lastCommitId);
                // and using commit's tree find the path
                RevTree tree = commit.getTree();
                System.out.println("Having tree: " + tree);

                // now try to find a specific file
                try (TreeWalk treeWalk = new TreeWalk(repository)) {
                    treeWalk.addTree(tree);
                    treeWalk.setRecursive(true);
                    treeWalk.setFilter(PathFilter.create("README.md"));
                    if (!treeWalk.next()) {
                        throw new IllegalStateException("Did not find expected file 'README.md'");
                    }

                    ObjectId objectId = treeWalk.getObjectId(0);
                    ObjectLoader loader = repository.open(objectId);

                    // and then one can the loader to read the file
                    loader.copyTo(System.out);
                }

                revWalk.dispose();
        }

4. JGit resources