libgit2 - 可链接的 Git 库

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

libgit2 是 Git 核心方法的便携式、纯 C 实现，它作为一个具有可靠 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();

将释放资源。 请注意，如果您有工作线程，则应在这些线程退出后调用 git_libgit2_shutdown。 如果您需要协助协调此操作，只需让工作线程在启动时调用 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 表示测试已被跳过，因为它不适用于您的平台或特别昂贵。

注意： 当您从 release 或从 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 会为您设置好一切。

安卓

使用 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 将其识别为库路径。 但请注意，此软件包适用于 MSYS 子系统，该子系统与 MinGW 不同。

语言绑定

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

如果您启动了另一个 libgit2 的语言绑定，请告知我们，以便我们将其添加到列表中。

我如何贡献？

我们欢迎新的贡献者！我们有许多标记为 "up for grabs" 和 "easy fix" 的问题，这些问题是入门的好地方。 在我们的 未完成的项目列表中有更详细的信息。

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

许可证

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

有关完整的许可文本，请参见 COPYING 文件。