Inleiding

Bekijken als Markdown Bewerken op GitHub Documentatie op bfe242f

Pitmaster is een zuivere PHP-bibliotheek die Git-repositories rechtstreeks leest en schrijft. Voor kernbewerkingen van de repository voert de bibliotheek geen shellopdracht uit met het binaire bestand git en gebruikt ze geen FFI. Het objectmodel Git, het pack-bestandsformaat, het indexformaat en het smart HTTP-transport zijn geïmplementeerd in PHP.

Waarom Pitmaster bestaat

PHP-applicaties die met Git-repositories werken, voeren doorgaans het binaire bestand git uit als shellopdracht. Dat werkt, maar maakt de installatie van git een harde vereiste, brengt beveiligingsrisico's met zich mee rond exec() en proc_open() en maakt de applicatie lastiger te implementeren in beperkte omgevingen (containers zonder git, shared hosting, serverless functies).

Pitmaster neemt de afhankelijkheid van git weg voor kernbewerkingen van de repository. Je PHP-applicatie kan commitgeschiedenis lezen, commits maken, diffs berekenen, de status controleren en naar remotes pushen via smart HTTP, met alleen de ingebouwde functies van PHP. Hooks en transport via SSH vormen de uitzonderingen: beide starten processen en kunnen per repositoryhandle worden uitgeschakeld (zie Hooks).

Wat het doet

Leest en schrijft losse objecten (blob, tree, commit, tag)
Leest pack-bestanden en lost delta-ketens op (OFS_DELTA en REF_DELTA)
Schrijft pack-bestanden voor netwerkbewerkingen
Leest en schrijft de index/staging area (formaten v2, v3, v4)
Leest en schrijft refs (branches, tags, HEAD, packed-refs, reftable)
Berekent diffs in het uniforme git-formaat (algoritmen Myers, Patience, Histogram en Minimal)
Voert three-way merges uit met conflictdetectie
Doorloopt commitgrafieken (log, afstamming, merge-basis)
Spreekt het protocol Git smart HTTP (clone, fetch, push)
Ondersteunt worktrees, submodules, stash, hooks en Git LFS

Wat het vereist

PHP 8.2 of hoger
Extensie zlib (ingebouwd in vrijwel alle PHP-installaties)
Extensie json
Extensie mbstring (gedeclareerd in composer.json, dus Composer vereist dit tijdens de installatie)
Extensie ctype (voor het valideren van objecthashes; ingeschakeld in de meeste PHP-builds, maar niet gedeclareerd in composer.json)

Voor kernbewerkingen van de repository is het binaire bestand git niet nodig. Optionele functies kunnen extra runtimevoorzieningen vereisen: hook-uitvoering gebruikt proc_open(), en voor SSH-transport wordt ext-ssh2 gebruikt als dit is geladen; anders wordt het systeem-binaire bestand ssh gestart via proc_open().

Snel voorbeeld

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

Begin met Aan de slag en raadpleeg daarna API, CLI en Bewerkingen voor de rest van de functionaliteit. In Testen lees je hoe Pitmaster wordt gecontroleerd aan de hand van git.