Saltar al contenido

Introducción

Ver como Markdown Editar en GitHub Documentación de bfe242f

Pitmaster es una biblioteca pura de PHP que lee y escribe repositorios Git de forma nativa. Las operaciones principales del repositorio no ejecutan el binario git ni usan FFI. El modelo de objetos Git, el formato de archivos de paquete, el formato del índice y el transporte HTTP inteligente están implementados en PHP.

Por qué existe Pitmaster

Las aplicaciones PHP que interactúan con repositorios Git suelen ejecutar el binario git desde la shell. Esto funciona, pero crea una dependencia estricta de que git esté instalado, introduce riesgos de seguridad relacionados con exec() y proc_open() y dificulta la implementación de la aplicación en entornos restringidos (contenedores sin git, alojamiento compartido y funciones sin servidor).

Pitmaster elimina la dependencia de git para las operaciones principales del repositorio. Su aplicación PHP puede leer el historial de confirmaciones, crear confirmaciones, calcular diferencias, consultar el estado y enviar cambios a repositorios remotos mediante HTTP inteligente, usando solo las funciones integradas de PHP. Los hooks y el transporte SSH son las excepciones: ambos inician procesos y se pueden desactivar por cada identificador de repositorio (consulte Hooks).

Qué hace

  • Lee y escribe objetos sueltos (blob, tree, commit, tag)
  • Lee archivos de paquete y resuelve cadenas delta (OFS_DELTA y REF_DELTA)
  • Escribe archivos de paquete para operaciones de red
  • Lee y escribe el índice/área de preparación (formatos v2, v3, v4)
  • Lee y escribe referencias (ramas, etiquetas, HEAD, packed-refs, reftable)
  • Calcula diferencias (algoritmos Myers, Patience, Histogram y Minimal) en el formato unificado de git
  • Realiza fusiones de tres vías con detección de conflictos
  • Recorre grafos de confirmaciones (registro, ascendencia, base de fusión)
  • Usa el protocolo Git HTTP inteligente (clonación, obtención y envío)
  • Admite árboles de trabajo, submódulos, stash, hooks y Git LFS

Requisitos

  • PHP 8.2 o posterior
  • Extensión zlib (integrada en prácticamente todas las instalaciones de PHP)
  • Extensión json
  • Extensión mbstring (declarada en composer.json, por lo que Composer la requiere durante la instalación)
  • Extensión ctype (se usa para validar hashes de objetos; está habilitada en la mayoría de las compilaciones de PHP, pero no está declarada en composer.json)

Las operaciones principales del repositorio no requieren el binario git. Las funciones opcionales pueden necesitar capacidades adicionales del entorno de ejecución: la ejecución de hooks usa proc_open() y el transporte SSH usa ext-ssh2 cuando está cargado; de lo contrario, inicia el binario ssh del sistema mediante proc_open().

Ejemplo rápido

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

Empiece por Introducción y luego consulte API, CLI y Operaciones para conocer el resto de las funciones. Pruebas explica cómo se comprueba Pitmaster frente a git.