Primeros pasos

Instalación

Instale Pitmaster mediante Composer:

composer require pitmaster/pitmaster

Requisitos

• PHP 8.2+ con clases de solo lectura, enumeraciones y promoción de constructores
• ext-zlib para comprimir y descomprimir objetos (incluida en la mayoría de las instalaciones)
• ext-json para archivos de estado de operaciones y cargas útiles Git LFS API
• ext-mbstring, declarada en composer.json, por lo que Composer la requiere durante la instalación
• ext-ctype para validar hashes (habilitada en la mayoría de las compilaciones de PHP, pero no declarada en composer.json)

Las operaciones principales del repositorio no requieren el binario git, FFI ni herramientas externas. Las funciones opcionales tienen requisitos adicionales en tiempo 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().

Abrir un repositorio existente

use Pitmaster\Pitmaster;

$repo = Pitmaster::open('/path/to/project');

Esto abre el repositorio en la ruta indicada. Pitmaster localiza el directorio .git (o resuelve un archivo .git en el caso de worktrees vinculados) e inicializa la base de datos de objetos, la base de datos de refs y la configuración.

open(), init() y clone() aceptan un arreglo de opciones como último argumento:

// Do not run .git/hooks scripts for this handle
$repo = Pitmaster::open('/path/to/project', ['hooks' => false]);

// Do not start any process: no hooks, no fsmonitor hook, no clone/fetch/push, no SSH
$repo = Pitmaster::open('/path/to/project', Pitmaster::processFreeOptions());

Los hooks se ejecutan de forma predeterminada. Pitmaster::processFreeOptions() devuelve ['processes' => false, 'hooks' => false]; las lecturas y escrituras locales siguen funcionando con ese identificador.

Comprobar si una ruta es un repositorio

if (Pitmaster::isRepository('/path/to/project')) {
    $repo = Pitmaster::open('/path/to/project');
}

Inicializar un repositorio nuevo

$repo = Pitmaster::init('/path/to/new-project');

Esto crea la estructura de directorios .git con objetos, refs, HEAD (que apunta a refs/heads/main) y una configuración predeterminada.

Para crear un repositorio SHA-256, pase el formato de objeto como segundo argumento:

$repo = Pitmaster::init('/path/to/new-project', 'sha256');

Los ID de objeto de ese repositorio tienen 64 caracteres hexadecimales, y la configuración registra extensions.objectformat = sha256. Los repositorios abiertos más adelante obtienen el formato de esa entrada de configuración.

Leer el commit de HEAD

$head = $repo->head();

echo "Commit: {$head->id->hex}\n";
echo "Author: {$head->author}\n";
echo "Message: {$head->message}\n";

El método head() resuelve HEAD (siguiendo refs simbólicas) y devuelve un objeto Commit.

Listar ramas y etiquetas

// All branch names
$branches = $repo->branches();
// ['main', 'feature/login', 'bugfix/typo']

// Current branch name (null if detached)
$current = $repo->branch();
// 'main'

// All tag names
$tags = $repo->tags();
// ['v1.0.0', 'v1.1.0']

Recorrer el historial de commits

// Last 20 commits from HEAD
$commits = $repo->log(20);

foreach ($commits as $commit) {
    echo substr($commit->id->hex, 0, 7) . " {$commit->message}\n";
}

También puede empezar desde un commit específico:

$from = $repo->resolve('feature/login');
$commits = $repo->log(10, $from);

Comprobar el estado del árbol de trabajo

use Pitmaster\Status\FileStatus;

$entries = $repo->status();

foreach ($entries as $entry) {
    if ($entry->index === FileStatus::Untracked) {
        echo "?? {$entry->path}\n";
    } elseif ($entry->index === FileStatus::Modified) {
        echo "M  {$entry->path}\n";
    } elseif ($entry->worktree === FileStatus::Modified) {
        echo " M {$entry->path}\n";
    }
}

Preparar archivos y crear un commit

// Stage specific files
$repo->add('src/Feature.php', 'tests/FeatureTest.php');

// Create a commit
$commitId = $repo->commit('Add new feature with tests');

echo "Created commit: {$commitId->hex}\n";

El nombre y el correo electrónico del autor se resuelven en este orden: las variables de entorno PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, las variables de entorno GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL, las constantes PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, la .git/config propia del repositorio (user.name y user.email) y, por último, Pitmaster <pitmaster@localhost>. Solo se lee el archivo de configuración del repositorio (y los archivos que incluye), no ~/.gitconfig. El committer se resuelve del mismo modo a partir de los nombres *_COMMITTER_* y, si no se encuentran, usa las constantes del autor.

Calcular diferencias

// Unstaged changes (worktree vs index)
$diffs = $repo->diff();

foreach ($diffs as $diff) {
    echo $diff->format(); // Unified diff output
}

// Staged changes (index vs HEAD)
$staged = $repo->diffStaged();

Clonar un repositorio remoto

$repo = Pitmaster::clone('https://github.com/user/repo.git', '/path/to/destination');

Esto descubre las referencias, obtiene el archivo del paquete, configura las ramas de seguimiento remoto y cambia a la rama predeterminada. HTTP(S) Las URL usan HTTP inteligente y recurren a HTTP simple; las URL SSH usan el transporte SSH. Pase la profundidad como tercer argumento para un clon superficial: Pitmaster::clone($url, $path, 1).

Leer cualquier objeto por su hash

$object = $repo->readObject($fullHash); // full 40-character (or 64 for SHA-256) hex hash

if ($object instanceof \Pitmaster\Object\Blob) {
    echo $object->content;
} elseif ($object instanceof \Pitmaster\Object\Commit) {
    echo $object->message;
}

Configuración

Pitmaster respeta .git/config del repositorio para la información del autor y las URL remotas. También puede establecer valores predeterminados globales con las constantes PHP, definidas antes de que se ejecute Pitmaster:

define('PITMASTER_AUTHOR_NAME', 'Your Name');
define('PITMASTER_AUTHOR_EMAIL', 'you@example.com');
define('PITMASTER_HTTP_TIMEOUT', 60);        // Seconds
define('PITMASTER_MAX_DELTA_CHAIN', 50);     // Max delta chain depth
define('PITMASTER_OBJECT_CACHE_BYTES', '64M');

Los valores de bytes aceptan un entero o una cadena con el sufijo k, m o g ('256M'). Los valores no válidos usan el valor predeterminado.

Las variables de entorno prevalecen sobre las constantes de identidad: PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, sus equivalentes PITMASTER_COMMITTER_* y las variables propias de git GIT_AUTHOR_* y GIT_COMMITTER_*. El transporte SSH lee las variables PITMASTER_SSH_*, descritas en Protocolos.

No hay ninguna constante para el algoritmo de hash. El formato de objetos se elige al crear el repositorio (Pitmaster::init($path, 'sha256') o init --object-format=sha256 en CLI) y luego se lee de la configuración del repositorio.