Wprowadzenie

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: bfe242f

Pitmaster to czysta biblioteka PHP, która natywnie odczytuje i zapisuje repozytoria Git. Podstawowe operacje na repozytorium nie uruchamiają zewnętrznego pliku binarnego git ani nie korzystają z FFI. Model obiektów Git, format pliku pakietu, format indeksu oraz inteligentny transport HTTP są zaimplementowane w PHP.

Dlaczego istnieje Pitmaster

Aplikacje PHP współpracujące z repozytoriami Git zazwyczaj uruchamiają zewnętrzny plik binarny git. To działa, ale tworzy twardą zależność od zainstalowanego git, budzi obawy o bezpieczeństwo związane z exec() i proc_open() oraz utrudnia wdrażanie aplikacji w środowiskach o ograniczeniach (kontenery bez gita, hosting współdzielony, funkcje bezserwerowe).

Pitmaster eliminuje zależność od git przy podstawowych operacjach na repozytorium. Aplikacja PHP może odczytywać historię zatwierdzeń, tworzyć zatwierdzenia, obliczać różnice, sprawdzać stan i wysyłać zmiany do zdalnych repozytoriów przez inteligentny HTTP, korzystając wyłącznie z wbudowanych funkcji PHP. Wyjątki stanowią hooki i transport SSH: oba uruchamiają procesy i oba można wyłączyć dla danego uchwytu repozytorium (zob. Hooki).

Funkcje

Odczytuje i zapisuje luźne obiekty (blob, tree, commit, tag)
Odczytuje pliki pakietów i rozwiązuje łańcuchy delt (OFS_DELTA i REF_DELTA)
Zapisuje pliki pakietów na potrzeby operacji sieciowych
Odczytuje i zapisuje indeks/obszar przejściowy (formaty v2, v3, v4)
Odczytuje i zapisuje referencje (gałęzie, tagi, HEAD, packed-refs, reftable)
Oblicza różnice (algorytmy Myers, Patience, Histogram i Minimal) w ujednoliconym formacie gita
Wykonuje scalanie trójstronne z wykrywaniem konfliktów
Przechodzi przez grafy zatwierdzeń (log, pochodzenie, wspólna baza scalania)
Obsługuje inteligentny protokół Git HTTP (clone, fetch, push)
Obsługuje worktree, submoduły, stash, hooki i Git LFS

Wymagania

PHP 8.2 lub nowszy
Rozszerzenie zlib (wbudowane w niemal wszystkie instalacje PHP)
Rozszerzenie json
Rozszerzenie mbstring (zadeklarowane w composer.json, więc Composer wymaga go podczas instalacji)
Rozszerzenie ctype (używane do weryfikacji skrótów obiektów; włączone w większości kompilacji PHP, ale niezadeklarowane w composer.json)

Podstawowe operacje na repozytorium nie wymagają pliku binarnego git. Funkcje opcjonalne mogą wymagać dodatkowych możliwości środowiska uruchomieniowego: wykonywanie hooków korzysta z proc_open(), a transport SSH używa ext-ssh2, jeśli jest załadowane; w przeciwnym razie uruchamia systemowy plik binarny ssh za pośrednictwem proc_open().

Szybki przykład

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');

Zacznij od sekcji Pierwsze kroki, a następnie zapoznaj się z sekcjami API, CLI i Operacje, aby poznać pozostałe funkcje. Sekcja Testowanie wyjaśnia, jak Pitmaster jest sprawdzane względem git.