[concept] JGit tutorial

[dorawyy]

References

• JGit Tutorial - Vogella
• JGit cookbook
  • Very good one, containing large numbers of available APIs, including high-level and low-level implementations
• How to Access a Git Repository with JGit

Add Maven Dependencies

• Maven JGit version list: here

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

API

Repository

A Repository holds all objects and refs used for managing source code. To build a repo, you invoke flavors of RepositoryBuiilder:

FileRepositoryBuilder builder = new FileRepositoryBuilder();
Repository repository = builder.setGitDir(new File("/my/git/directory"))
  .readEnvironment() // scan environment GIT_* variables
  .findGitDir() // scan up the file system tree
  .build();

Git Objects

All objects are represented by a SHA-1 id in the Git object model. In JGit, this is represented by the AnyObjectId and ObjectId classes.

There are four types of objects in the Git object model:

• blob: is used to store file data
• tree: can be thought of as a dir, it references other trees and blobs
• commit: a commit points to a single tree
• tag: marks a commit as special; generally used to mark specific releases To resolve an object from a repo, simply pass in the right revision string

  ObjectId head = repository.resolve("HEAD");

Ref

A Ref is a variable that holds a single object identifier. The object identifier can be valid Git object (blob, tree, commit, tag). For example, to query for the references to head, you can simply call

Ref HEAD = repository.getRef("refs/heads/master");

RevWalk

A RevWalk walks a commit graph and produces the matching commits in order

RevWalk walk = new RevWalk(repository);

RevCommit

A RevCommit represents a commit in the Git object model. To parse a commit, simply use a RevWalk instance:

RevWalk walk = new RevWalk(repository);
RevCommit commit = walk.parseCommit(ObjectIdOfCommit);

RevTag

A RevTag represents a tag in the Git object model. to parse a tag, simply use a RevWalk instance:

RevWalk walk = new RevWalk(repository);
RevTag tag = wak.parseTag(objectIdOfTag);

RevTree

A RevTree represents a tree in the Git object model. To parse a tree, simply use a RevWalk instance:

RevWalk walk = new RevWalk(repository);
RevTree tree = walk.parseTree(objectIdOfTree);

[dorawyy]

Example Snippets

Directly create a repo object

# with a Repo's local path
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();

Create a Git object based on Repository

# with a Repo's local path
Git.open(new File("/path/to/repo/.git"))
    .checkout();
Repository repository = git.getRepository();

Check out a specific commit

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

# with a Git object
git.checkout()
    .setCreateBranch(true)
    .setName("new-branch")
    .call();

[check out a commit and create a new branch with this commit]()

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

Searching and accessing a file

# with 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();
        }

[dorawyy]

Summary of info that we need:

• List of branches
• All merge commit, including
  • commit id
  • commit message
  • commit parents
  • commit branches
  • changes of the commit
  • changes of its parents

Questions to figure out:

• How to read information of a commit
• How to list all merge commits