Premiers pas

Afficher au format Markdown Modifier sur GitHub Documentation de bfe242f

Installation

Installez Pitmaster via Composer :

Shell

composer require pitmaster/pitmaster

Prérequis

PHP 8.2+ avec classes en lecture seule, énumérations et promotion de constructeur
ext-zlib pour la compression et la décompression des objets (intégré dans la plupart des installations)
ext-json pour les fichiers d'état des opérations et les charges utiles Git LFS API
ext-mbstring, déclaré dans composer.json, donc Composer en a besoin lors de l'installation
ext-ctype pour la validation des hachages (activé dans la plupart des compilations PHP, mais non déclaré dans composer.json)

Les opérations principales sur les dépôts ne nécessitent ni le binaire git, ni FFI, ni outils externes. Les fonctionnalités facultatives ont des exigences d'exécution supplémentaires : l'exécution des hooks utilise proc_open(), et le transport SSH utilise ext-ssh2 lorsqu'il est chargé ; sinon, il lance le binaire système ssh via proc_open().

Ouvrir un dépôt existant

PHP

use Pitmaster\Pitmaster;

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

Ouvre le dépôt au chemin indiqué. Pitmaster localise le répertoire .git (ou résout un fichier .git pour les worktrees liés), puis initialise la base d'objets, la base de refs et la configuration.

open(), init() et clone() acceptent un tableau d'options comme dernier argument :

PHP

// 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());

Les hooks sont exécutés par défaut. Pitmaster::processFreeOptions() renvoie ['processes' => false, 'hooks' => false] ; les lectures et écritures locales continuent de fonctionner sur un tel handle.

Vérifier si un chemin est un dépôt

PHP

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

Initialiser un nouveau dépôt

PHP

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

Cela crée la structure de répertoires .git avec les objets, les refs, HEAD (pointant vers refs/heads/main) et une configuration par défaut.

Pour créer un dépôt SHA-256, indiquez le format d'objet en deuxième argument :

PHP

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

Les ID d'objet dans ce dépôt font 64 caractères hexadécimaux, et la configuration enregistre extensions.objectformat = sha256. Les dépôts ouverts par la suite récupèrent le format dans cette entrée de configuration.

Lire le commit HEAD

PHP

$head = $repo->head();

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

La méthode head() résout HEAD (en suivant les refs symboliques) et renvoie un objet Commit.

Lister les branches et les tags

PHP

// 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']

Parcourir l'historique des commits

PHP

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

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

Vous pouvez aussi partir d'un commit spécifique :

PHP

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

Vérifier l'état de l'arbre de travail

PHP

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";
    }
}

Ajouter des fichiers à l'index et créer un commit

PHP

// 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";

Le nom et l'adresse e-mail de l'auteur sont déterminés dans cet ordre : les variables d'environnement PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, les variables d'environnement GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL, les constantes PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, la configuration propre au dépôt .git/config (user.name et user.email), puis Pitmaster <pitmaster@localhost>. Seul le fichier de configuration du dépôt (et les fichiers qu'il inclut) est lu, pas ~/.gitconfig. Le committer est déterminé de la même façon à partir des noms *_COMMITTER_* et revient aux constantes de l'auteur en dernier recours.

Calculer les diffs

PHP

// 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();

Cloner un dépôt distant

PHP

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

Cette fonction découvre les références, récupère le fichier pack, configure les branches de suivi distant et extrait la branche par défaut. HTTP(S) Les URL utilisent HTTP intelligent et basculent sur HTTP simple ; les URL SSH utilisent le transport SSH. Passez une profondeur en troisième argument pour un clonage superficiel : Pitmaster::clone($url, $path, 1).

Lire n’importe quel objet à partir de son hachage

PHP

$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;
}

Configuration

Pitmaster respecte le .git/config du dépôt pour les informations d’auteur et les URL distantes. Vous pouvez également définir des valeurs par défaut globales à l’aide des constantes PHP, définies avant l’exécution de Pitmaster :

PHP

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

Constante	Valeur par défaut	Effet
`PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`	aucune	Identité de l’auteur (voir l’ordre ci-dessus)
`PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL`	valeurs de l’auteur	Identité du validateur
`PITMASTER_HTTP_TIMEOUT`	`30`	Délai d’attente de HTTP intelligent en secondes (entier)
`PITMASTER_MAX_DELTA_CHAIN`	`50`	Profondeur maximale de la chaîne de deltas lors de la lecture des packs (entier)
`PITMASTER_OBJECT_CACHE_ENTRIES`	`1024`	Objets conservés dans le cache d’objets en mémoire
`PITMASTER_OBJECT_CACHE_BYTES`	`16M`	Limite en octets du cache d’objets
`PITMASTER_PACK_RESOLVED_CACHE_ENTRIES`	`4096`	Objets delta résolus mis en cache par pack
`PITMASTER_PACK_RESOLVED_CACHE_BYTES`	`32M`	Limite en octets de ce cache de pack
`PITMASTER_MAX_PACK_MEMORY`	aucune	Ancien nom de la limite en octets du cache de pack, utilisé uniquement si `PITMASTER_PACK_RESOLVED_CACHE_BYTES` n’est pas défini

Les valeurs en octets acceptent un entier ou une chaîne avec le suffixe k, m ou g ('256M'). Les valeurs non valides reprennent la valeur par défaut.

Les variables d’environnement prennent le pas sur les constantes d’identité : PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, leurs équivalents PITMASTER_COMMITTER_* et les variables GIT_AUTHOR_* et GIT_COMMITTER_* propres à git. Le transport SSH lit les variables PITMASTER_SSH_*, décrites dans Protocoles.

Il n’existe pas de constante pour l’algorithme de hachage. Le format des objets est choisi lors de la création du dépôt (Pitmaster::init($path, 'sha256') ou init --object-format=sha256 sur le CLI), puis lu dans la configuration du dépôt.