章节 ▾ 第二版

A2.3 附录 B：在你的应用程序中嵌入 Git - JGit

JGit

如果你想从 Java 程序中使用 Git，有一个功能齐全的 Git 库叫做 JGit。JGit 是一个相对功能齐全的 Git 实现，完全用 Java 编写，并在 Java 社区中广泛使用。JGit 项目属于 Eclipse 伞下，其主页位于 https://www.eclipse.org/jgit/。

开始设置

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

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

当你阅读本文时，version 很可能已经更新；查看 https://mvnrepository.com/artifact/org.eclipse.jgit/org.eclipse.jgit 以获取更新的存储库信息。完成此步骤后，Maven 将自动获取并使用你需要的 JGit 库。

如果你宁愿自己管理二进制依赖项，则可以从 https://www.eclipse.org/jgit/download 获取预构建的 JGit 二进制文件。你可以通过运行这样的命令将它们构建到你的项目中

javac -cp .:org.eclipse.jgit-3.5.0.201409260305-r.jar App.java
java -cp .:org.eclipse.jgit-3.5.0.201409260305-r.jar App

底层命令

JGit 有两个基本的 API 级别：底层命令和高层命令。这些术语来自 Git 本身，JGit 大致分为相同的区域：高层命令 API 是友好的前端，用于常见的用户级别操作（普通用户使用 Git 命令行工具进行的操作），而底层命令 API 用于直接与低级存储库对象交互。

大多数 JGit 会话的起点是 Repository 类，你首先要做的是创建它的一个实例。对于基于文件系统的存储库（是的，JGit 允许其他存储模型），可以使用 FileRepositoryBuilder 来完成此操作

// Create a new repository
Repository newlyCreatedRepo = FileRepositoryBuilder.create(
    new File("/tmp/new_repo/.git"));
newlyCreatedRepo.create();

// Open an existing repository
Repository existingRepo = new FileRepositoryBuilder()
    .setGitDir(new File("my_repo/.git"))
    .build();

构建器具有流畅的 API，可以提供查找 Git 存储库所需的所有信息，无论你的程序是否确切知道其位置。它可以使用环境变量 (.readEnvironment())，从工作目录中的某个位置开始搜索 (.setWorkTree(…).findGitDir())，或者只是像上面那样打开一个已知的 .git 目录。

一旦你拥有了 Repository 实例，你就可以用它做各种各样的事情。这是一个快速示例

// Get a reference
Ref master = repo.getRef("master");

// Get the object the reference points to
ObjectId masterTip = master.getObjectId();

// Rev-parse
ObjectId obj = repo.resolve("HEAD^{tree}");

// Load raw object contents
ObjectLoader loader = repo.open(masterTip);
loader.copyTo(System.out);

// Create a branch
RefUpdate createBranch1 = repo.updateRef("refs/heads/branch1");
createBranch1.setNewObjectId(masterTip);
createBranch1.update();

// Delete a branch
RefUpdate deleteBranch1 = repo.updateRef("refs/heads/branch1");
deleteBranch1.setForceUpdate(true);
deleteBranch1.delete();

// Config
Config cfg = repo.getConfig();
String name = cfg.getString("user", null, "name");

这里有很多内容，让我们一次查看一个部分。

第一行获取指向 master 引用的指针。JGit 自动获取实际的 master 引用，它位于 refs/heads/master，并返回一个对象，允许您获取有关该引用的信息。您可以获取名称 (.getName())，以及直接引用的目标对象 (.getObjectId()) 或符号引用指向的引用 (.getTarget())。引用对象也用于表示标签引用和对象，因此您可以询问标签是否被“剥离”，这意味着它指向（可能很长的）一系列标签对象的最终目标。

第二行获取 master 引用的目标，该目标作为 ObjectId 实例返回。ObjectId 表示对象的 SHA-1 哈希，它可能存在于 Git 的对象数据库中，也可能不存在。第三行类似，但展示了 JGit 如何处理 rev-parse 语法（有关更多信息，请参见分支引用）；您可以传递 Git 能够理解的任何对象说明符，JGit 将返回该对象的有效 ObjectId，或者 null。

接下来的两行展示了如何加载对象的原始内容。在本例中，我们调用 ObjectLoader.copyTo() 将对象的内容直接流式传输到 stdout，但 ObjectLoader 还有一些方法可以读取对象的类型和大小，以及将其作为字节数组返回。对于大对象（其中 .isLarge() 返回 true），您可以调用 .openStream() 来获取一个类似 InputStream 的对象，该对象可以读取原始对象数据，而无需一次性将其全部拉入内存。

接下来的几行展示了创建新分支所需的操作。我们创建一个 RefUpdate 实例，配置一些参数，并调用 .update() 来触发更改。紧随其后的是删除同一分支的代码。请注意，需要 .setForceUpdate(true) 才能使其工作；否则 .delete() 调用将返回 REJECTED，并且不会发生任何事情。

最后一个示例展示了如何从 Git 配置文件中获取 user.name 值。此 Config 实例使用我们之前打开的存储库进行本地配置，但也会自动检测全局和系统配置文件，并从中读取值。

这只是完整底层 API 的一小部分示例；还有许多其他方法和类可用。此外，此处未展示 JGit 处理错误的方式，即通过使用异常。JGit API 有时会抛出标准 Java 异常（例如 IOException），但也有许多 JGit 特定的异常类型也已提供（例如 NoRemoteRepositoryException、CorruptObjectException 和 NoMergeBaseException）。

瓷器

底层 API 相当完整，但将它们串联起来以实现常见目标（如将文件添加到索引或创建新提交）可能很麻烦。JGit 提供了一组更高级别的 API 来帮助解决此问题，这些 API 的入口点是 Git 类

Repository repo;
// construct repo...
Git git = new Git(repo);

Git 类有一组很好的高级构建器风格方法，可用于构建一些相当复杂的行为。让我们看一个例子 — 做类似于 git ls-remote 的事情

CredentialsProvider cp = new UsernamePasswordCredentialsProvider("username", "p4ssw0rd");
Collection<Ref> remoteRefs = git.lsRemote()
    .setCredentialsProvider(cp)
    .setRemote("origin")
    .setTags(true)
    .setHeads(false)
    .call();
for (Ref ref : remoteRefs) {
    System.out.println(ref.getName() + " -> " + ref.getObjectId().name());
}

这是 Git 类中常见的模式；这些方法返回一个命令对象，该对象允许您链接方法调用来设置参数，这些参数在您调用 .call() 时执行。在本例中，我们要求 origin 远程仓库提供标签，但不提供 head。另请注意，使用了 CredentialsProvider 对象进行身份验证。

Git 类中还有许多其他命令可用，包括但不限于 add、blame、commit、clean、push、rebase、revert 和 reset。

进一步阅读

这只是 JGit 全部功能的一小部分示例。如果您有兴趣并想了解更多信息，请在此处查找信息和灵感

scroll-to-top