Pitmaster

Git 中的 PHP：读取和写入仓库、执行 diff 和合并，以及通过智能 HTTP 通信，全程无需调用 git。

终端

composer require pitmaster/pitmaster

开始使用

GitHub

最新版本 v0.2.11 2026-09-24 MIT PHP 8.2+

终端

# List all branches (current marked with *)
./bin/pitmaster branch

# Create a new branch from HEAD
./bin/pitmaster branch feature/new-thing

# Delete a branch
./bin/pitmaster branch -d feature/old
./bin/pitmaster branch -D feature/old

实践应用

打开仓库，然后通过方法调用或命令行读取和写入。

从 PHP 读取仓库

Pitmaster::open() 会定位 .git 目录并返回仓库句柄。每个状态条目都会分别记录索引和工作树的状态。

在命令行中，./vendor/bin/pitmaster 会模拟部分 git 命令；由于 0.2.11，安装 Composer 后即可使用。

阅读入门指南

PHP

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";
}

终端

./vendor/bin/pitmaster log
./vendor/bin/pitmaster status
./vendor/bin/pitmaster diff
./vendor/bin/pitmaster show HEAD
./vendor/bin/pitmaster add file.txt
./vendor/bin/pitmaster commit -m "message"
./vendor/bin/pitmaster branch feature
./vendor/bin/pitmaster checkout feature
./vendor/bin/pitmaster merge feature

无需 git 二进制程序

核心操作在 PHP 8.2+ 中运行，无需 git 二进制程序或 FFI。钩子和 SSH 回退方案会启动进程，除非传入 ['hooks' => false] 或 processFreeOptions()。

读取与写入

松散对象、带增量解析的包文件、索引、引用和配置。git 可读取 Pitmaster 写入的索引版本 2 和 3，以及松散引用。

差异与合并

支持 Myers、patience 和 histogram 差异算法，并能检测重命名。支持带冲突标记的三方合并。

网络协议

通过智能 HTTP 或 SSH 克隆、获取和推送；克隆和获取还可回退到简单 HTTP。较低层级的客户端支持协议 v2。

Git 操作

add、commit、status、diff、merge、checkout、reset、stash、cherry-pick、revert、rebase、blame、grep。

CLI

22 个 git 风格的命令，包括 init、log、status、diff、add、commit、branch、merge、stash、blame 和 grep。克隆、获取和推送仅支持通过库调用。

经 Oracle 测试

761 个场景会将结果与从真实 git 捕获的输出进行比较，并在 CI 中运行；605 个场景来自 git 自身、libgit2、go-git、isomorphic-git、dulwich 和 JGit 的测试套件。

完整搜索

支持 blame、grep、bisect、notes 和日志路径筛选，无需调用 git。

为什么选择 Pitmaster

无需安装 git

提交、差异、状态和历史记录都在 PHP 中计算，因此即使容器和主机没有 git 二进制程序，也能操作仓库。

无需进程的句柄

Pitmaster::processFreeOptions() 会关闭钩子、fsmonitor 钩子、克隆、获取、推送和 SSH 进程传输。本地读写仍可正常进行。

已通过 git 验证

集成测试会针对 git 二进制运行，支持矩阵则统计其范围内、在声明的兼容范围内经 oracle 验证的 146 项功能中的 146 项。

SHA-1 与 SHA-256

使用 Pitmaster::init($path, 'sha256') 创建 SHA-256 仓库，或运行 init --object-format=sha256。支持读取和写入 pack 文件；支持读取 commit-graph、multi-pack index 和 reftable 文件。

对比

通过 PHP 使用 Git 仓库的其他方式，以及 Pitmaster 的不同之处。

Pitmaster 与其他工具的对比
工具	擅长领域	与 Pitmaster 的区别
git（命令行）	擅长领域参考实现，提供丰富的命令集，涵盖高级操作并可全面访问内部机制。	与 Pitmaster 的区别Pitmaster 在 PHP 进程内运行，核心操作不会通过 shell 调用 git。其 CLI 仅实现了 git 命令的一个子集。
czproject/git-php	擅长领域紧凑的 PHP API，支持 init、clone、commit、merge、分支、标签和远程仓库。可在 PHP 8.0 或更高版本上运行，并调用已安装的 git 客户端。	与 Pitmaster 的区别核心操作无需 git 客户端，因为 Pitmaster 会自行读写对象、pack 文件和索引。要求 PHP 8.2 或更高版本。
gitonomy/gitlib	擅长领域无需构建任何内容，即可通过 PHP 8.4 或更高版本访问仓库。其通过 shell 调用 git。	与 Pitmaster 的区别Pitmaster 的核心操作不会调用 shell；不启动进程的句柄会禁用需要启动进程的部分功能。
libgit2	擅长领域以可链接库形式提供的可移植 C 实现，涵盖 Git 的核心方法，并提供 Ruby、.NET、Python、Node.js、Rust 等语言的绑定。	与 Pitmaster 的区别Pitmaster 是通过 Composer 安装的纯 PHP，不含编译库或 FFI。它从 libgit2 的测试资源中导入了 63 个 oracle 场景。

来源，已选中 2026年10月14日

问答

来自 Pitmaster 文档的简明解答。

阅读文档

先从入门指南开始，了解如何通过 PHP 打开首个仓库；之后可参考 API 和 CLI。