libgit2/libgit2
GitHub: libgit2/libgit2
跨平台、可链接的纯 C 语言 Git 核心方法库，允许开发者将 Git 功能无缝集成到应用程序中。
Stars: 10405 | Forks: 2589
# libgit2 - Git 可链接库
[](https://www.bestpractices.dev/projects/9609)
| 构建状态 | |
| ------------ | - |
| **main** 分支构建 | [](https://github.com/libgit2/libgit2/actions/workflows/main.yml?query=event%3Apush+branch%3Amain) [](https://github.com/libgit2/libgit2/actions/workflows/experimental.yml?query=event%3Apush+branch%3Amain) |
| **v1.9 分支**构建 | [](https://github.com/libgit2/libgit2/actions/workflows/main.yml?query=event%3Apush+branch%3Amaint%2Fv1.9) [](https://github.com/libgit2/libgit2/actions/workflows/experimental.yml?query=event%3Apush+branch%3Amaint%2Fv1.9) |
| **v1.8 分支**构建 | [](https://github.com/libgit2/libgit2/actions/workflows/main.yml?query=event%3Apush+branch%3Amaint%2Fv1.8) [](https://github.com/libgit2/libgit2/actions/workflows/experimental.yml?query=event%3Apush+branch%3Amaint%2Fv1.8) |
| **Nightly** 构建 | [](https://github.com/libgit2/libgit2/actions/workflows/nightly.yml) [](https://scan.coverity.com/projects/639) |
`libgit2` 是一个跨平台、纯 C 实现的 Git 核心方法库
以可靠的 API 形式作为可链接库提供，允许您将 Git
功能构建到您的应用程序中。
`libgit2` 被广泛应用于各种场景，从 GUI 客户端到托管
提供商（"forges"），以及介于两者之间的无数实用程序和应用程序。由于它是用 C 编写的，因此可以通过 "绑定"（bindings）提供给任何
其他编程语言，因此您可以在
[Ruby](https://github.com/libgit2/rugged),
[.NET](https://github.com/libgit2/libgit2sharp),
[Python](http://www.pygit2.org/),
[Node.js](http://nodegit.org),
[Rust](https://github.com/rust-lang/git2-rs), 等语言中使用它。
`libgit2` 根据**非常宽松的许可证**（GPLv2 附带特殊的链接例外条款）进行许可。这意味着您可以将该库与任何类型的软件链接，而无需使该软件受 GPL 约束。对 libgit2 的更改仍受其 GPL 许可证覆盖。
# 目录
* [使用 libgit2](#using-libgit2)
* [快速开始](#quick-start)
* [获取帮助](#getting-help)
* [功能概览](#what-it-can-do)
* [可选依赖项](#optional-dependencies)
* [初始化](#initialization)
* [线程](#threading)
* [约定](#conventions)
* [构建 libgit2 - 使用 CMake](#building-libgit2---using-cmake)
* [构建](#building)
* [安装](#installation)
* [高级用法](#advanced-usage)
* [编译器和链接器选项](#compiler-and-linker-options)
* [macOS](#macos)
* [iOS](#ios)
* [Android](#android)
* [MinGW](#mingw)
* [语言绑定](#language-bindings)
* [如何贡献？](#how-can-i-contribute)
* [许可证](#license)
# 使用 libgit2
这些说明中的大多数假设您正在编写 C 应用程序
并希望直接使用 libgit2。如果您*不*使用 C，
而是使用不同的语言或平台，如 .NET、
Node.js 或 Ruby，那么可能有一个
"[语言绑定](#language-bindings)" 可以使用，用于处理
调用本机代码的繁琐任务。
但是，如果您*确实*想直接使用 libgit2 - 因为您正在用 C 构建应用程序 - 那么您也许可以使用现有的二进制文件。
有一些
[vcpkg](https://github.com/Microsoft/vcpkg) 和
[conan](https://conan.io/center/recipes/libgit2)
包管理器的包。而且 libgit2 在
[Homebrew](https://formulae.brew.sh/formula/libgit2) 和大多数 Linux
发行版中都有提供。
但是，这些版本*可能*已经过时，如果可能的话，我们建议使用
最新版本。幸好 libgit2 并不难编译。
# 快速开始
构建 libgit2 的**先决条件**：
1. [CMake](https://cmake.org/)，建议安装到
您的 `PATH` 中。
2. [Python](https://www.python.org) 被我们的测试框架使用，并且
应该安装到您的 `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 .`
在这些步骤中遇到问题？请阅读我们的[故障排除指南](docs/troubleshooting.md)。
下面提供了更详细的构建指导。
# 获取帮助
**与我们聊天**
- 通过 IRC：加入 [libera](https://libera.chat) 上的 [#libgit2](https://web.libera.chat/#libgit2)。
- 通过 Slack：访问 [slack.libgit2.org](http://slack.libgit2.org/)
注册，然后加入 `#libgit2`
**获取帮助**
如果您对库有疑问，请务必查看
[API 文档](https://libgit2.org/libgit2/)。如果您仍有
疑问，请在 Slack 上联系我们，或者在
[StackOverflow](http://stackoverflow.com/questions/tagged/libgit2)
上发布问题（标记 `libgit2`）。
**报告错误**
请打开一个 [GitHub Issue](https://github.com/libgit2/libgit2/issues)
并尽可能包含更多信息。如果可能，请提供
说明您遇到的问题的示例代码。如果您
仅在特定的存储库中看到错误，请尽可能提供指向它的链接。
我们要求您不要打开 GitHub Issue 来寻求帮助，仅用于错误报告。
**报告安全问题**
请查看 SECURITY.md。
# 功能概览
libgit2 为您提供了在您选择的编程语言中管理 Git 存储库的能力。它在生产中被用于为许多应用程序提供动力，包括 GitHub.com、Plastic SCM 和 Azure DevOps。
它的目标不是取代 git 工具或其面向用户的命令。一些 API 类似于底层命令（plumbing commands），因为它们与 Git 系统的概念紧密一致，但用户输入的大多数命令不在该库的直接实现范围内。
该库提供：
* SHA 转换、格式化和缩写
* 抽象的 ODB 后端系统
* commit、tag、tree 和 blob 的解析、编辑和回写
* tree 遍历
* 版本遍历
* 索引文件（暂存区）操作
* 引用管理（包括打包引用）
* 配置文件管理
* 高级存储库管理
* 线程安全和可重入性
* 描述性和详细的错误消息
* ...以及更多（超过 175 种不同的 API 调用）
由于 libgit2 纯粹是 Git 系统的消费者，我们必须
适应上游所做的更改。这有两个主要后果：
* 某些更改可能需要我们更改提供的接口。虽然
我们尝试以通用方式实现函数，以便不需要
未来的更改，但我们不能保证完全稳定的 API。
* 由于我们必须跟上上游行为更改的步伐，我们
可能会在某些领域滞后。我们通常会在我们的
问题跟踪器中用标签 "git change" 记录这些不兼容性。
# 可选依赖项
虽然该库提供了依赖项很少的 git 功能，但一些推荐的依赖项用于提高性能
或完整功能。
- 哈希生成：Git 使用 SHA1DC（冲突检测 SHA1）
作为其默认哈希生成。SHA256 支持是实验性的，并且在
macOS 和 Windows 上由系统库提供优化支持，或者在 Unix 系统上由 HTTPS 库在可用时提供。
- 线程：在 Windows 上由系统库提供，
在 Unix 系统上由 pthreads 提供。
- HTTPS：在 macOS 和 Windows 上由系统库提供，
或在其他 Unix 系统上由 OpenSSL 或 mbedTLS 提供。
- SSH：由 [libssh2](https://libssh2.org/) 或通过调用
[OpenSSH](https://www.openssh.com) 提供。
- Unicode：在 Windows 和 macOS 上由系统库提供。
# 初始化
该库需要跟踪一些全局状态。在调用任何其他 libgit2 函数之前，请调用
```
git_libgit2_init();
```
您可以多次调用此函数。调用相同次数的
```
git_libgit2_shutdown();
```
将释放资源。请注意，如果您有工作线程，您应该
在这些线程退出*后*调用 `git_libgit2_shutdown`。如果您
需要协助协调这一点，只需让工作线程在
启动时调用 `git_libgit2_init`，在关闭时调用 `git_libgit2_shutdown`。
# 线程
有关信息，请参阅 [线程](docs/threading.md)
# 约定
有关我们使用的外部和内部 API/编码约定的概述，请参阅 [约定](docs/conventions.md)。
# 构建 libgit2 - 使用 CMake
## 构建
在大多数平台上，`libgit2` 都可以干净地构建，不需要任何外部
依赖项作为要求。`libgit2` 使用
[CMake](`：在 Unix 上为 SPNEGO 身份验证启用 GSSAPI。
默认为 `OFF`。
* `USE_HTTP_PARSER=type`：选择 HTTP 解析器；要么是用于外部
[`http-parser`](https://github.com/nodejs/http-parser) 依赖项的 `http-parser`，
用于外部 [`llhttp`](https://github.com/nodejs/llhttp)
依赖项的 `llhttp`，或者是 `builtin`。默认为 `builtin`。
* `REGEX_BACKEND=type`：选择要使用的正则表达式后端；
`regcomp_l`、`pcre2`、`pcre`、`regcomp` 或 `builtin` 之一。
默认是在可用的情况下使用 `regcomp_l`，如果找到 PCRE 则使用 PCRE，否则，
使用内置的。
* `USE_BUNDLED_ZLIB=type`：选择捆绑的 zlib；`ON` 或 `OFF`。
默认是使用系统 zlib（如果可用），回退到捆绑的 zlib。
## 定位依赖项
`libgit2` 项目使用 `cmake`，因为它有助于跨平台
项目，尤其是那些具有许多依赖项的项目。如果您的依赖项
位于非标准位置，您可能需要使用 `_ROOT_DIR` 选项
来指定它们的位置。例如，要指定 OpenSSL 位置：
```
$ cmake -DOPENSSL_ROOT_DIR=/tmp/openssl-3.3.2 ..
```
由于这些选项对于 CMake 是通用的，它们的
[文档](https://cmake.org/documentation/) 可能会有所帮助。如果
您对依赖项有疑问，请 [联系我们](#getting-help)。
## 运行测试
构建完成后，您可以使用以下命令从 `build` 目录运行测试
```
$ ctest -V
```
或者，您可以直接使用以下命令运行测试套件，
```
$ ./libgit2_tests
```
直接调用测试套件很有用，因为它允许您使用 `-s` 标志执行
单个测试或测试组。例如，要
运行索引测试：
```
$ ./libgit2_tests -sindex
```
要运行名为 `index::racy::diff` 的单个测试，该测试对应于
测试函数
[`test_index_racy__diff`](https://github.com/libgit2/libgit2/blob/main/tests/libgit2/index/racy.c#L22):
```
$ ./libgit2_tests -sindex::racy::diff
```
测试套件将为每个通过的测试打印一个 `.`，为任何失败的测试打印一个 `F`。
`S` 表示跳过了测试，因为它不适用于您的平台或特别昂贵。
**注意：** 当您从 [发行版](https://github.com/libgit2/libgit2/releases) 或 [main 分支](https://github.com/libgit2/libgit2/tree/main) 构建未修改的源代码树时，应该*没有*失败的测试。
如果您看到测试失败，请联系我们或
[打开问题](https://github.com/libgit2/libgit2/issues)。
## 安装
要安装该库，您可以通过设置来指定安装前缀：
```
$ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix
$ cmake --build . --target install
```
## 高级用法
有关更高级的用法或有关 CMake 的问题，请阅读
[CMake FAQ](https://cmake.org/Wiki/CMake_FAQ。
声明了以下 CMake 变量：
- `CMAKE_INSTALL_BINDIR`：将二进制文件安装到何处。
- `CMAKE_INSTALL_LIBDIR`：将库安装到何处。
- `CMAKE_INSTALL_INCLUDEDIR`：将头文件安装到何处。
- `BUILD_SHARED_LIBS`：将 libgit2 构建为共享库（默认为 ON）
- `BUILD_TESTS`：构建单元和集成测试套件（默认为 ON）
- `USE_THREADS`：使用线程支持构建 libgit2（默认为 ON）
要列出所有构建选项及其当前值，您可以执行
以下操作：
```
# 创建并设置 build 目录
$ mkdir build && cd build
$ cmake ..
# 列出所有 build 选项及其值
$ cmake -L
```
## 编译器和链接器选项
有几个选项控制编译器和链接器的行为。这些标志可能对交叉编译或专用
设置很有用。
- `CMAKE_C_FLAGS`：设置您自己的编译器标志
- `CMAKE_C_STANDARD`：要编译依据的 C 标准；默认为 `C90`
- `CMAKE_C_EXTENSIONS`：是否支持编译器扩展；默认为 `OFF`
- `CMAKE_FIND_ROOT_PATH`：覆盖库的搜索路径
- `ZLIB_LIBRARY`、`OPENSSL_SSL_LIBRARY` 和 `OPENSSL_CRYPTO_LIBRARY`：
告诉 CMake 在哪里找到那些特定的库
- `LINK_WITH_STATIC_LIBRARIES`：仅链接系统库的静态版本
## macOS
如果您想使用 Xcode，您可以使用 "-G Xcode" 生成 Xcode 项目。
```
# 创建并设置 build 目录
$ mkdir build && cd build
$ cmake -G Xcode ..
```
## iOS
1. 获取 iOS cmake 工具链文件：
您可以使用现有的工具链文件，如 [ios-cmake](https://github.com/leetal/ios-cmake) 或编写您自己的工具链文件。
2. 指定工具链和系统名称：
- CMAKE_TOOLCHAIN_FILE 变量指向 iOS 的工具链文件。
- CMAKE_SYSTEM_NAME 应设置为 iOS。
3. 示例命令：
假设您使用的是 ios-cmake 工具链，命令可能如下所示：
```
cmake -G Xcode -DCMAKE_TOOLCHAIN_FILE=path/to/ios.toolchain.cmake -DCMAKE_SYSTEM_NAME=iOS -DPLATFORM=OS64 ..
```
4. 构建项目：
生成项目后，在 Xcode 中打开 .xcodeproj 文件，选择您的 iOS 设备或模拟器作为目标，然后构建您的项目。
## 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 默认将其识别为库路径。
但请注意，此包适用于 MSYS 子系统，这与 MinGW 不同。
# 语言绑定
以下是当前可用的 libgit2 绑定：
* C++
* libqgit2，Qt 绑定
* D
* dlibgit
* Delphi
* GitForDelphi
* libgit2-delphi
* Erlang
* Geef
* Go
* git2go
* GObject
* libgit2-glib
* Guile
* Guile-Git
* Haskell
* hgit2
* Java
* Jagged
* Git24j
* Javascript / WebAssembly ( 浏览器和 nodejs )
* WASM-git
* Julia
* LibGit2.jl
* Lua
* luagit2
* .NET
* libgit2sharp
* Node.js
* nodegit
* Objective-C
* objective-git
* OCaml
* ocaml-libgit2
* Parrot Virtual Machine
* parrot-libgit2
* Perl
* Git-Raw
* Pharo Smalltalk
* libgit2-pharo-bindings
* PHP
* php-git2
* Python
* pygit2
* R
* gert
* git2r
* Ruby
* Rugged
* Rust
* git2-rs
* Swift
* SwiftGit2
* SwiftGitX
* swift-libgit2
* Tcl
* lg2
* Vala
* libgit2.vapi
如果您开始使用另一种语言绑定到 libgit2，请告诉我们，以便
我们可以将其添加到列表中。
# 如何贡献？
我们欢迎新的贡献者！我们有许多被标记为
["up for grabs"](https://github.com/libgit2/libgit2/issues?q=is%3Aissue+is%3Aopen+label%3A%22up+for+grabs%22)
和
["easy fix"](https://github.com/libgit2/libgit2/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22easy+fix%22)
的问题，这些都是切入并开始的好地方。在我们的 [杰出项目](docs/projects.md) 列表中有更详细的信息。
请务必查看 [贡献指南](docs/contributing.md)
以了解我们的工作流程，以及 libgit2
[编码约定](docs/conventions.md)。
# 许可证
`libgit2` 遵循 GPL2 **附带链接例外条款**。这意味着您可以
从任何程序（专有或开源；付费或免费）链接和使用该库。
但是，如果您修改 libgit2 本身，则必须分发
您修改的 libgit2 版本的源代码。
有关完整的许可证文本，请参阅 [COPYING 文件](COPYING)。
标签：Bash脚本, Git, Git实现, libgit2, SOC Prime, 代码管理, 分布式版本控制, 可移植, 安全可观测性, 安全测试工具, 客户端加密, 库, 应急响应, 应用程序集成, 开发工具, 开源, 版本控制, 链接库