Gå til indhold

Introduktion

Vis som Markdown Rediger på GitHub Dokumentation hos bfe242f

Pitmaster er et rent PHP-bibliotek, der læser og skriver Git-repositories direkte. Kernehandlinger i repositoryet kalder ikke det binære git via skallen og bruger ikke FFI. Git-objektmodellen, pack-filformatet, indeksformatet og smart-transport over HTTP er implementeret i PHP.

Hvorfor Pitmaster findes

PHP-applikationer, der arbejder med Git-repositories, kalder typisk det binære git via skallen. Det fungerer, men skaber en hård afhængighed af, at git er installeret, giver sikkerhedsproblemer med exec() og proc_open() og gør applikationen sværere at udrulle i begrænsede miljøer (containere uden git, delt hosting, serverløse funktioner).

Pitmaster fjerner afhængigheden af git ved kernearbejde med repositories. Din PHP-applikation kan læse commit-historik, oprette commits, beregne diffs, kontrollere status og pushe til eksterne repositories over smart HTTP ved kun at bruge PHPs indbyggede funktioner. Hooks og transport over SSH er undtagelserne: begge starter processer, og begge kan slås fra pr. repository-handle (se Hooks).

Funktioner

  • Læser og skriver løse objekter (blob, tree, commit, tag)
  • Læser pack-filer og opløser deltakedener (OFS_DELTA og REF_DELTA)
  • Skriver pack-filer til netværkshandlinger
  • Læser og skriver indekset/staging-området (formaterne v2, v3, v4)
  • Læser og skriver refs (branches, tags, HEAD, packed-refs, reftable)
  • Beregner diffs (algoritmerne Myers, Patience, Histogram og Minimal) i git's unified-format
  • Udfører trevejsfletninger med konfliktdetektion
  • Gennemgår commit-grafer (log, ancestry, merge-base)
  • Taler smart-protokollen Git over HTTP (clone, fetch, push)
  • Understøtter worktrees, undermoduler, stash, hooks og Git LFS

Krav

  • PHP 8.2 eller nyere
  • Udvidelsen zlib (indbygget i stort set alle PHP-installationer)
  • Udvidelsen json
  • Udvidelsen mbstring (deklareret i composer.json, så Composer kræver den ved installation)
  • Udvidelsen ctype (bruges til at validere objekt-hashes; aktiveret i de fleste PHP-builds, men ikke deklareret i composer.json)

Kernehandlinger i repositoryet kræver ikke det binære git. Valgfrie funktioner kan kræve yderligere funktioner ved kørsel: hook-afvikling bruger proc_open(), og transport over SSH bruger ext-ssh2, når den er indlæst, og starter ellers systemets binære ssh via proc_open().

Hurtigt eksempel

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

Begynd med Kom godt i gang, og brug derefter API, CLI og Handlinger til resten af funktionerne. Test forklarer, hvordan Pitmaster kontrolleres mod git.