1. 简介
JGit 是一个轻量级、纯 Java 实现的 Git 版本控制系统库，包含仓库访问流程、网络协议和核心版本控制算法。
JGit 是 Java 社区广泛使用的功能完备的 Git 实现。该项目隶属于 Eclipse 基金会，官网地址为 JGit。
本指南将介绍如何使用 JGit 进行开发。
2. 快速上手
将 JGit 集成到项目中有多种方式，最简单的是通过 Maven。在 pom.xml 的 <dependencies> 标签中添加以下依赖：
<dependency>
<groupId>org.eclipse.jgit</groupId>
<artifactId>org.eclipse.jgit</artifactId>
<version>4.6.0.201612231935-r</version>
</dependency>
⚠️ 最新版本请查阅 Maven 中央仓库。添加后 Maven 会自动下载所需依赖。
如果使用 OSGi 环境，可通过 p2 仓库集成，详情参考 Eclipse JGit。
3. 创建仓库
JGit 提供两级 API：
- Porcelain API：面向用户的高级操作（类似 Git 命令行工具）
- Plumbing API：直接操作底层仓库对象
大多数操作从 Repository 类开始。创建新仓库：
Git git = Git.init().setDirectory("/path/to/repo").call();
这会在指定路径创建带工作目录的仓库。
克隆现有仓库：
Git git = Git.cloneRepository()
.setURI("https://github.com/eclipse/jgit.git")
.setDirectory("/path/to/repo")
.call();
上述代码将 JGit 仓库克隆到本地 /path/to/repo 目录。
4. Git 对象模型
Git 中所有对象通过 SHA-1 ID 标识，JGit 中用 AnyObjectId 和 ObjectId 表示。
Git 对象包含四种类型：
- blob：存储文件数据
- tree：目录结构，引用其他 tree 和 blob
- commit：指向单个 tree
- tag：标记特殊 commit（通常用于版本发布）
解析对象示例：
ObjectId head = repository.resolve("HEAD");
4.1 Ref
Ref 是持有单个对象 ID 的变量，可指向任何 Git 对象。获取 master 分支引用：
Ref HEAD = repository.getRef("refs/heads/master");
4.2 RevWalk
RevWalk 用于遍历提交图并按序生成提交：
RevWalk walk = new RevWalk(repository);
4.3 RevCommit
RevCommit 表示 Git 中的提交对象。使用 RevWalk 解析：
RevWalk walk = new RevWalk(repository);
RevCommit commit = walk.parseCommit(objectIdOfCommit);
4.4 RevTag
RevTag 表示 Git 中的标签对象。解析方式：
RevWalk walk = new RevWalk(repository);
RevTag tag = walk.parseTag(objectIdOfTag);
4.5 RevTree
RevTree 表示 Git 中的树对象。解析方式：
RevWalk walk = new RevWalk(repository);
RevTree tree = walk.parseTree(objectIdOfTree);
5. Porcelain API
JGit 在 org.eclipse.jgit.api 包中提供了模拟 Git 命令的高级 API。
5.1 AddCommand (git-add)
通过 addFilepattern() 添加文件到暂存区：
Git git = new Git(db);
AddCommand add = git.add();
add.addFilepattern("someDirectory").call();
5.2 CommitCommand (git-commit)
提交代码支持以下选项：
setAuthor()setCommitter()setAll()
示例：
Git git = new Git(db);
CommitCommand commit = git.commit();
commit.setMessage("initial commit").call();
5.3 TagCommand (git-tag)
标签操作支持：
setName()setMessage()setTagger()setObjectId()setForceUpdate()setSigned()
示例：
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)
遍历提交图：
add(AnyObjectId start)addRange(AnyObjectId since, AnyObjectId until)
获取提交日志：
Git git = new Git(db);
Iterable<RevCommit> log = git.log().call();
6. Ant 任务
JGit 在 org.eclipse.jgit.ant 包中提供了常用 Ant 任务。
配置任务：
<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>
支持 git-clone、git-init 和 git-checkout 任务。
6.1 git-clone
<git-clone uri="http://egit.eclipse.org/jgit.git" />
✅ 必需属性：
uri：克隆源地址
❌ 可选属性：
dest：目标路径（默认基于 URI 生成目录名）bare：是否创建裸仓库（默认 false）branch：初始检出分支（默认 HEAD）
6.2 git-init
<git-init />
❌ 可选属性：
dest：仓库初始化路径（默认当前目录）bare：是否创建裸仓库（默认 false）
6.3 git-checkout
<git-checkout src="path/to/repo" branch="origin/newbranch" />
✅ 必需属性：
src：仓库路径branch：检出分支名称
❌ 可选属性：
createbranch：分支不存在时是否创建（默认 false）force：是否强制覆盖现有分支（默认 false）
7. 总结
JGit 的高级 API 设计直观，熟悉 Git 命令的开发者能快速上手对应的类和方法。
✅ 完整代码示例可参考 JGit 代码片段库。
遇到问题可在此留言或咨询 JGit 社区。