[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