Úvod

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na bfe242f

Pitmaster je čisto implementovaná knižnica PHP, ktorá natívne číta a zapisuje repozitáre Git. Základné operácie s repozitárom nespúšťajú cez shell binárny súbor git ani nepoužívajú FFI. Objektový model Git, formát súboru balíka, formát indexu a inteligentný prenos HTTP sú implementované v PHP.

Prečo existuje Pitmaster

Aplikácie PHP, ktoré pracujú s repozitármi Git, zvyčajne spúšťajú binárny súbor git cez shell. Funguje to, ale vytvára pevnú závislosť od nainštalovaného git, prináša bezpečnostné riziká súvisiace s exec() a proc_open() a sťažuje nasadenie aplikácie v obmedzených prostrediach (kontajnery bez git, zdieľaný hosting, bezserverové funkcie).

Pitmaster odstraňuje závislosť od git pri základnej práci s repozitárom. Vaša aplikácia PHP môže čítať históriu odovzdaní, vytvárať odovzdania, počítať rozdiely, kontrolovať stav a odosielať zmeny do vzdialených repozitárov cez inteligentný HTTP iba pomocou vstavaných funkcií PHP. Výnimkou sú hooky a prenos SSH: oba spúšťajú procesy a oba možno vypnúť pre konkrétny objekt repozitára (pozrite si Hooky).

Čo dokáže

Číta a zapisuje voľné objekty (blob, strom, odovzdanie, značka)
Číta súbory balíkov a rieši reťazce delta (OFS_DELTA a REF_DELTA)
Zapisuje súbory balíkov pre sieťové operácie
Číta a zapisuje index/pracovnú oblasť prípravy (formáty v2, v3, v4)
Číta a zapisuje odkazy (vetvy, značky, HEAD, packed-refs, reftable)
Počíta rozdiely (algoritmy Myers, Patience, Histogram a Minimal) v zjednotenom formáte git
Vykonáva trojcestné zlučovania s detekciou konfliktov
Prechádza grafy odovzdaní (záznam, pôvodnosť, základ zlúčenia)
Podporuje inteligentný protokol Git HTTP (klonovanie, načítanie, odosielanie)
Podporuje pracovné stromy, submoduly, odložené zmeny, hooky a Git LFS

Čo vyžaduje

PHP 8.2 alebo novší
Rozšírenie zlib (vstavané prakticky vo všetkých inštaláciách PHP)
Rozšírenie json
Rozšírenie mbstring (deklarované v composer.json, takže Composer ho vyžaduje pri inštalácii)
Rozšírenie ctype (používa sa na overovanie hashov objektov; povolené vo väčšine zostavení PHP, no nie je deklarované v composer.json)

Základné operácie s repozitárom nevyžadujú binárny súbor git. Voliteľné funkcie môžu vyžadovať ďalšie možnosti behu: spúšťanie hookov používa proc_open() a prenos SSH používa ext-ssh2, keď je načítané, inak spustí systémový binárny súbor ssh prostredníctvom proc_open().

Rýchly príklad

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

Začnite stránkou Začíname a potom si pozrite API, CLI a Operácie, kde nájdete opis zvyšku funkcií. Vysvetlenie, ako sa Pitmaster overuje voči git, nájdete na stránke Testovanie.