はじめに
Pitmasterは、Gitリポジトリをネイティブに読み書きする純粋なPHP製ライブラリです。コアとなるリポジトリ操作ではgitバイナリの起動やFFIの使用はありません。Gitのオブジェクトモデル、パックファイル形式、インデックス形式、smart HTTPトランスポートをPHPで実装しています。
Pitmasterが作られた理由
PHPアプリケーションがGitリポジトリとやり取りする場合、通常はgitバイナリをシェルから実行します。この方法は機能しますが、gitのインストールが必須になり、exec()とproc_open()に関するセキュリティ上の懸念が生じます。また、gitのないコンテナ、共有ホスティング、サーバーレス関数など、制限された環境ではアプリケーションのデプロイが難しくなります。
Pitmasterは、コアリポジトリ操作におけるgit依存をなくします。PHPアプリケーションは、PHP組み込みの関数だけを使って、コミット履歴の読み取り、コミットの作成、差分の計算、ステータスの確認、スマートHTTP経由でのリモートへのプッシュを実行できます。例外はフックとSSHトランスポートです。どちらもプロセスを起動しますが、リポジトリハンドルごとに無効にできます（フックを参照）。
機能
- ルースオブジェクト（blob、tree、commit、tag）の読み書き
- パックファイルの読み取りと差分チェーンの解決（OFS_DELTAとREF_DELTA）
- ネットワーク操作用のパックファイルの書き込み
- インデックス／ステージング領域の読み書き（v2、v3、v4形式）
- 参照（ブランチ、タグ、HEAD、packed-refs、reftable）の読み書き
- gitの統一形式で差分を計算（Myers、Patience、Histogram、Minimalアルゴリズム）
- 競合検出に対応した3方向マージ
- コミットグラフの走査（ログ、祖先関係、マージベース）
- GitスマートHTTPプロトコルに対応（clone、fetch、push）
- worktree、サブモジュール、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、操作を参照してください。テストでは、Pitmasterがgitに対してどのように検証されるかを説明しています。