Въведение

Преглед като Markdown Редактиране в GitHub Документация за bfe242f

Pitmaster е библиотека на PHP без външни зависимости, която чете и записва хранилища Git директно. Основните операции с хранилището не стартират двоичния файл git и не използват FFI. Моделът на обектите Git, форматът на pack файловете, форматът на индекса и smart транспортът HTTP са реализирани на PHP.

Защо съществува Pitmaster

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

Pitmaster премахва зависимостта от git за основната работа с хранилища. Вашето приложение PHP може да чете историята на комитите, да създава комити, да изчислява разлики, да проверява състоянието и да изпраща към отдалечени хранилища чрез smart HTTP, използвайки само вградените функции на PHP. Изключенията са hook-овете и транспортът SSH: и двете стартират процеси и могат да бъдат изключени за всеки обект на хранилище (вижте Hooks).

Какво прави

Чете и записва свободни обекти (blob, tree, commit, tag)
Чете pack файлове и разрешава вериги delta (OFS_DELTA и REF_DELTA)
Записва pack файлове за мрежови операции
Чете и записва индекса/областта за подготовка (формати v2, v3, v4)
Чете и записва препратки (клонове, етикети, HEAD, packed-refs, reftable)
Изчислява разлики във формата unified на git (алгоритми Myers, Patience, Histogram и Minimal)
Извършва тристранни сливания с откриване на конфликти
Обхожда графи на комитите (log, ancestry, merge base)
Използва протокола Git smart HTTP (clone, fetch, push)
Поддържа работни дървета, подмодули, stash, hook-ове и Git LFS

Какви са изискванията

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

Основните операции с хранилището не изискват двоичния файл git. Незадължителните функции може да изискват допълнителни възможности по време на изпълнение: изпълнението на hook използва 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.