# 简介
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 传输是例外：两者都会启动进程，并且都可以针对每个仓库句柄关闭（参见[钩子](https://pitmaster.inline0.dev/zh/docs/advanced/hooks)）。

## 功能说明

- 读取和写入松散对象（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` 二进制文件。

## 快速示例

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

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

从 [入门指南](https://pitmaster.inline0.dev/zh/docs/getting-started)开始，然后使用 [API](https://pitmaster.inline0.dev/zh/docs/api)、[CLI](https://pitmaster.inline0.dev/zh/docs/cli)，其余功能请参阅 [运维](https://pitmaster.inline0.dev/zh/docs/operations/read)。[测试](https://pitmaster.inline0.dev/zh/docs/testing)说明了如何根据 `git` 检查 Pitmaster。