Introduction

Afficher au format Markdown Modifier sur GitHub Documentation de bfe242f

Pitmaster est une bibliothèque PHP pure qui lit et écrit nativement les dépôts Git. Les opérations principales sur les dépôts n’appellent pas le binaire git via le shell et n’utilisent pas FFI. Le modèle d’objets Git, le format des fichiers pack et index ainsi que le transport intelligent HTTP sont implémentés en PHP.

Pourquoi Pitmaster existe

Les applications PHP qui interagissent avec des dépôts Git appellent généralement le binaire git via le shell. Cette solution fonctionne, mais impose une dépendance à l’installation de git, soulève des problèmes de sécurité liés à exec() et proc_open(), et complique le déploiement de l’application dans des environnements restreints (conteneurs sans git, hébergement mutualisé, fonctions sans serveur).

Pitmaster supprime la dépendance à git pour les opérations principales sur les dépôts. Votre application PHP peut lire l’historique des commits, créer des commits, calculer des différences, vérifier l’état et envoyer des modifications vers des dépôts distants via HTTP intelligent, en utilisant uniquement les fonctions intégrées de PHP. Les hooks et le transport SSH font exception : tous deux lancent des processus et peuvent être désactivés pour chaque handle de dépôt (voir Hooks).

Fonctionnalités

Lit et écrit les objets libres (blob, tree, commit, tag)
Lit les fichiers pack et résout les chaînes de deltas (OFS_DELTA et REF_DELTA)
Écrit des fichiers pack pour les opérations réseau
Lit et écrit l’index/la zone de préparation (formats v2, v3, v4)
Lit et écrit les références (branches, tags, HEAD, packed-refs, reftable)
Calcule les différences (algorithmes Myers, Patience, Histogram et Minimal) au format unifié de git
Effectue des fusions à trois voies avec détection des conflits
Parcourt les graphes de commits (journal, ascendance, base de fusion)
Prend en charge le protocole intelligent Git HTTP (clone, récupération, envoi)
Prend en charge les arbres de travail, les sous-modules, stash, les hooks et Git LFS

Prérequis

PHP 8.2 ou version ultérieure
Extension zlib (intégrée à pratiquement toutes les installations PHP)
Extension json
Extension mbstring (déclarée dans composer.json, donc Composer en a besoin au moment de l’installation)
Extension ctype (utilisée pour valider les hachages d’objets ; activée dans la plupart des compilations PHP, mais non déclarée dans composer.json)

Les opérations principales sur les dépôts ne nécessitent pas le binaire git. Les fonctionnalités facultatives peuvent nécessiter des capacités d’exécution supplémentaires : l’exécution des hooks utilise proc_open(), et le transport SSH utilise ext-ssh2 si cette extension est chargée ; sinon, il lance le binaire système ssh via proc_open().

Exemple rapide

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

Commencez par Bien démarrer, puis consultez API, CLI et Opérations pour découvrir le reste des fonctionnalités. Tests explique comment Pitmaster est vérifié par rapport à git.