To resolve an object from a repository, simply pass in the right revision string.

To resolve an object from a repository, simply pass in the right revision string.

−

<source lang="java">

+

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

−

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

+

−

</source>

+

=== Ref ===

=== Ref ===

Line 136:

Line 134:

For example, to query for the reference to head, you can simply call

For example, to query for the reference to head, you can simply call

−

<source lang="java">

+

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

−

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

+

−

</source>

+

=== RevWalk ===

=== RevWalk ===

Line 144:

Line 140:

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

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

−

<source lang="java">

+

RevWalk walk = new RevWalk(repository);

−

RevWalk walk = new RevWalk(repository);

+

−

</source>

+

TODO talk about filters

TODO talk about filters

Line 156:

Line 150:

To parse a commit, simply use a '''RevWalk''' instance:

To parse a commit, simply use a '''RevWalk''' instance:

−

<source lang="java">

+

RevWalk walk = new RevWalk(repository);

−

RevWalk walk = new RevWalk(repository);

+

RevCommit commit = walk.parseCommit(objectIdOfCommit);

−

RevCommit commit = walk.parseCommit(objectIdOfCommit);

+

−

</source>

+

=== RevTag ===

=== RevTag ===

Line 167:

Line 159:

To parse a tag, simply use a '''RevWalk''' instance:

To parse a tag, simply use a '''RevWalk''' instance:

−

<source lang="java">

+

RevWalk walk = new RevWalk(repository);

−

RevWalk walk = new RevWalk(repository);

+

RevTag tag = walk.parseTag(objectIdOfTag);

−

RevTag tag = walk.parseTag(objectIdOfTag);

+

−

</source>

+

=== RevTree ===

=== RevTree ===

Line 176:

Line 166:

A '''RevTree''' represents a tree in the Git object model.

A '''RevTree''' represents a tree in the Git object model.

−

To parse a commit, simply use a '''RevWalk''' instance:

+

To parse a tree, simply use a '''RevWalk''' instance:

−

<source lang="java">

+

RevWalk walk = new RevWalk(repository);

−

RevWalk walk = new RevWalk(repository);

+

RevTree tree = walk.parseTree(objectIdOfTree);

−

RevTree tree = walk.parseTree(objectIdOfTree);

+

−

</source>

+

= Reference =

= Reference =

Line 199:

Line 187:

Here's a quick example of how to add a set of files to the index using the porcelain API.

Here's a quick example of how to add a set of files to the index using the porcelain API.

−

<source lang="java">

+

Git git = new Git(db);

−

Git git = new Git(db);

+

AddCommand add = git.add();

−

AddCommand add = git.add();

+

add.addFilepattern("someDirectory").call();

−

add.addFilepattern("someDirectory").call();

+

−

</source>

+

=== CommitCommand (git-commit) ===

=== CommitCommand (git-commit) ===

Line 215:

Line 201:

Here's a quick example of how to commit using the porcelain API.

Here's a quick example of how to commit using the porcelain API.

−

<source lang="java">

+

Git git = new Git(db);

−

Git git = new Git(db);

+

CommitCommand commit = git.commit();

−

CommitCommand commit = git.commit();

+

commit.setMessage("initial commit").call();

−

commit.setMessage("initial commit").call();

+

−

</source>

+

=== TagCommand (git-tag) ===

=== TagCommand (git-tag) ===

Line 234:

Line 218:

Here's a quick example of how to tag a commit using the porcelain API.

Here's a quick example of how to tag a commit using the porcelain API.

−

<source lang="java">

+

Git git = new Git(db);

−

Git git = new Git(db);

+

RevCommit commit = git.commit().setMessage("initial commit").call();

−

RevCommit commit = git.commit().setMessage("initial commit").call();

+

RevTag tag = git.tag().setName("tag").call();

−

RevTag tag = git.tag().setName("tag").call();

+

−

</source>

+

=== LogCommand (git-log) ===

=== LogCommand (git-log) ===

Line 249:

Line 231:

Here's a quick example of how get some log messages.

Here's a quick example of how get some log messages.

−

<source lang="java">

+

Git git = new Git(db);

−

Git git = new Git(db);

+

Iterable<RevCommit> log = git.log().call();

−

LogCommand log = git.log().call();

+

−

</source>

+

=== MergeCommand (git-merge) ===

=== MergeCommand (git-merge) ===

TODO

TODO

+

+

== Ant Tasks ==

+

+

JGit has Ant tasks for some common tasks contained in the '''org.eclipse.jgit.ant''' bundle.

+

+

To use these tasks:

+

+

<taskdef resource="org/eclipse/jgit/ant/ant-tasks.properties">

+

<classpath>

+

<pathelement location="path/to/org.eclipse.jgit.ant-VERSION.jar"/>

+

<pathelement location="path/to/org.eclipse.jgit-VERSION.jar"/>

+

<pathelement location="path/to/jsch-0.1.44-1.jar"/>

+

</classpath>

+

</taskdef>

+

+

This would then provide git-clone, git-init and git-checkout tasks.

+

+

=== git-clone ===

+

+

<git-clone uri="http://egit.eclipse.org/jgit.git" />

+

+

The following attributes are required:

+

* uri: the uri to clone from

+

+

The following attributes are optional:

+

* dest: the destination to clone to (defaults to use a human readable directory name based on the last path component of the uri)

+

* bare: true/false/yes/no to indicate if the cloned repository should be bare or not (defaults to false)

+

* branch: the initial branch to check out when cloning the repository (defaults to HEAD)

+

+

=== git-init ===

+

+

<git-init />

+

+

The following attributes are optional:

+

* dest: the path where a git repository is initialized (defaults $GIT_DIR or the current directory)

+

* bare: true/false/yes/no to indicate if the repository should be bare or not (defaults to false)

+

+

=== git-checkout ===

+

+

<git-checkout src="path/to/repo" branch="origin/experimental" />

+

+

The following attributes are required:

+

* src: the path to the git repository

+

* branch: the initial branch to checkout

+

+

The following attributes are optional:

+

* createbranch: true/false/yes/no to indicate whether the branch should be created if it does not already exist (defaults to false)

+

* force: true/false/yes/no: if true/yes and the branch with the given name already exists, the start-point of an existing branch will be set to a new start-point; if false, the existing branch will not be changed (defaults to false)

Taking JGit for a Spin

Although you are probably interested in JGit because you want to integrate it into an existing application or create a tool, JGit is more than simply a Java library for working with git repository. So before diving into the different aspects of the library let's take JGit for a spin.

You are probably familiar with the git command line interface (CLI) that can be used from the shell or in scripts. JGit comes with its own small CLI, which, although not as feature-full as the git CLI, is a good way to showcase what JGIt can do. Furthermore, the programs serve as an excellent source of inspiration for how to accomplish different tasks.

Building the JGit CLI

Assuming that you have the EGit git repository cloned and ready, build the jgit binary by running the jgit maven build (see the Contributor Guide):

~/src/jgit$ mvn clean install

Find the jgit binary here (path relative to root of working tree of your clone of the jgit repository):

org.eclipse.jgit.pgm/target/jgit

Check your build by running the "version" command:

prompt$ ./jgit version
jgit version 0.10.0-SNAPSHOT

If you want to use jgit frequently you may consider to ease running it via a symbolic link (usually goes under /usr/local/bin)

sudo ln -s /path/to/jgit /usr/local/bin/jgit

Running the JGit CLI

Overview

When given the -h flag, commands provide a helpful message listing what flags they support.

The commands are modeled after their corresponding command in the git CLI.
We will not cover all the commands here, but simply give some examples.

jgit also provides a number of debug and test commands, to list all the available commands run

prompt$ ./jgit debug-show-commands

Inspecting the Repository

Before inspecting the most recent commits, you probably want to know which branches the repository contains and what branch is currently checked out. Using the branch commands -v flag, you get a small summary of branches, their revision, and the first line of the revision's commit message.

will show you all commits in the "master" branch, where the author name matches "Matthias" and the commit messages contains the word tycho. More search criteria to filter the commit log, such as committer name, can be given.

Graphical History View

Finally, to show some of the graphical capabilities of JGit, we will end this small tour by launching the graphical log tool.

prompt$ ./jgit glog

This should give you a window with the revision graph plotted to the left and three columns containing the first line of the message, the author name, and the commit date.

Concepts

API

Repository

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

git-clone

dest: the destination to clone to (defaults to use a human readable directory name based on the last path component of the uri)

bare: true/false/yes/no to indicate if the cloned repository should be bare or not (defaults to false)

branch: the initial branch to check out when cloning the repository (defaults to HEAD)

git-init

<git-init />

The following attributes are optional:

dest: the path where a git repository is initialized (defaults $GIT_DIR or the current directory)

bare: true/false/yes/no to indicate if the repository should be bare or not (defaults to false)

git-checkout

<git-checkout src="path/to/repo" branch="origin/experimental" />

The following attributes are required:

src: the path to the git repository

branch: the initial branch to checkout

The following attributes are optional:

createbranch: true/false/yes/no to indicate whether the branch should be created if it does not already exist (defaults to false)

force: true/false/yes/no: if true/yes and the branch with the given name already exists, the start-point of an existing branch will be set to a new start-point; if false, the existing branch will not be changed (defaults to false)

Snippet Collection

Advanced Topics

Reducing memory usage with RevWalk

The revision walk interface and the RevWalk and RevCommit
classes are designed to be light-weight. However, when used
with any repository of considerable size they may still
require a lot of memory. This section provides hints on what
you can do to reduce memory when walking the revision graph.

Restrict the walked revision graph

Try to walk only the amount of the graph you
actually need to walk. That is, if you are looking for the commits in
refs/heads/master not yet in refs/remotes/origin/master, make sure you
markStart() for refs/heads/master and markUninteresting()
refs/remotes/origin/master. The RevWalk traversal will only parse the
commits necessary for it to answer you, and will try to avoid looking
back further in history. That reduces the size of the internal object
map, and thus reduces overall memory usage.

Discard the body of a commit

There is a setRetainBody(false) method you can use to discard the body
of a commit if you don't need the author, committer or message
information during the traversal. Examples of when you don't need
this data is when you are only using the RevWalk to compute the merge
base between branches, or to perform a task you would have used `git
rev-list` with its default formatting for.

If you do need the body, consider extracting the data you need and
then calling dispose() on the RevCommit, assuming you only need the
data once and can then discard it. If you need to hang onto the data,
you may find that JGit's internal representation uses less overall
memory than if you held onto it yourself, especially if you want the
full message. This is because JGit uses a byte[] internally to store the
message in UTF-8. Java String storage would be bigger using UTF-16,
assuming the message is mostly US-ASCII data.

Subclassing RevWalk and RevCommit

If you need to attach additional data to a commit, consider
subclassing both RevWalk and RevCommit, and using the createCommit()
method in RevWalk to consruct an instance of your RevCommit subclass.
Put the additional data as fields in your RevCommit subclass, so that
you don't need to use an auxiliary HashMap to translate from RevCommit
or ObjectId to your additional data fields.

Cleaning up after a revision walk

A RevWalk cannot shrink its internal object map. If you have just
done a huge traversal of say all history of the repository, that will
load everything into the object map, and it cannot be released. If
you don't need this data in the near future, it may be a good idea to
throw away the RevWalk and allocate a new one for your next traversal.
That will let the GC reclaim everything and make it available for
another use. On the other hand, reusing an existing object map is
much faster than building a new one from scratch. So you need to
balance the reclaiming of memory against the user's desire to perform
fast updates of an existing repository view.