# Concepts

## API

### Repository

A Repository holds all objects and refs used for managing source code.

To build a repository, you invoke flavors of RepositoryBuilder.

    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 directory; 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 repository, 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 any valid Git object (blob, tree, commit, tag).

For example, to query for the reference 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);

TODO talk about filters

### 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 = walk.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);