Saltar al contenido

PHP API

Ver como Markdown Editar en GitHub Documentación de bfe242f

Pitmaster\Pitmaster

La clase Pitmaster\Pitmaster es el punto de entrada estático. Proporciona métodos de fábrica para abrir, crear y clonar repositorios, además de funciones auxiliares de detección.

PHP
use Pitmaster\Pitmaster;

open

PHP
public static function open(string $path, array $options = []): Repository

Abra un repositorio existente en $path. La ruta debe ser la raíz del árbol de trabajo (que contiene .git/). También admite worktrees vinculados (donde .git es un archivo que contiene gitdir: <path>) y repositorios bare (donde $path es el propio directorio .git).

$options acepta dos valores booleanos, ambos true de forma predeterminada:

  • hooks: ejecuta scripts .git/hooks. Pase false para omitirlos en este controlador.
  • processes: permite cualquier acción que inicie un proceso o abra un transporte de red. Pase false para desactivar los hooks, el hook fsmonitor, clone, fetch, push y el transporte de procesos SSH. Las lecturas y escrituras locales siguen funcionando.

Lanza InvalidArgumentException si la ruta no es un repositorio git.

PHP
$repo = Pitmaster::open('/home/user/project');
$repo = Pitmaster::open('/home/user/project', ['hooks' => false]);
$repo = Pitmaster::open('/home/user/project', Pitmaster::processFreeOptions());

init

PHP
public static function init(string $path, string $objectFormat = 'sha1', array $options = []): Repository

Inicialice un repositorio nuevo en $path. Crea la estructura de directorios .git con objects/, refs/heads/, refs/tags/, hooks/, info/, HEAD (que apunta a refs/heads/main) y un config predeterminado.

$objectFormat es 'sha1' o 'sha256'. Un repositorio SHA-256 obtiene repositoryformatversion = 1 y extensions.objectformat = sha256 en su configuración. Cualquier otro valor lanza InvalidArgumentException. $options acepta las mismas claves que open().

Lanza RuntimeException si ya existe un repositorio en la ruta.

PHP
$repo = Pitmaster::init('/home/user/new-project');
$repo = Pitmaster::init('/home/user/sha256-project', 'sha256');

clone

PHP
public static function clone(string $url, string $path, ?int $depth = null, array $options = []): Repository

Clone un repositorio remoto. Inicializa un repositorio nuevo, descubre las referencias remotas, descarga el archivo pack, configura las ramas de seguimiento remoto y materializa el árbol de trabajo. Las URL SSH (ssh://... o user@host:path) usan el transporte SSH; las demás URL usan HTTP inteligente y recurren a HTTP simple cuando falla el intercambio inteligente. Pase $depth para un clon superficial.

Lanza RuntimeException cuando $options['processes'] sea false. Si el clon falla y $path no existía antes, se elimina el directorio creado parcialmente.

PHP
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/repo');
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/shallow', 1);
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/repo', null, ['hooks' => false]);

processFreeOptions

PHP
public static function processFreeOptions(): array

Devuelve ['processes' => false, 'hooks' => false] para entornos de ejecución que no deben iniciar procesos del host. Páselo a open() o init().

isRepository

PHP
public static function isRepository(string $path): bool

Comprueba si una ruta es un repositorio git. Devuelve true para repositorios normales (directorio .git/), worktrees vinculados (archivo .git) y repositorios bare (si existe el archivo HEAD).

PHP
if (Pitmaster::isRepository('/path/to/check')) {
    // It's a git repo
}

isWorktree

PHP
public static function isWorktree(string $path): bool

Comprueba si una ruta es un worktree vinculado (no el repositorio principal). Devuelve true solo si .git es un archivo que contiene una referencia gitdir:.

PHP
if (Pitmaster::isWorktree('/path/to/worktree')) {
    // It's a linked worktree
}

commonGitDir

PHP
public static function commonGitDir(string $path): ?string

Resuelve el directorio git común a partir de cualquier ruta de checkout. En repositorios normales, es el directorio .git. En worktrees vinculados, es el directorio git compartido que contiene objetos, configuración y packed-refs. Devuelve null si la ruta no es un repositorio.

PHP
$common = Pitmaster::commonGitDir('/path/to/worktree');
// '/path/to/main-repo/.git'

Pitmaster\Repository

La clase Pitmaster\Repository es el controlador principal para todas las operaciones de git. Obtenga una instancia mediante Pitmaster::open(), Pitmaster::init() o Pitmaster::clone().

PHP
use Pitmaster\Repository;

Acceso a rutas

gitDir

PHP
public function gitDir(): string

Devuelve el directorio git de cada worktree. En repositorios normales, es .git/. En worktrees vinculados, es .git/worktrees/<name>/.

commonGitDir

PHP
public function commonGitDir(): string

Devuelve el directorio git compartido. En repositorios normales, es igual que gitDir(). En worktrees vinculados, es el directorio .git/ del repositorio principal (donde se encuentran los objetos, la configuración y packed-refs).

workDir

PHP
public function workDir(): string

Devuelve la ruta raíz del árbol de trabajo.

isLinkedWorktree

PHP
public function isLinkedWorktree(): bool

Devuelve true si este controlador de repositorio es un worktree vinculado.

isBare, hooksEnabled, processesEnabled

PHP
public function isBare(): bool
public function hooksEnabled(): bool
public function processesEnabled(): bool

Indica si el repositorio carece de árbol de trabajo y cuáles opciones de hooks / processes están activas para este controlador. hooksEnabled() es false siempre que los procesos estén desactivados.

Objetos

readObject

PHP
public function readObject(string $hash): GitObject

Lee cualquier objeto mediante su hash hexadecimal completo (40 caracteres, o 64 en un repositorio SHA-256). No se aceptan hashes abreviados. Devuelve una instancia Blob, Tree, Commit o Tag. Busca primero en los objetos sueltos y luego en los archivos pack.

Lanza ObjectNotFoundException si no se encuentra el hash.

PHP
$object = $repo->readObject('a1b2c3d4e5f6...');

writeObject

PHP
public function writeObject(GitObject $object): ObjectId

Escribe un objeto en el almacén de objetos sueltos. Devuelve el ObjectId calculado.

PHP
use Pitmaster\Object\Blob;

$blob = Blob::fromContent('Hello, world!');
$id = $repo->writeObject($blob);

catFile

PHP
public function catFile(string $hash): string

Devuelve el contenido sin procesar de un objeto, equivalente a git cat-file -p.

PHP
echo $repo->catFile('a1b2c3d4...');

objectExists

PHP
public function objectExists(string $hash): bool

Comprueba si existe un objeto en el repositorio (suelto o empaquetado).

listObjects

PHP
public function listObjects(): array

Enumera todos los hashes de objetos del repositorio. Devuelve un array de cadenas hexadecimales.

Referencias

PHP
public function head(): Commit

Devuelve el commit HEAD actual. Sigue las referencias simbólicas (HEAD -> refs/heads/main -> hash del commit).

Lanza RuntimeException si HEAD no apunta a un commit válido (e.g., repositorio vacío).

branch

PHP
public function branch(?string $name = null): ?string

Sin argumentos, devuelve el nombre de la rama actual (e.g., 'main') o null si HEAD está separado de una rama.

Con un nombre de rama, lo resuelve a su hash de commit (cadena hexadecimal) o devuelve null si la rama no existe.

PHP
$current = $repo->branch();        // 'main'
$hash = $repo->branch('feature');   // 'abc123...' or null

branches

PHP
public function branches(): array

Devuelve un array ordenado de todos los nombres de rama (sin el prefijo refs/heads/).

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

tags

PHP
public function tags(): array

Devuelve un array ordenado de todos los nombres de etiqueta (sin el prefijo refs/tags/).

resolve

PHP
public function resolve(string $revision): ObjectId

Resuelve una expresión de revisión a un ObjectId. Admite:

  • Hashes hexadecimales completos (40 caracteres, o 64 para SHA-256). No resuelve hashes abreviados como abc1234.
  • HEAD
  • Nombres de rama (main, feature/login)
  • Nombres de etiqueta (v1.0.0)
  • Rutas completas de referencia (refs/heads/main)
  • Expresiones de revisión (HEAD~3, main^2)

Lanza RuntimeException si no se puede resolver la revisión.

PHP
$id = $repo->resolve('HEAD~3');
$id = $repo->resolve('v1.0.0');
$id = $repo->resolve('feature/login');

allRefs

PHP
public function allRefs(): array

Devuelve todas las referencias en un array asociativo de nombres de referencia a hashes hexadecimales.

PHP
$refs = $repo->allRefs();
// ['refs/heads/main' => 'abc123...', 'refs/tags/v1.0.0' => 'def456...']

updateRef

PHP
public function updateRef(string $name, ObjectId $target): void

Actualiza una referencia para que apunte a un destino nuevo.

PHP
$repo->updateRef('refs/heads/main', $commitId);

createBranch

PHP
public function createBranch(string $name, ?ObjectId $from = null): void

Crea una rama nueva. Si $from es null, crea la rama desde el HEAD actual.

PHP
$repo->createBranch('feature/new-thing');
$repo->createBranch('hotfix', $repo->resolve('v1.0.0'));

deleteBranch

PHP
public function deleteBranch(string $name): void

Elimina una rama por nombre. Lanza RuntimeException si la rama tiene checkout o no existe. A diferencia de git branch -d, no comprueba si la rama se ha fusionado.

PHP
$repo->deleteBranch('feature/old');

createLightweightTag

PHP
public function createLightweightTag(string $name, ?ObjectId $target = null): void

Crea una etiqueta ligera. Si $target es null, etiqueta directamente el HEAD actual.

PHP
$repo->createLightweightTag('v2.0.0');
$repo->createLightweightTag('hotfix-start', $repo->resolve('main~2'));

createTag

PHP
public function createTag(string $name, string $message, ?ObjectId $target = null, ?string $tagger = null): ObjectId

Crea una etiqueta anotada. Si $target es null, etiqueta el HEAD actual. Devuelve el ObjectId del objeto de etiqueta.

PHP
$tagId = $repo->createTag('v2.0.0', 'Release version 2.0.0');

deleteTag

PHP
public function deleteTag(string $name): void

Elimina una etiqueta por nombre.

PHP
$repo->deleteTag('v1.0.0');

packRefs

PHP
public function packRefs(): void

Reescribe el archivo packed-refs compartido a partir del conjunto actual de referencias sueltas y elimina las referencias sueltas compartidas correspondientes. En worktrees vinculados, escribe en el directorio git común.

PHP
$repo->packRefs();

defaultBranch

PHP
public function defaultBranch(): string

Resuelve la rama predeterminada del repositorio. Comprueba primero la referencia simbólica HEAD remota, luego el HEAD local y, por último, recurre a main o master.

isBranchMerged

PHP
public function isBranchMerged(string $branch, ?string $target = null): bool

Comprueba si una rama se ha fusionado por completo con otra (de forma predeterminada, con la rama predeterminada).

PHP
if ($repo->isBranchMerged('feature/done')) {
    $repo->deleteBranch('feature/done');
}

checkout

PHP
public function checkout(string $target): void

Cambia de rama o separa HEAD de una rama. Actualiza HEAD, el índice y el árbol de trabajo. $target puede ser un nombre de rama, una etiqueta, un hash completo o una expresión de revisión; si no es una rama, HEAD queda separado.

Lanza RuntimeException cuando un cambio local (preparado o no) o un archivo sin seguimiento se encuentre en una ruta que difiera entre el árbol actual y el de destino.

Los cambios sin commit en otros archivos con seguimiento no se conservan: se reconstruyen el índice y el árbol de trabajo a partir del árbol de destino, por lo que se pierden las modificaciones en archivos idénticos en ambos lados, que git conservaría (#2). Haga commit de esos cambios o guárdelos en stash primero. merge(), cherryPick(), revert(), rebase() y los métodos de bisect reconstruyen el árbol de trabajo del mismo modo.

PHP
$repo->checkout('feature/login');
$repo->checkout($repo->resolve('v1.0.0')->hex);  // Detached HEAD

Índice

index

PHP
public function index(): Index

Lee y devuelve el índice actual (área de preparación) desde .git/index.

add

PHP
public function add(string ...$paths): void

Prepara archivos. Lee cada archivo del árbol de trabajo, crea un objeto blob y actualiza el índice. Cada argumento debe ser la ruta de un archivo (o enlace simbólico) relativa a la raíz del árbol de trabajo; no se expanden directorios ni patrones glob, y si falta un archivo se lanza RuntimeException.

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

remove

PHP
public function remove(string ...$paths): void
public function removeCached(string ...$paths): void

Elimina rutas con seguimiento tanto del índice como del árbol de trabajo. Admite --cached y -r / --recursive en la lista de argumentos para un comportamiento similar a Git.

PHP
$repo->remove('old-file.txt');
$repo->remove('-r', 'src');
$repo->remove('--cached', 'old-file.txt');
$repo->removeCached('old-file.txt');

mv

PHP
public function mv(string $source, string $destination): void

Mueve o cambia el nombre de un archivo tanto en el árbol de trabajo como en el índice.

PHP
$repo->mv('old-name.php', 'new-name.php');

Commits

commit

PHP
public function commit(?string $message = null, ?string $author = null): ObjectId

Crea un commit a partir del índice actual. Construye una jerarquía de árboles a partir de las entradas del índice, crea el objeto commit con HEAD como padre (si lo hay) y actualiza HEAD. Devuelve el ObjectId del nuevo commit.

$message solo puede ser null cuando una fusión, selección de commit, reversión o reorganización se detiene por un conflicto; en ese caso, se usa el mensaje preparado. De lo contrario, un mensaje null lanza RuntimeException('Commit message required'). También se lanza una excepción si el índice tiene rutas sin fusionar, si está vacío en un repositorio sin commits o si el árbol no ha cambiado con respecto a HEAD.

El parámetro $author es una cadena completa de autor de git (Name <email> timestamp timezone). Si es null, se resuelve a partir de las variables de entorno, las constantes y .git/config, en el orden descrito en Introducción.

PHP
$id = $repo->commit('Fix null pointer bug');

show

PHP
public function show(string $revision): array

Muestra un commit o referencia similar y sus diferencias con respecto al primer padre. Cuando la revisión se resuelve en una etiqueta anotada, el valor devuelto también incluye ['tag' => Tag] y commit es el commit de destino de la etiqueta.

PHP
$result = $repo->show('HEAD');
echo $result['commit']->message;

foreach ($result['diff'] as $diff) {
    echo $diff->format();
}

reset

PHP
public function reset(string $revision, string $mode = 'mixed'): void

Restablece HEAD a un commit. Modos:

  • 'soft': mueve solo HEAD
  • 'mixed': mueve HEAD y restablece el índice (predeterminado)
  • 'hard': mueve HEAD, restablece el índice y restablece el árbol de trabajo
PHP
$repo->reset('HEAD~1', 'soft');
$repo->reset('main', 'hard');

restore

PHP
public function restore(string $path, ?string $source = null, bool $staged = false, bool $worktree = false): void

Restaura una ruta desde el índice o desde una revisión de origen específica. Si no se activa ninguno de los indicadores, Pitmaster restaura el árbol de trabajo desde el índice (o desde $source si se indica). staged: true restaura el índice desde HEAD (o desde $source) y deja intacto el árbol de trabajo; pase staged: true, worktree: true para restaurar ambos.

PHP
$repo->restore('src/File.php');                                        // Worktree from index
$repo->restore('src/File.php', staged: true);                          // Index from HEAD
$repo->restore('src/File.php', 'HEAD~1');                              // Worktree from another commit
$repo->restore('src/File.php', 'HEAD~1', staged: true, worktree: true); // Index + worktree from another commit

cherryPick

PHP
public function cherryPick(string $revision): ObjectId
public function cherryPickContinue(): ObjectId
public function cherryPickAbort(): void

Aplica un commit como un commit nuevo en la rama actual y conserva el autor original. Si la operación se detiene por conflictos, resuélvalos, prepare las rutas y luego llame a cherryPickContinue() o cherryPickAbort().

PHP
$newId = $repo->cherryPick('feature~2');

// After resolving conflicts:
$repo->add('src/File.php');
$repo->cherryPickContinue();

revert

PHP
public function revert(string $revision): ObjectId
public function revertContinue(): ObjectId
public function revertAbort(): void

Crea un commit que deshace otro commit. Si la reversión se detiene por conflictos, resuélvalos, prepare las rutas y luego llame a revertContinue() o revertAbort().

PHP
$revertId = $repo->revert('HEAD~1');

// After resolving conflicts:
$repo->add('src/File.php');
$repo->revertContinue();

rebase

PHP
public function rebase(string $onto): array
public function rebaseContinue(): array
public function rebaseAbort(): void
public function rebaseSkip(): array

Reorganiza la rama actual sobre otra revisión. Actualmente, Pitmaster admite reorganizaciones lineales con un estado de detención Git similar para los conflictos, además de continuar, abortar y omitir. HEAD debe apuntar a una rama.

rebase(), rebaseContinue() y rebaseSkip() devuelven ['success' => bool, 'commits' => int, 'conflicts' => list<string>]: si la reorganización terminó, cuántos commits se aplicaron y cuáles eran las rutas en conflicto cuando se detuvo.

PHP
$result = $repo->rebase('main');

if (!$result['success']) {
    // Resolve conflicts, then continue or skip/abort.
    $repo->add('src/File.php');
    $repo->rebaseContinue();
}

Estado

status

PHP
public function status(): array

Calcula el estado del árbol de trabajo. Devuelve un array de objetos StatusEntry, cada uno con:

  • path: la ruta del archivo
  • index: enumeración FileStatus de los cambios entre HEAD y el índice
  • worktree: enumeración FileStatus de los cambios entre el índice y el árbol de trabajo
  • origPath, renameScore: se establecen para las entradas renombradas; en los demás casos, null

Los archivos sin seguimiento tienen FileStatus::Untracked en ambas columnas. No se informan los archivos ignorados.

PHP
foreach ($repo->status() as $entry) {
    echo $entry->shortFormat() . "\n"; // "M  src/File.php", "?? notes.txt"
}

statusPorcelainV2

PHP
public function statusPorcelainV2(): string

Salida del estado legible por máquinas en el formato porcelain v2 de git.

PHP
echo $repo->statusPorcelainV2();
// 1 M. N... 000000 000000 000000 0000...0000 0000...0000 modified-file.txt
// ? untracked-file.txt

Diferencias

diff

PHP
public function diff(?string $pathspec = null, string $algorithm = 'myers'): array

Compara el árbol de trabajo con el índice (cambios sin preparar). Devuelve un array de objetos DiffResult. $pathspec filtra por una ruta de archivo exacta. $algorithm es 'myers' (predeterminado), 'patience', 'histogram' o 'minimal'; cualquier otro valor lanza InvalidArgumentException.

PHP
$diffs = $repo->diff();

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

diffStaged

PHP
public function diffStaged(?string $pathspec = null, string $algorithm = 'myers'): array

Compara el índice con HEAD (cambios preparados). Devuelve DiffResult[], con detección de cambios de nombre entre archivos eliminados y añadidos.

Actualmente se ignora el argumento $pathspec, por lo que se devuelven todos los archivos preparados. El método devuelve un array vacío antes del primer commit (#5).

PHP
$staged = $repo->diffStaged();

diffTree

PHP
public function diffTree(ObjectId $a, ObjectId $b, string $algorithm = 'myers'): array

Compara dos árboles mediante sus ObjectId. Devuelve DiffResult[]. Pase los ID de árbol, no los ID de commit: un ID de commit no se interpreta como árbol y produce un resultado vacío.

PHP
$old = $repo->readObject($repo->resolve('HEAD~1')->hex);
$new = $repo->head();
$diffs = $repo->diffTree($old->tree, $new->tree);

Registro

log

PHP
public function log(int $limit = 50, ?ObjectId $from = null): array

Recorre el historial de commits, del más reciente al más antiguo según la marca de tiempo del autor del commit. Devuelve Commit[]. Si $from es null, comienza desde HEAD. Devuelve un array vacío si HEAD aún no tiene un commit.

PHP
$commits = $repo->log(10);

logAll

PHP
public function logAll(int $limit = 50): array

Recorre los commits accesibles desde cada referencia y desde HEAD, del más reciente al más antiguo. Devuelve Commit[].

logOneline

PHP
public function logOneline(int $limit = 50, bool $all = false, ?string $path = null): array

Devuelve las líneas del registro en formato git log --oneline (abc1234 Subject), desde HEAD, desde todas las referencias ($all) o filtradas por ruta.

logPath

PHP
public function logPath(string $path, int $limit = 50): array

Filtra el registro por una ruta de archivo. Devuelve solo los commits cuya diferencia con el primer padre añade, modifica, elimina o renombra ese archivo exacto. Las rutas de directorio no coinciden.

Solo se examinan los 5 * $limit commits más recientes, por lo que el resultado puede omitir commits anteriores que afecten al archivo (#7).

PHP
$commits = $repo->logPath('src/Repository.php', 20);

Fusión

merge

PHP
public function merge(string $branch, string $strategy = 'recursive'): MergeResult
public function mergeOctopus(array $branches): MergeResult
public function mergeContinue(): ObjectId
public function mergeAbort(): void

Fusiona una rama (o cualquier revisión) en HEAD. Detecta automáticamente las fusiones de avance rápido. Para las demás fusiones, detecta conflictos a nivel de árbol y crea un commit de fusión si no hay conflictos. Si hay conflictos, la operación se detiene y escribe en el índice y el árbol de trabajo un estado de fusión similar a Git; resuelva las rutas, prepárelas y luego llame a mergeContinue() o mergeAbort().

$strategy 'ours' registra un commit de fusión que conserva el árbol de HEAD; cualquier otro valor utiliza la fusión recursiva predeterminada. mergeOctopus() fusiona dos o más ramas en un solo commit. Si alguna rama tiene conflictos, devuelve un resultado con conflictos sin escribir el estado de fusión ni crear un commit.

Al fusionar una rama que ya está incluida en HEAD se crea otro commit de fusión en lugar de indicar «Already up to date» (#6). Los cambios sin confirmar en archivos con seguimiento se sobrescriben, como se describe en checkout().

Devuelve un MergeResult con:

  • clean: si la fusión se completó sin conflictos
  • commitId: el ID del commit de fusión (si se completó sin conflictos)
  • conflictPaths: la lista de rutas de archivos en conflicto (si hubo conflictos)
  • mergedContents: la ruta en conflicto al contenido del archivo con marcadores de conflicto (si hubo conflictos)
PHP
$result = $repo->merge('feature/login');

if ($result->clean) {
    echo "Merged: {$result->commitId->hex}\n";
} else {
    echo "Conflicts in: " . implode(', ', $result->conflictPaths) . "\n";
    $repo->add('src/File.php');
    $repo->mergeContinue();
}

mergeBase

PHP
public function mergeBase(ObjectId $a, ObjectId $b): ?ObjectId

Busca la base de fusión (el ancestro común más bajo) de dos commits. Devuelve null si no existe ningún ancestro común.

PHP
$base = $repo->mergeBase(
    $repo->resolve('main'),
    $repo->resolve('feature/login'),
);

Búsqueda binaria

PHP
public function bisectStart(string $bad, string $good): ObjectId
public function bisectGood(?string $revision = null): ?ObjectId
public function bisectBad(?string $revision = null): ?ObjectId
public function bisectReset(): void

Busca mediante búsqueda binaria el commit que introdujo un cambio. bisectStart() registra las revisiones correctas e incorrectas, selecciona el primer candidato y lo devuelve. bisectGood() y bisectBad() marcan el HEAD actual (o $revision), seleccionan el siguiente candidato y lo devuelven. Cuando queda un solo sospechoso, se devuelve ese commit y sigue siendo el candidato: es el primer commit incorrecto. bisectReset() finaliza la sesión y vuelve a la rama o al commit donde comenzó.

PHP
$candidate = $repo->bisectStart('HEAD', 'v1.0.0');
// test $candidate ...
$candidate = $repo->bisectBad();
$candidate = $repo->bisectGood();
$repo->bisectReset();

Red

fetch

PHP
public function fetch(string $remote = 'origin', ?int $depth = null): void

Obtiene datos de un remoto. Descarga objetos nuevos y actualiza las referencias de seguimiento remoto. Pasa $depth para ampliar o limitar un historial superficial.

fetch() y los métodos push*() lanzan RuntimeException en un controlador abierto con ['processes' => false].

PHP
$repo->fetch();
$repo->fetch('upstream');

push

PHP
public function push(string $remote = 'origin', ?string $branch = null): void
public function pushForceWithLease(string $remote = 'origin', ?string $branch = null, ?ObjectId $expected = null): void
public function pushAtomic(string $remote = 'origin', array $branches = []): void
public function pushMirror(string $remote = 'origin'): void

Envía la rama actual (o una rama especificada) a un remoto. Hay variantes con force-with-lease, atómica y espejo para actualizar referencias de forma más estricta o amplia.

PHP
$repo->push();
$repo->push('origin', 'feature/login');
$repo->pushForceWithLease('origin', 'main', $repo->resolve('refs/remotes/origin/main'));
$repo->pushAtomic('origin', ['main', 'release']);
$repo->pushMirror();

Árboles de trabajo

addWorktree

PHP
public function addWorktree(string $path, string $branch, ?ObjectId $from = null, ?string $name = null): Worktree

Añade un árbol de trabajo vinculado. Crea la rama si no existe, configura los metadatos del árbol de trabajo y materializa los archivos del árbol. Pasa $name cuando necesites un identificador de metadatos determinista distinto del nombre base del directorio de la copia de trabajo.

PHP
$wt = $repo->addWorktree('/tmp/review', 'feature/review');
$wt = $repo->addWorktree('/tmp/checkouts/review', 'feature/review', name: 'review-wt');

removeWorktree

PHP
public function removeWorktree(string $pathOrName, bool $force = false): void

Elimina un árbol de trabajo vinculado. Usa $force = true para eliminarlo incluso si está bloqueado.

worktrees

PHP
public function worktrees(): array

Lista todos los árboles de trabajo (principal y vinculados). Devuelve Worktree[].

PHP
foreach ($repo->worktrees() as $wt) {
    echo "{$wt->path} [{$wt->branch}]\n";
}

Configuración

config

PHP
public function config(): GitConfig

Accede a la configuración de git del repositorio. Lee y escribe valores de configuración.

PHP
$config = $repo->config();
$name = $config->get('user.name');
$config->set('user.email', 'new@example.com');

Acceso interno

Estos métodos exponen componentes internos para casos de uso avanzados.

objectDatabase

PHP
public function objectDatabase(): ObjectDatabase

Accede a la base de datos de objetos sin procesar (almacenes loose y pack).

refDatabase

PHP
public function refDatabase(): RefDatabase

Accede a la base de datos de referencias sin procesar (referencias loose y empaquetadas).

Clases de nivel inferior

Estas clases no están envueltas por Repository y se crean a partir de sus componentes internos.

Pitmaster\Graph\Blame

PHP
public function blame(ObjectId $headId, string $path): array

Devuelve una entrada por cada línea de $path en $headId: ['line' => int, 'hash' => string, 'author' => string, 'content' => string]. author es la cadena de identidad completa (Name <email> timestamp timezone).

PHP
use Pitmaster\Graph\Blame;

$blame = new Blame($repo->objectDatabase());

foreach ($blame->blame($repo->resolve('HEAD'), 'src/File.php') as $line) {
    echo substr($line['hash'], 0, 8) . " {$line['content']}\n";
}

Pitmaster\Graph\Grep

PHP
public function grep(ObjectId $treeId, string $pattern, string $prefix = '', array $options = []): array

Busca en los blobs de un árbol. Devuelve ['path' => string, 'line' => int, 'content' => string] por cada línea coincidente. Opciones: regex (trata el patrón como una expresión PCRE) y ignore_case. Una expresión regular no válida lanza InvalidArgumentException.

PHP
use Pitmaster\Graph\Grep;

$grep = new Grep($repo->objectDatabase());
$matches = $grep->grep($repo->head()->tree, 'TODO', '', ['ignore_case' => true]);

Pitmaster\Ref\Notes

PHP
public function get(ObjectId $commitId, string $notesRef = 'refs/notes/commits'): ?string
public function set(ObjectId $commitId, string $noteContent, string $notesRef = 'refs/notes/commits'): void
public function remove(ObjectId $commitId, string $notesRef = 'refs/notes/commits'): void
public function listAll(string $notesRef = 'refs/notes/commits'): array
public function merge(string $sourceRef, string $targetRef = 'refs/notes/commits'): void

Lee y escribe notas de git almacenadas bajo una referencia de notas. listAll() devuelve una asignación de hashes de commits al contenido de las notas.

PHP
use Pitmaster\Ref\Notes;

$notes = new Notes($repo->objectDatabase(), $repo->refDatabase());
$notes->set($repo->resolve('HEAD'), "Reviewed\n");
echo $notes->get($repo->resolve('HEAD'));