-
A1. 附录 A: Git 在其他环境
- A1.1 图形界面
- A1.2 Visual Studio 中的 Git
- A1.3 Visual Studio Code 中的 Git
- A1.4 IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine 中的 Git
- A1.5 Sublime Text 中的 Git
- A1.6 Bash 中的 Git
- A1.7 Zsh 中的 Git
- A1.8 PowerShell 中的 Git
- A1.9 小结
-
A2. 附录 B: 在应用程序中嵌入 Git
-
A3. 附录 C: Git 命令
A2.2 附录B:在应用程序中嵌入Git - Libgit2
Libgit2
另一个可供选择的方案是使用 Libgit2。Libgit2 是 Git 的一个无依赖实现,其重点在于提供一个友好的 API 供其他程序使用。你可以在 https://libgit2.org 找到它。
首先,我们来看看 C API 是怎样的。以下是快速概览
// Open a repository
git_repository *repo;
int error = git_repository_open(&repo, "/path/to/repository");
// Dereference HEAD to a commit
git_object *head_commit;
error = git_revparse_single(&head_commit, repo, "HEAD^{commit}");
git_commit *commit = (git_commit*)head_commit;
// Print some of the commit's properties
printf("%s", git_commit_message(commit));
const git_signature *author = git_commit_author(commit);
printf("%s <%s>\n", author->name, author->email);
const git_oid *tree_id = git_commit_tree_id(commit);
// Cleanup
git_commit_free(commit);
git_repository_free(repo);
前几行代码打开一个 Git 仓库。git_repository
类型代表一个带有内存缓存的仓库句柄。这是最简单的方法,适用于你知道仓库工作目录或 .git
文件夹的确切路径的情况。此外还有 git_repository_open_ext
,它包含搜索选项;git_clone
及其相关函数用于创建远程仓库的本地克隆;以及 git_repository_init
用于创建全新的仓库。
第二段代码使用 rev-parse 语法(更多信息请参阅分支引用),以获取 HEAD 最终指向的提交。返回的类型是一个 git_object
指针,它代表了 Git 仓库对象数据库中存在的事物。git_object
实际上是几种不同类型对象的“父”类型;每个“子”类型的内存布局与 git_object
相同,因此你可以安全地转换为正确的类型。在这种情况下,git_object_type(commit)
将返回 GIT_OBJ_COMMIT
,因此安全地转换为 git_commit
指针是可行的。
下一段代码展示了如何访问提交的属性。这里最后一行使用了 git_oid
类型;这是 Libgit2 对 SHA-1 哈希值的表示。
从这个示例中,我们可以看到一些模式开始浮现
-
如果你声明一个指针并将其引用传递给 Libgit2 调用,该调用可能会返回一个整数错误代码。值
0
表示成功;任何小于 0 的值都是错误。 -
如果 Libgit2 为你填充了一个指针,你有责任释放它。
-
如果 Libgit2 从调用中返回一个
const
指针,你不需要释放它,但当其所属的对象被释放时,它将变得无效。 -
编写 C 代码有点痛苦。
最后一点意味着你在使用 Libgit2 时不太可能编写 C 代码。幸运的是,有许多针对特定语言的绑定可用,这使得你可以相当容易地在你的特定语言和环境中处理 Git 仓库。让我们看看上面示例使用 Libgit2 的 Ruby 绑定(名为 Rugged)的写法,它可以在 https://github.com/libgit2/rugged 找到。
repo = Rugged::Repository.new('path/to/repository')
commit = repo.head.target
puts commit.message
puts "#{commit.author[:name]} <#{commit.author[:email]}>"
tree = commit.tree
如你所见,代码简洁了许多。首先,Rugged 使用异常;它可以抛出像 ConfigError
或 ObjectError
这样的异常来指示错误情况。其次,由于 Ruby 进行了垃圾回收,所以不需要显式释放资源。让我们来看一个稍微复杂一点的例子:从头开始创建提交
blob_id = repo.write("Blob contents", :blob) # (1)
index = repo.index
index.read_tree(repo.head.target.tree)
index.add(:path => 'newfile.txt', :oid => blob_id) # (2)
sig = {
:email => "bob@example.com",
:name => "Bob User",
:time => Time.now,
}
commit_id = Rugged::Commit.create(repo,
:tree => index.write_tree(repo), # (3)
:author => sig,
:committer => sig, # (4)
:message => "Add newfile.txt", # (5)
:parents => repo.empty? ? [] : [ repo.head.target ].compact, # (6)
:update_ref => 'HEAD', # (7)
)
commit = repo.lookup(commit_id) # (8)
-
创建一个新的 blob 对象,其中包含新文件的内容。
-
使用 HEAD 提交的树填充索引,并将新文件添加到路径
newfile.txt
。 -
这会在 ODB 中创建一个新的树对象,并将其用于新的提交。
-
我们为作者和提交者字段使用相同的签名。
-
提交信息。
-
创建提交时,你必须指定新提交的父级。这里使用 HEAD 的尖端作为唯一的父级。
-
Rugged(和 Libgit2)在进行提交时可以选择性地更新引用。
-
返回值是新提交对象的 SHA-1 哈希值,你可以使用它来获取一个
Commit
对象。
Ruby 代码既漂亮又简洁,而且由于 Libgit2 承担了繁重的工作,这段代码运行速度也很快。如果你不是 Ruby 开发者,我们在其他绑定中会介绍一些其他绑定。
高级功能
Libgit2 具有一些超出核心 Git 范围的能力。一个例子是可插拔性:Libgit2 允许你为几种类型的操作提供自定义“后端”,这样你就可以用与标准 Git 不同的方式存储数据。Libgit2 允许为配置、引用存储和对象数据库等提供自定义后端。
我们来看看这是如何工作的。以下代码摘自 Libgit2 团队提供的一组后端示例(可在 https://github.com/libgit2/libgit2-backends 找到)。以下是为对象数据库设置自定义后端的方法
git_odb *odb;
int error = git_odb_new(&odb); // (1)
git_odb_backend *my_backend;
error = git_odb_backend_mine(&my_backend, /*…*/); // (2)
error = git_odb_add_backend(odb, my_backend, 1); // (3)
git_repository *repo;
error = git_repository_open(&repo, "some-path");
error = git_repository_set_odb(repo, odb); // (4)
请注意,错误已被捕获,但未处理。我们希望你的代码比我们的更好。
-
初始化一个空的(对象数据库)ODB“前端”,它将作为执行实际工作的“后端”的容器。
-
初始化一个自定义 ODB 后端。
-
将后端添加到前端。
-
打开一个仓库,并将其设置为使用我们的 ODB 来查找对象。
但这个 git_odb_backend_mine
是什么呢?嗯,那是你自己的 ODB 实现的构造函数,你可以在其中做任何你想做的事情,只要你正确地填充了 git_odb_backend
结构体。它可能看起来像这样
typedef struct {
git_odb_backend parent;
// Some other stuff
void *custom_context;
} my_backend_struct;
int git_odb_backend_mine(git_odb_backend **backend_out, /*…*/)
{
my_backend_struct *backend;
backend = calloc(1, sizeof (my_backend_struct));
backend->custom_context = …;
backend->parent.read = &my_backend__read;
backend->parent.read_prefix = &my_backend__read_prefix;
backend->parent.read_header = &my_backend__read_header;
// …
*backend_out = (git_odb_backend *) backend;
return GIT_SUCCESS;
}
这里最微妙的约束是 my_backend_struct
的第一个成员必须是 git_odb_backend
结构体;这确保了内存布局符合 Libgit2 代码的预期。其余部分是任意的;这个结构体可以根据你的需要变得或大或小。
初始化函数为该结构体分配内存,设置自定义上下文,然后填充其支持的 parent
结构体成员。请查看 Libgit2 源码中的 include/git2/sys/odb_backend.h
文件以获取完整的调用签名集;你的特定用例将有助于确定你需要支持哪些。
其他绑定
Libgit2 具有多种语言的绑定。在此,我们展示一个使用本文撰写时一些更完整的绑定包的小例子;许多其他语言(包括 C++、Go、Node.js、Erlang 和 JVM)也有库,都处于不同的成熟阶段。官方的绑定集合可以在 https://github.com/libgit2 浏览仓库找到。我们将编写的代码将返回 HEAD 最终指向的提交的提交信息(类似于 git log -1
)。
LibGit2Sharp
如果你正在编写 .NET 或 Mono 应用程序,那么 LibGit2Sharp(https://github.com/libgit2/libgit2sharp)是你正在寻找的。这些绑定是用 C# 编写的,并且非常注意将原始的 Libgit2 调用封装为具有原生感的 CLR API。以下是我们的示例程序的样子
new Repository(@"C:\path\to\repo").Head.Tip.Message;
对于桌面 Windows 应用程序,甚至还有一个 NuGet 包可以帮助你快速入门。
objective-git
如果你的应用程序运行在 Apple 平台上,你很可能正在使用 Objective-C 作为你的实现语言。Objective-Git(https://github.com/libgit2/objective-git)是 Libgit2 在该环境下的绑定的名称。示例程序如下所示
GTRepository *repo =
[[GTRepository alloc] initWithURL:[NSURL fileURLWithPath: @"/path/to/repo"] error:NULL];
NSString *msg = [[[repo headReferenceWithError:NULL] resolvedTarget] message];
Objective-git 与 Swift 完全兼容,所以如果你已经放弃了 Objective-C,也无需担心。
pygit2
Libgit2 在 Python 中的绑定称为 Pygit2,可以在 https://www.pygit2.org 找到。我们的示例程序
pygit2.Repository("/path/to/repo") # open repository
.head # get the current branch
.peel(pygit2.Commit) # walk down to the commit
.message # read the message
延伸阅读
当然,全面介绍 Libgit2 的功能超出了本书的范围。如果你想了解更多关于 Libgit2 本身的信息,可以在 https://libgit2.github.com/libgit2 找到 API 文档,并在 https://libgit2.github.com/docs 找到一系列指南。对于其他绑定,请查阅捆绑的 README 和测试;那里通常会有一些小的教程和进一步阅读的指引。