Pular para o conteúdo

Introdução

Ver como Markdown Editar no GitHub Documentação em bfe242f

Pitmaster é uma biblioteca pura de PHP que lê e grava repositórios Git nativamente. As operações principais do repositório não executam o binário git nem usam FFI. O modelo de objetos Git, o formato do arquivo pack, o formato do índice e o transporte HTTP inteligente são implementados em PHP.

Por que Pitmaster existe

Aplicações PHP que interagem com repositórios Git normalmente executam o binário git pelo shell. Isso funciona, mas cria uma dependência rígida da instalação de git, traz preocupações de segurança em torno de exec() e proc_open() e dificulta a implantação do aplicativo em ambientes restritos (contêineres sem git, hospedagem compartilhada, funções sem servidor).

Pitmaster elimina a dependência de git para o trabalho principal com repositórios. Seu aplicativo PHP pode ler o histórico de commits, criar commits, calcular diffs, verificar o estado e fazer push para remotos por HTTP inteligente usando apenas as funções integradas de PHP. Hooks e o transporte SSH são exceções: ambos iniciam processos e podem ser desativados por identificador de repositório (consulte Hooks).

O que ele faz

  • Lê e grava objetos soltos (blob, tree, commit, tag)
  • Lê arquivos pack e resolve cadeias delta (OFS_DELTA e REF_DELTA)
  • Grava arquivos pack para operações de rede
  • Lê e grava o índice/área de preparação (formatos v2, v3, v4)
  • Lê e grava refs (branches, tags, HEAD, packed-refs, reftable)
  • Calcula diffs (algoritmos Myers, Patience, Histogram e Minimal) no formato unificado de git
  • Realiza mesclagens de três vias com detecção de conflitos
  • Percorre grafos de commits (log, ancestralidade, base da mesclagem)
  • Fala o protocolo Git HTTP inteligente (clone, fetch, push)
  • Oferece suporte a worktrees, submódulos, stash, hooks e Git LFS

O que é necessário

  • PHP 8.2 ou posterior
  • Extensão zlib (incluída em praticamente todas as instalações de PHP)
  • Extensão json
  • Extensão mbstring (declarada em composer.json, portanto Composer exige-a no momento da instalação)
  • Extensão ctype (usada para validar hashes de objetos; habilitada na maioria das compilações de PHP, mas não declarada em composer.json)

As operações principais do repositório não exigem o binário git. Recursos opcionais podem precisar de capacidades adicionais em tempo de execução: a execução de hooks usa proc_open(), e o transporte SSH usa ext-ssh2 quando carregado; caso contrário, inicia o binário ssh do sistema por meio de proc_open().

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

Comece por Primeiros passos e, em seguida, consulte API, CLI e Operações para conhecer o restante dos recursos. Testes explica como Pitmaster é verificado em relação a git.