Vai al contenuto

Introduzione

Visualizza come Markdown Modifica su GitHub Documentazione di bfe242f

Pitmaster è una libreria pura di PHP che legge e scrive nativamente repository Git. Le operazioni fondamentali sui repository non invocano il binario git dalla shell né usano FFI. Il modello degli oggetti Git, il formato dei file pack, il formato dell'indice e il trasporto HTTP intelligente sono implementati in PHP.

Perché esiste Pitmaster

Le applicazioni PHP che interagiscono con repository Git in genere invocano il binario git dalla shell. Funziona, ma crea una dipendenza obbligatoria dall'installazione di git, introduce problemi di sicurezza legati a exec() e proc_open() e rende più difficile distribuire l'applicazione in ambienti con restrizioni (container senza git, hosting condiviso, funzioni serverless).

Pitmaster elimina la dipendenza da git per le operazioni fondamentali sui repository. La vostra applicazione PHP può leggere la cronologia dei commit, crearne di nuovi, calcolare differenze, controllare lo stato e inviare modifiche ai repository remoti tramite HTTP intelligente, usando solo le funzioni integrate di PHP. Gli hook e il trasporto SSH fanno eccezione: entrambi avviano processi e possono essere disattivati per singolo handle del repository (vedere Hook).

Cosa fa

  • Legge e scrive oggetti sciolti (blob, tree, commit, tag)
  • Legge i file pack e risolve le catene delta (OFS_DELTA e REF_DELTA)
  • Scrive file pack per le operazioni di rete
  • Legge e scrive l'indice e l'area di staging (formati v2, v3, v4)
  • Legge e scrive riferimenti (rami, tag, HEAD, packed-refs, reftable)
  • Calcola le differenze nel formato unificato di git (con gli algoritmi Myers, Patience, Histogram e Minimal)
  • Esegue merge a tre vie rilevando i conflitti
  • Esplora i grafi dei commit (log, discendenza, base comune di merge)
  • Comunica tramite il protocollo Git HTTP intelligente (clone, fetch, push)
  • Supporta worktree, sottomoduli, stash, hook e Git LFS

Requisiti

  • PHP 8.2 o successivo
  • Estensione zlib (integrata praticamente in tutte le installazioni PHP)
  • Estensione json
  • Estensione mbstring (dichiarata in composer.json, quindi Composer la richiede al momento dell'installazione)
  • Estensione ctype (usata per convalidare gli hash degli oggetti; abilitata nella maggior parte delle build PHP, ma non dichiarata in composer.json)

Le operazioni fondamentali sui repository non richiedono il binario git. Le funzionalità opzionali possono richiedere capacità di runtime aggiuntive: l'esecuzione degli hook usa proc_open(), mentre il trasporto SSH usa ext-ssh2 se caricato; altrimenti avvia il binario ssh di sistema tramite proc_open().

Esempio rapido

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

Iniziate con Guida introduttiva, poi consultate API, CLI e Operazioni per il resto delle funzionalità. Test spiega come Pitmaster viene verificato rispetto a git.