A Guide to JGit – JGit指南

最后修改: 2017年 1月 13日

中文/混合/英文(键盘快捷键：t)

1. Introduction

1.介绍

JGit is a lightweight, pure Java library implementation of the Git version control system – including repository access routines, network protocols, and core version control algorithms.

JGit是Git版本控制系统的一个轻量级的纯Java库实现–包括存储库访问例程、网络协议和核心版本控制算法。

JGit is a relatively full-featured implementation of Git written in Java and is widely used in the Java community. The JGit project is under the Eclipse umbrella, and its home can be found at JGit.

JGit是一个用Java编写的功能相对完整的Git实现，在Java社区被广泛使用。JGit项目隶属于Eclipse，其主页可在JGit找到。

In this tutorial, we’ll explain how to work with it.

在本教程中，我们将解释如何使用它。

2. Getting Started

2.开始

There are a number of ways to connect your project with JGit and start writing code. Probably the easiest way is to use Maven – the integration is accomplished by adding the following snippet to the <dependencies> tag in our pom.xml file:

有很多方法可以将你的项目与JGit连接起来并开始编写代码。最简单的方法可能是使用Maven–通过在我们的<dependencies>文件中的 pom.xml标签中添加以下片段来实现集成。

<dependency>
    <groupId>org.eclipse.jgit</groupId>
    <artifactId>org.eclipse.jgit</artifactId>
    <version>4.6.0.201612231935-r</version>
</dependency>

Please visit the Maven Central repository for the newest version of JGit. Once this step is done, Maven will automatically acquire and use the JGit libraries that we’ll need.

请访问Maven Central 仓库，获取最新的JGit版本。完成这一步骤后，Maven会自动获取并使用我们需要的JGit库。

If you prefer OSGi bundles, there is also a p2 repository. Please visit Eclipse JGit to get the necessary information how to integrate this library.

如果你喜欢OSGi捆绑，也有一个p2仓库。请访问Eclipse JGit以获得如何集成该库的必要信息。

3. Creating a Repository

3.创建一个存储库

JGit has two basic levels of API: plumbing and porcelain. The terminology for these comes from Git itself. JGit is divided into the same areas:

JGit有两个基本级别的API。plumbing和porcelain。这些术语来自于Git本身。JGit也被分为同样的区域。

  • porcelain APIs – front-end for common user-level actions (similar to Git command-line tool)
  • plumbing APIs – direct interacting with low-level repository objects

The starting point for most JGit sessions is in the Repository class. The first thing we are going to do is the creation of a new Repository instance.

大多数JGit会话的起点是在Repository类。我们要做的第一件事是创建一个新的Repository实例。

The init command will let us create an empty repository:

init命令将让我们创建一个空的版本库。

Git git = Git.init().setDirectory("/path/to/repo").call();

This will create a repository with a working directory at the location given to setDirectory().

这将在setDirectory()中给出的位置创建一个具有工作目录的版本库。

An existing repository can be cloned with the cloneRepository command:

一个现有的版本库可以用cloneRepository命令来克隆。

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

The code above will clone the JGit repository into the local directory named path/to/repo.

上面的代码将把JGit仓库克隆到名为path/to/repo的本地目录。

4. Git Objects

4.Git对象

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

在Git对象模型中，所有对象都由一个SHA-1的id表示。在JGit中，它由AnyObjectId和ObjectId类表示。

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

在Git对象模型中，有四种类型的对象。

  • blob – used for storing file data
  • tree – a directory; it references other trees and blobs
  • commit – points to a single tree
  • tag – marks a commit as special; generally used for marking specific releases

To resolve an object from a repository, simply pass the right revision as in the following function:

要从存储库中解析一个对象，只需像下面的函数那样传递正确的修订版。

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

4.1. Ref

4.1.参考资料

The Ref is a variable that holds a single object identifier. The object identifier can be any valid Git object (blob, tree, commit, tag).

Ref 是一个持有单个对象标识符的变量。对象标识符可以是任何有效的Git对象（blob, tree, commit, tag）。

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

例如，要查询对head的引用，你可以简单地调用。

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

4.2. RevWalk

4.2.RevWalk

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

RevWalk 读取提交图，并按顺序生成匹配的提交。

RevWalk walk = new RevWalk(repository);

4.3. RevCommit

4.3.RevCommit

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

RevCommit 在 Git 对象模型中代表一个提交。要解析一个提交，请使用RevWalk实例。

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

4.4. RevTag

4.4.RevTag

The RevTag represents a tag in the Git object model. You can use a RevWalk instance to parse a tag:

RevTag代表Git对象模型中的一个标签。你可以使用一个RevWalk实例来解析一个标签。

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

4.5. RevTree

4.5.RevTree

The RevTree represents a tree in the Git object model. A RevWalk instance is also used to parse a tree:

RevTree代表Git对象模型中的一棵树。一个RevWalk实例也被用来解析一个树。

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

5. Porcelain API

5.瓷器API

While JGit contains a lot of low-level code to work with Git repositories, it also contains a higher level API that mimics some of the Git porcelain commands in the org.eclipse.jgit.api package.

虽然JGit包含了很多与Git仓库合作的底层代码，但它也包含了一个更高层次的API，在org.eclipse.jgit.api包中模拟了一些Gitporcelain命令。

5.1. AddCommand (git-add)

5.1.AddCommand（git-add）

The AddCommand allows you to add files to the index via:

AddCommand允许你通过添加文件到索引。

  • addFilepattern()

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

这里有一个快速的例子，说明如何使用porcelain API向索引添加一组文件。

Git git = new Git(db);
AddCommand add = git.add();
add.addFilepattern("someDirectory").call();

5.2. CommitCommand (git-commit)

5.2.CommitCommand（git-commit）

The CommitCommand allows you to perform commits and has following options available:

CommitCommand允许你执行提交，有以下选项。

  • setAuthor()
  • setCommitter()
  • setAll()

Here’s a quick example of how to commit using the porcelain API:

这里有一个如何使用porcelain API提交的快速例子。

Git git = new Git(db);
CommitCommand commit = git.commit();
commit.setMessage("initial commit").call();

5.3. TagCommand (git-tag)

5.3.TagCommand（git-tag）

The TagCommand supports a variety of tagging options:

TagCommand支持多种标签选项。

  • setName()
  • setMessage()
  • setTagger()
  • setObjectId()
  • setForceUpdate()
  • setSigned()

Here’s a quick example of tagging a commit using the porcelain API:

下面是一个使用porcelain API标记提交的快速例子。

Git git = new Git(db);
RevCommit commit = git.commit().setMessage("initial commit").call();
RevTag tag = git.tag().setName("tag").call();

5.4. LogCommand (git-log)

5.4.LogCommand（git-log）

The LogCommand allows you to easily walk a commit graph.

LogCommand可以让你轻松地浏览一个提交图。

  • add(AnyObjectId start)
  • addRange(AnyObjectId since, AnyObjectId until)

Here’s a quick example of how to get some log messages:

下面是一个快速的例子，说明如何获得一些日志信息。

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

6. Ant Tasks

6.蚂蚁的任务

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

JGit也有一些常见的Ant任务，包含在org.eclipse.jgit.ant捆绑包中。

To use those 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 provide the git-clone, git-init and git-checkout tasks.

这将提供git-clone、git-init和git-checkout任务。

6.1. git-clone

6.1.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)

6.2. git-init

6.2.git-init

<git-init />

No attributes are required to run the git-init task.

运行git-init任务不需要任何属性。

The following attributes are optional:

以下属性是可选的。

  • dest: the path where a git repository is initialized (defaults to $GIT_DIR or the current directory)
  • bare: true/false/yes/no to indicate if the repository should be bare or not (defaults to false)

6.3. git-checkout

6.3.git-checkout

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

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)

7. Conclusion

7.结论

The high-level JGit API isn’t hard to understand. If you know what git command to use, you can easily guess which classes and methods to use in JGit.

高级别的JGit API并不难理解。如果你知道使用什么git命令，你可以很容易地猜到在JGit中使用哪些类和方法。

There is a collection of ready-to-run JGit code snippets available here.

有一个可随时运行的JGit代码片断集合，可在这里获得。

If you still have difficulties or questions, please leave a comment here or ask the JGit community for assistance.

如果您仍有困难或问题，请在此留言或向JGit社区寻求帮助。