# Введение
Pitmaster — это библиотека, целиком написанная на PHP, которая напрямую читает и записывает репозитории Git. Основные операции с репозиторием не запускают двоичный файл `git` через командную оболочку и не используют FFI. Модель объектов Git, формат pack-файлов, формат индекса и транспорт умного протокола HTTP реализованы на PHP.

## Зачем нужен Pitmaster

Приложения PHP, работающие с репозиториями Git, обычно запускают двоичный файл `git` через командную оболочку. Это работает, но создаёт жёсткую зависимость от установленного `git`, вызывает вопросы безопасности при работе с `exec()` и `proc_open()` и усложняет развёртывание приложения в средах с ограничениями (контейнеры без git, виртуальный хостинг, бессерверные функции).

Pitmaster устраняет зависимость от `git` при основных операциях с репозиторием. Ваше приложение PHP может просматривать историю коммитов, создавать коммиты, вычислять различия, проверять состояние и отправлять данные в удалённые репозитории по умному протоколу HTTP, используя только встроенные функции PHP. Исключения — хуки и транспорт SSH: оба запускают процессы, и оба можно отключить для каждого дескриптора репозитория (см. раздел [Хуки](https://pitmaster.inline0.dev/ru/docs/advanced/hooks)).

## Возможности

- Читает и записывает отдельные объекты (blob, tree, commit, tag)
- Читает pack-файлы и разрешает цепочки delta (OFS_DELTA и REF_DELTA)
- Записывает pack-файлы для сетевых операций
- Читает и записывает индекс/область подготовки (форматы v2, v3, v4)
- Читает и записывает ссылки (ветки, теги, HEAD, packed-refs, Reftable)
- Вычисляет различия алгоритмами Myers, Patience, Histogram и Minimal в унифицированном формате git
- Выполняет трёхсторонние слияния с обнаружением конфликтов
- Обходит графы коммитов (журнал, предки, база слияния)
- Поддерживает умный протокол Git HTTP (клонирование, получение данных, отправка данных)
- Поддерживает рабочие деревья, подмодули, stash, хуки и Git LFS

## Требования

- PHP 8.2 или новее
- Расширение `zlib` (встроено практически во все установки PHP)
- Расширение `json`
- Расширение `mbstring` (указано в `composer.json`, поэтому Composer требует его при установке)
- Расширение `ctype` (для проверки хешей объектов; включено в большинство сборок PHP, но не указано в `composer.json`)

Для основных операций с репозиторием двоичный файл `git` не требуется. Дополнительным функциям могут понадобиться другие возможности среды выполнения: для выполнения хуков используется `proc_open()`, а транспорт SSH использует `ext-ssh2`, если он загружен, и в противном случае запускает системный двоичный файл `ssh` через `proc_open()`.

## Быстрый пример

```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/ru/docs/getting-started), затем изучите [API](https://pitmaster.inline0.dev/ru/docs/api), [CLI](https://pitmaster.inline0.dev/ru/docs/cli) и [Операции](https://pitmaster.inline0.dev/ru/docs/operations/read), чтобы ознакомиться с остальными возможностями. В разделе [Тестирование](https://pitmaster.inline0.dev/ru/docs/testing) объясняется, как Pitmaster проверяется на соответствие `git`.