# はじめに
Pitmasterは、Gitリポジトリをネイティブに読み書きする純粋なPHP製ライブラリです。コアとなるリポジトリ操作では`git`バイナリの起動やFFIの使用はありません。Gitのオブジェクトモデル、パックファイル形式、インデックス形式、smart HTTPトランスポートをPHPで実装しています。

## Pitmasterが作られた理由

PHPアプリケーションがGitリポジトリとやり取りする場合、通常は`git`バイナリをシェルから実行します。この方法は機能しますが、`git`のインストールが必須になり、`exec()`と`proc_open()`に関するセキュリティ上の懸念が生じます。また、gitのないコンテナ、共有ホスティング、サーバーレス関数など、制限された環境ではアプリケーションのデプロイが難しくなります。

Pitmasterは、コアリポジトリ操作における`git`依存をなくします。PHPアプリケーションは、PHP組み込みの関数だけを使って、コミット履歴の読み取り、コミットの作成、差分の計算、ステータスの確認、スマートHTTP経由でのリモートへのプッシュを実行できます。例外はフックとSSHトランスポートです。どちらもプロセスを起動しますが、リポジトリハンドルごとに無効にできます（[フック](https://pitmaster.inline0.dev/ja/docs/advanced/hooks)を参照）。

## 機能

- ルースオブジェクト（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`バイナリを起動します。

## 使用例

```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/ja/docs/getting-started)を読み、残りの範囲については[API](https://pitmaster.inline0.dev/ja/docs/api)、[CLI](https://pitmaster.inline0.dev/ja/docs/cli)、[操作](https://pitmaster.inline0.dev/ja/docs/operations/read)を参照してください。[テスト](https://pitmaster.inline0.dev/ja/docs/testing)では、Pitmasterが`git`に対してどのように検証されるかを説明しています。