简介

Pitmaster 是一个纯 PHP 库，可直接读取和写入 Git 仓库。核心仓库操作不会调用 git 二进制文件，也不使用 FFI。Git 对象模型、pack 文件格式、索引格式和 smart HTTP 传输均由 PHP 实现。

Pitmaster 的由来

与 Git 仓库交互的 PHP 应用通常会调用 git 二进制文件。这种方式可行，但会导致应用必须安装 git，引发与 exec() 和 proc_open() 相关的安全问题，也让应用难以部署在受限环境中（例如没有 git 的容器、共享主机和无服务器函数）。

Pitmaster 消除了核心仓库操作对 git 的依赖。你的 PHP 应用可以读取提交历史、创建提交、计算差异、检查状态，并通过 smart HTTP 推送到远程仓库；这些操作只需使用 PHP 内置函数即可。钩子和 SSH 传输是例外：两者都会启动进程，并且都可以针对每个仓库句柄关闭（参见钩子）。

功能说明

• 读取和写入松散对象（blob、tree、commit、tag）
• 读取 pack 文件并解析 delta 链（OFS_DELTA 和 REF_DELTA）
• 为网络操作写入 pack 文件
• 读取和写入索引/暂存区（v2、v3、v4 格式）
• 读取和写入 refs（分支、标签、HEAD、packed-refs、reftable）
• 使用 git 的统一格式计算差异（Myers、Patience、Histogram 和 Minimal 算法）
• 执行三方合并并检测冲突
• 遍历提交图（日志、祖先关系、合并基点）
• 使用 Git smart HTTP 协议（克隆、获取、推送）
• 支持工作树、子模块、stash、钩子和 Git LFS

运行要求

• PHP 8.2 或更高版本
• zlib 扩展（几乎所有 PHP 安装都内置此扩展）
• json 扩展
• mbstring 扩展（在 composer.json 中声明，因此安装 Composer 时需要此扩展）
• ctype 扩展（用于验证对象哈希；大多数 PHP 构建中已启用，但未在 composer.json 中声明）

核心仓库操作不需要 git 二进制文件。可选功能可能需要额外的运行时能力：执行钩子需要 proc_open()；SSH 传输在已加载时使用 ext-ssh2，否则会通过 proc_open() 启动系统 ssh 二进制文件。

快速示例

use Pitmaster\Pitmaster;

$repo = Pitmaster::open('/path/to/project');

// Read the current HEAD commit
$head = $repo->head();
echo $head->message;

// List branches
foreach ($repo->branches() as $branch) {
    echo $branch . "\n";
}

// Check status
foreach ($repo->status() as $entry) {
    echo "{$entry->path}: {$entry->index->value}{$entry->worktree->value}\n";
}

// Create a commit
$repo->add('src/Feature.php');
$commitId = $repo->commit('Add new feature');

从 入门指南开始，然后使用 API、CLI，其余功能请参阅 运维。测试说明了如何根据 git 检查 Pitmaster。