Введение

Просмотреть как Markdown Редактировать на GitHub Документация по bfe242f

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

Зачем нужен Pitmaster

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

Pitmaster устраняет зависимость от git при основных операциях с репозиторием. Ваше приложение PHP может просматривать историю коммитов, создавать коммиты, вычислять различия, проверять состояние и отправлять данные в удалённые репозитории по умному протоколу HTTP, используя только встроенные функции PHP. Исключения — хуки и транспорт SSH: оба запускают процессы, и оба можно отключить для каждого дескриптора репозитория (см. раздел Хуки).

Возможности

Читает и записывает отдельные объекты (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');

Начните с раздела Начало работы, затем изучите API, CLI и Операции, чтобы ознакомиться с остальными возможностями. В разделе Тестирование объясняется, как Pitmaster проверяется на соответствие git.