libgit2 - 可链接的 Git 库

构建状态
main 分支 CI 构建 CI Build
v1.8 分支 CI 构建 CI Build
v1.7 分支 CI 构建 CI Build
每日构建 Nightly Build Coverity Scan Status

libgit2 是一个便携式、纯 C 实现的 Git 核心方法库，它提供了一个具有稳定 API 的可链接库，允许你将 Git 功能构建到你的应用程序中。像 Rugged (Ruby)、LibGit2Sharp (.NET)、pygit2 (Python) 和 NodeGit (Node) 这样的语言绑定允许你用你喜欢的语言构建 Git 工具。

libgit2 被用于驱动 Git GUI 客户端，例如 GitKraken 和 GitButler，以及 Git 托管提供商，例如 GitHub、GitLab 和 Azure DevOps。每次你点击“合并拉取请求”时，我们都会执行合并操作。

libgit2 使用 非常宽松的许可协议 (带有特殊链接例外的 GPLv2)。这意味着你可以将该库链接到任何类型的软件，而无需使该软件遵守 GPL。对 libgit2 的更改仍将受其 GPL 许可证的约束。 此外，示例代码已发布到公共领域（有关更多信息，请参阅单独的许可证）。

目录

使用 libgit2

这些说明大部分都假设你在用 C 编写应用程序，并且希望直接使用 libgit2。如果你不使用 C，而是用其他语言或平台编写，例如 .NET、Node.js 或 Ruby，那么可能有一个“语言绑定”可以用来处理调用本机代码的繁琐任务。

但是如果你确实想直接使用 libgit2——因为你在用 C 构建应用程序——那么你也许可以使用现有的二进制文件。 vcpkg 和 conan 包管理器有相应的包。 并且 libgit2 在 Homebrew 和大多数 Linux 发行版中都可用。

但是，这些版本可能已过时，如果可能，我们建议使用最新版本。 幸运的是，libgit2 并不难编译。

快速入门

构建 libgit2 的先决条件

  1. CMake，建议将其安装到你的 PATH 中。
  2. Python 被我们的测试框架使用，并且应该安装到你的 PATH 中。
  3. C 编译器：libgit2 是 C90，应该可以在大多数编译器上编译。
    • Windows：推荐使用 Visual Studio
    • Mac：推荐使用 Xcode
    • Unix：推荐使用 gcc 或 clang。

构建

  1. 在 libgit2 源代码目录下创建一个构建目录，然后进入该目录：mkdir build && cd build
  2. 创建 cmake 构建环境：cmake ..
  3. 构建 libgit2：cmake --build .

这些步骤有问题？ 请阅读我们的故障排除指南。 以下提供更详细的构建指导。

获取帮助

与我们聊天

获取帮助

如果你对该库有疑问，请务必查看 API 文档。 如果你还有问题，请在 Slack 上联系我们，或者在 StackOverflow 上发布问题（使用 libgit2 标签）。

报告错误

请打开一个 GitHub Issue 并尽可能包含更多信息。 如果可能，请提供说明你所看到问题的示例代码。 如果你仅在特定存储库上看到错误，请尽可能提供指向它的链接。

我们要求你不要打开 GitHub Issue 寻求帮助，仅用于错误报告。

报告安全问题

请查看 SECURITY.md。

它能做什么

libgit2 使你能够使用你选择的编程语言管理 Git 存储库。 它在生产中用于驱动许多应用程序，包括 GitHub.com、Plastic SCM 和 Azure DevOps。

它不旨在取代 git 工具或其面向用户的命令。 某些 API 类似于底层命令，因为这些命令与 Git 系统的概念紧密相关，但是用户键入的大多数命令都超出了此库直接实现的范围。

该库提供

由于 libgit2 纯粹是 Git 系统的使用者，因此我们必须适应上游所做的更改。 这有两个主要后果

可选依赖项

尽管该库提供了 git 功能，而无需依赖项，但它可以利用一些库来添加功能

初始化

该库需要跟踪一些全局状态。 调用

git_libgit2_init();

在调用任何其他 libgit2 函数之前。 你可以多次调用此函数。 匹配的调用次数

git_libgit2_shutdown();

将释放资源。 请注意，如果你有 worker 线程，则应在这些线程退出后调用 git_libgit2_shutdown。 如果你需要协助协调此操作，只需让 worker 线程在启动时调用 git_libgit2_init，在关闭时调用 git_libgit2_shutdown 即可。

线程

有关信息，请参见 线程

约定

有关我们使用的外部和内部 API/编码约定的概述，请参见 约定。

构建 libgit2 - 使用 CMake

构建

libgit2 在大多数平台上都可以干净地构建，而无需任何外部依赖项。 在类似 Unix 的系统（例如 Linux、*BSD 和 Mac OS X）下，libgit2 希望 pthreads 可用； 它们应默认安装在所有系统上。 在 Windows 下，libgit2 使用本机 Windows API 进行线程处理。

libgit2 库在所有平台上都使用 CMake（版本 2.8 或更高版本）构建。

在大多数系统上，你可以使用以下命令构建该库

$ mkdir build && cd build
$ cmake ..
$ cmake --build .

或者，你可以将 CMake GUI 工具指向 CMakeLists.txt 文件并生成特定于平台的构建项目或 IDE 工作区。

如果你不熟悉 CMake，更详细的解释可能会有所帮助。

运行测试

构建完成后，你可以使用以下命令从 build 目录运行测试

$ ctest -V

或者，你可以使用以下命令直接运行测试套件

$ ./libgit2_tests

直接调用测试套件很有用，因为它允许你使用 -s 标志执行单个测试或测试组。 例如，要运行索引测试

$ ./libgit2_tests -sindex

要运行名为 index::racy::diff 的单个测试，该测试对应于测试函数 test_index_racy__diff

$ ./libgit2_tests -sindex::racy::diff

测试套件将为每个通过的测试打印一个 .，为任何失败的测试打印一个 F。 S 表示由于测试不适用于你的平台或特别昂贵而被跳过。

注意： 从 发行版 或从 main 分支构建未修改的源代码树时，应该没有失败的测试。 如果你看到测试失败，请联系我们或打开一个 issue。

安装

要安装该库，你可以通过设置以下内容来指定安装前缀

$ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix
$ cmake --build . --target install

高级用法

有关更高级的用法或有关 CMake 的问题，请阅读 https://cmake.com.cn/Wiki/CMake_FAQ。

声明了以下 CMake 变量

要列出所有构建选项及其当前值，您可以执行以下操作

# Create and set up a build directory
$ mkdir build
$ cmake ..
# List all build options and their values
$ cmake -L

编译器和链接器选项

CMake 允许您指定一些变量来控制编译器和链接器的行为。这些标志很少使用，但对于 64 位到 32 位的交叉编译可能很有用。

MacOS X

如果您想为 Mac OS X 构建通用二进制文件，如果您在配置时使用 -DCMAKE_OSX_ARCHITECTURES="i386;x86_64"，CMake 会为您设置好一切。

Android

使用 make-standalone-toolchain.sh 脚本从 NDK 中提取工具链。 可选地，交叉编译并将 OpenSSL 安装在其中。 然后创建一个 CMake 工具链文件，该文件配置到您的交叉编译器的路径（将 {PATH} 替换为工具链的完整路径）

SET(CMAKE_SYSTEM_NAME Linux)
SET(CMAKE_SYSTEM_VERSION Android)

SET(CMAKE_C_COMPILER   {PATH}/bin/arm-linux-androideabi-gcc)
SET(CMAKE_CXX_COMPILER {PATH}/bin/arm-linux-androideabi-g++)
SET(CMAKE_FIND_ROOT_PATH {PATH}/sysroot/)

SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

配置时，将 -DCMAKE_TOOLCHAIN_FILE={pathToToolchainFile} 添加到 cmake 命令。

MinGW

如果您想在启用 SSH 支持的 MinGW 环境中构建库，您可能需要在配置时将 -DCMAKE_LIBRARY_PATH="${MINGW_PREFIX}/${MINGW_CHOST}/lib/" 标志传递给 CMake。 这是因为 CMake 默认情况下无法在 MinGW 文件夹中找到 Win32 库，并且您可能会看到一条错误消息，指出 CMake 无法在配置期间解析 ws2_32 库。

另一种选择是在配置之前安装 msys2-w32api-runtime 包。 此包将 Win32 库安装到 /usr/lib 文件夹中，该文件夹默认情况下被 CMake 识别为库路径。 但请注意，此包适用于与 MinGW 不同的 MSYS 子系统。

语言绑定

以下是当前可用的 libgit2 的绑定

如果您开始使用另一种语言绑定到 libgit2，请告知我们，以便我们可以将其添加到列表中。

我如何贡献？

我们欢迎新的贡献者！ 我们有很多标记为 "可以争取" 和 "简单修复" 的问题，这些是上手的好地方。 在我们的 未完成的项目 列表中有更详细的信息。

请务必查看 贡献指南 以了解我们的工作流程，以及 libgit2 编码约定。

许可证

libgit2 在 GPL2 带有链接例外下发布。 这意味着您可以从任何程序（专有或开源、付费或免费）链接到和使用该库。 但是，如果您修改 libgit2 本身，则必须分发您修改后的 libgit2 版本的源代码。

请参阅 COPYING 文件 以获取完整的许可文本。