Úvod

Pitmaster je čistá knihovna PHP, která nativně čte a zapisuje úložiště Git. Základní operace s úložištěm nespouštějí binární soubor git v shellu ani nepoužívají FFI. Objektový model Git, formát souboru pack, formát indexu a chytrý přenos HTTP jsou implementovány v PHP.

Proč existuje Pitmaster

Aplikace PHP, které pracují s úložišti Git, obvykle spouštějí binární soubor git v shellu. Funguje to, ale vytváří to pevnou závislost na nainstalovaném git, přináší bezpečnostní rizika spojená s exec() a proc_open() a ztěžuje nasazení aplikace v omezených prostředích (kontejnery bez gitu, sdílený hosting, serverless funkce).

Pitmaster odstraňuje závislost na git při základní práci s úložištěm. Vaše aplikace PHP může číst historii commitů, vytvářet commity, počítat rozdíly, kontrolovat stav a odesílat změny do vzdálených úložišť pomocí chytrého přenosu HTTP, pouze s využitím vestavěných funkcí PHP. Výjimkou jsou hooky a přenos SSH: oba spouštějí procesy a lze je vypnout pro jednotlivý objekt úložiště (viz Hooky).

Co umí

• Čte a zapisuje volné objekty (blob, strom, commit, štítek)
• Čte soubory pack a řeší řetězce rozdílů (OFS_DELTA a REF_DELTA)
• Zapisuje soubory pack pro síťové operace
• Čte a zapisuje index/připravenou oblast (formáty v2, v3, v4)
• Čte a zapisuje odkazy (větve, štítky, HEAD, packed-refs, reftable)
• Počítá rozdíly ve sjednoceném formátu gitu (algoritmy Myers, Patience, Histogram a Minimal)
• Provádí trojcestná sloučení s detekcí konfliktů
• Prochází grafy commitů (log, předci, základní sloučení)
• Komunikuje protokolem Git chytrého HTTP (clone, fetch, push)
• Podporuje pracovní stromy, submoduly, stash, hooky a Git LFS

Co vyžaduje

• PHP 8.2 nebo novější
• Rozšíření zlib (vestavěné prakticky ve všech instalacích PHP)
• Rozšíření json
• Rozšíření mbstring (deklarované v composer.json, takže je Composer vyžaduje při instalaci)
• Rozšíření ctype (slouží k ověřování hashů objektů; povoleno ve většině sestavení PHP, ale není deklarováno v composer.json)

Základní operace s úložištěm nevyžadují binární soubor git. Volitelné funkce mohou potřebovat další možnosti běhového prostředí: spouštění hooků používá proc_open() a přenos SSH používá ext-ssh2, pokud je načteno, jinak spouští systémový binární soubor ssh přes proc_open().

Rychlý příklad

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

Začněte průvodcem Začínáme a poté pro zbývající části použijte API, CLI a Operace. V části Testování se dozvíte, jak se Pitmaster ověřuje vůči git.