PHP API
Pitmaster\Pitmaster
Die Klasse Pitmaster\Pitmaster ist der statische Einstiegspunkt. Sie bietet Factory-Methoden zum Öffnen, Erstellen und Klonen von Repositorys sowie Erkennungsfunktionen.
use Pitmaster\Pitmaster;
open
public static function open(string $path, array $options = []): Repository
Öffne ein vorhandenes Repository unter $path. Der Pfad sollte auf die Wurzel des Arbeitsverzeichnisses zeigen (mit .git/). Unterstützt werden auch verknüpfte Worktrees (bei denen .git eine Datei mit gitdir: <path> enthält) und Bare-Repositorys (bei denen $path selbst das Verzeichnis .git ist).
$options akzeptiert zwei boolesche Werte, die standardmäßig beide true sind:
hooks:.git/hooks-Skripte ausführen. Übergibfalse, um sie für dieses Handle zu überspringen.processes: alles zulassen, was einen Prozess startet oder einen Netzwerktransport öffnet. Übergibfalse, um Hooks, den fsmonitor-Hook, Klonen, Fetch, Push und den SSH-Prozesstransport zu deaktivieren. Lokales Lesen und Schreiben funktioniert weiterhin.
Löst InvalidArgumentException aus, wenn der Pfad kein git-Repository ist.
$repo = Pitmaster::open('/home/user/project');
$repo = Pitmaster::open('/home/user/project', ['hooks' => false]);
$repo = Pitmaster::open('/home/user/project', Pitmaster::processFreeOptions());
init
public static function init(string $path, string $objectFormat = 'sha1', array $options = []): Repository
Ein neues Repository unter $path initialisieren. Erstellt die .git-Verzeichnisstruktur mit objects/, refs/heads/, refs/tags/, hooks/, info/, HEAD (zeigt auf refs/heads/main) und einer Standard-config.
$objectFormat ist 'sha1' oder 'sha256'. Ein SHA-256-Repository erhält repositoryformatversion = 1 und extensions.objectformat = sha256 in seiner Konfiguration. Jeder andere Wert löst InvalidArgumentException aus. $options verwendet dieselben Schlüssel wie open().
Löst RuntimeException aus, wenn unter diesem Pfad bereits ein Repository vorhanden ist.
$repo = Pitmaster::init('/home/user/new-project');
$repo = Pitmaster::init('/home/user/sha256-project', 'sha256');
clone
public static function clone(string $url, string $path, ?int $depth = null, array $options = []): Repository
Ein entferntes Repository klonen. Initialisiert ein neues Repo, ermittelt Remote-Refs, lädt die Pack-Datei herunter, richtet Remote-Tracking-Branches ein und erstellt den Arbeitsbaum. SSH-URLs (ssh://... oder user@host:path) verwenden den SSH-Transport; andere URLs nutzen smart HTTP und greifen auf dumb HTTP zurück, wenn der Smart-Austausch fehlschlägt. Für einen flachen Klon $depth übergeben.
Löst RuntimeException aus, wenn $options['processes'] false ist. Wenn das Klonen fehlschlägt und $path zuvor nicht vorhanden war, wird das teilweise erstellte Verzeichnis entfernt.
$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
public static function processFreeOptions(): array
Gibt ['processes' => false, 'hooks' => false] für Laufzeitumgebungen zurück, die keine Host-Prozesse starten dürfen. An open() oder init() übergeben.
isRepository
public static function isRepository(string $path): bool
Prüft, ob ein Pfad ein git-Repository ist. Gibt true für gewöhnliche Repositories (Verzeichnis .git/), verknüpfte Arbeitsbäume (Datei .git) und Bare-Repositories (Datei HEAD vorhanden) zurück.
if (Pitmaster::isRepository('/path/to/check')) {
// It's a git repo
}
isWorktree
public static function isWorktree(string $path): bool
Prüfen, ob ein Pfad ein verknüpfter Arbeitsbaum ist (nicht das Haupt-Repo). Gibt true nur zurück, wenn .git eine Datei mit einer gitdir:-Referenz ist.
if (Pitmaster::isWorktree('/path/to/worktree')) {
// It's a linked worktree
}
commonGitDir
public static function commonGitDir(string $path): ?string
Löst das gemeinsame git-Verzeichnis anhand eines beliebigen Checkout-Pfads auf. Bei gewöhnlichen Repositories ist dies das Verzeichnis .git. Bei verknüpften Arbeitsbäumen ist es das gemeinsame Verzeichnis git, das Objekte, Konfiguration und Packed-Refs enthält. Gibt null zurück, wenn der Pfad kein Repository ist.
$common = Pitmaster::commonGitDir('/path/to/worktree');
// '/path/to/main-repo/.git'
Pitmaster\Repository
Die Klasse Pitmaster\Repository ist die zentrale Schnittstelle für alle git-Operationen. Erzeuge sie mit Pitmaster::open(), Pitmaster::init() oder Pitmaster::clone().
use Pitmaster\Repository;
Pfadzugriffe
gitDir
public function gitDir(): string
Gibt das git-Verzeichnis des jeweiligen Arbeitsbaums zurück. Bei gewöhnlichen Repositories ist dies .git/. Bei verknüpften Arbeitsbäumen ist es .git/worktrees/<name>/.
commonGitDir
public function commonGitDir(): string
Gibt das gemeinsame Git-Verzeichnis zurück. Bei regulären Repos entspricht es gitDir(). Bei verknüpften Arbeitsbäumen ist es das Verzeichnis .git/ des Haupt-Repos (dort befinden sich Objekte, Konfiguration und packed-refs).
workDir
public function workDir(): string
Gibt den Stammpfad des Arbeitsbaums zurück.
isLinkedWorktree
public function isLinkedWorktree(): bool
Gibt true zurück, wenn dieses Repository-Handle ein verknüpfter Arbeitsbaum ist.
isBare, hooksEnabled, processesEnabled
public function isBare(): bool
public function hooksEnabled(): bool
public function processesEnabled(): bool
Gibt an, ob das Repository keinen Arbeitsbaum hat und welche der Optionen hooks / processes für dieses Handle gelten. hooksEnabled() ist immer false, wenn Prozesse deaktiviert sind.
Objekte
readObject
public function readObject(string $hash): GitObject
Ein beliebiges Objekt anhand seines vollständigen hexadezimalen Hashes lesen (40 Zeichen oder 64 in einem SHA-256-Repository). Abgekürzte Hashes werden nicht akzeptiert. Gibt eine Instanz von Blob, Tree, Commit oder Tag zurück. Durchsucht zuerst lose Objekte, dann Pack-Dateien.
Löst ObjectNotFoundException aus, wenn der Hash nicht gefunden wird.
$object = $repo->readObject('a1b2c3d4e5f6...');
writeObject
public function writeObject(GitObject $object): ObjectId
Ein Objekt in den Speicher für lose Objekte schreiben. Gibt den berechneten ObjectId zurück.
use Pitmaster\Object\Blob;
$blob = Blob::fromContent('Hello, world!');
$id = $repo->writeObject($blob);
catFile
public function catFile(string $hash): string
Den Rohinhalt eines Objekts zurückgeben, gleichbedeutend mit git cat-file -p.
echo $repo->catFile('a1b2c3d4...');
objectExists
public function objectExists(string $hash): bool
Prüfen, ob ein Objekt im Repository vorhanden ist (lose oder gepackt).
listObjects
public function listObjects(): array
Alle Objekt-Hashes im Repository auflisten. Gibt ein Array hexadezimaler Zeichenfolgen zurück.
Refs
head
public function head(): Commit
Den aktuellen HEAD-Commit zurückgeben. Folgt symbolischen Refs (HEAD -> refs/heads/main -> Commit-Hash).
Löst RuntimeException aus, wenn HEAD nicht auf einen gültigen Commit zeigt (e.g, leeres Repository).
branch
public function branch(?string $name = null): ?string
Ohne Argumente wird der aktuelle Branch-Name zurückgegeben (e.g, 'main') oder null, wenn HEAD losgelöst ist.
Mit einem Branch-Namen wird dieser zu seinem Commit-Hash (hexadezimale Zeichenfolge) aufgelöst oder null zurückgegeben, wenn der Branch nicht existiert.
$current = $repo->branch(); // 'main'
$hash = $repo->branch('feature'); // 'abc123...' or null
branches
public function branches(): array
Ein sortiertes Array aller Branch-Namen zurückgeben (ohne das Präfix refs/heads/).
$branches = $repo->branches();
// ['bugfix/typo', 'feature/login', 'main']
tags
public function tags(): array
Ein sortiertes Array aller Tag-Namen zurückgeben (ohne das Präfix refs/tags/).
resolve
public function resolve(string $revision): ObjectId
Einen Revisionsausdruck zu einem ObjectId auflösen. Unterstützt werden:
- Vollständige Hex-Hashes (40 Zeichen oder 64 für SHA-256). Abgekürzte Hashes wie
abc1234werden nicht aufgelöst. HEAD- Branch-Namen (
main,feature/login) - Tag-Namen (
v1.0.0) - Vollständige Ref-Pfade (
refs/heads/main) - Revisionsausdrücke (
HEAD~3,main^2)
Löst RuntimeException aus, wenn die Revision nicht aufgelöst werden kann.
$id = $repo->resolve('HEAD~3');
$id = $repo->resolve('v1.0.0');
$id = $repo->resolve('feature/login');
allRefs
public function allRefs(): array
Alle Refs als assoziatives Array mit Ref-Namen und Hex-Hashes zurückgeben.
$refs = $repo->allRefs();
// ['refs/heads/main' => 'abc123...', 'refs/tags/v1.0.0' => 'def456...']
updateRef
public function updateRef(string $name, ObjectId $target): void
Eine Ref aktualisieren, sodass sie auf ein neues Ziel zeigt.
$repo->updateRef('refs/heads/main', $commitId);
createBranch
public function createBranch(string $name, ?ObjectId $from = null): void
Einen neuen Branch erstellen. Wenn $from null ist, wird der aktuelle HEAD als Ausgangspunkt verwendet.
$repo->createBranch('feature/new-thing');
$repo->createBranch('hotfix', $repo->resolve('v1.0.0'));
deleteBranch
public function deleteBranch(string $name): void
Einen Branch anhand seines Namens löschen. Löst RuntimeException aus, wenn der Branch ausgecheckt ist oder nicht existiert. Anders als git branch -d wird nicht geprüft, ob der Branch gemergt wurde.
$repo->deleteBranch('feature/old');
createLightweightTag
public function createLightweightTag(string $name, ?ObjectId $target = null): void
Einen Lightweight-Tag erstellen. Wenn $target null ist, wird der aktuelle HEAD direkt getaggt.
$repo->createLightweightTag('v2.0.0');
$repo->createLightweightTag('hotfix-start', $repo->resolve('main~2'));
createTag
public function createTag(string $name, string $message, ?ObjectId $target = null, ?string $tagger = null): ObjectId
Einen annotierten Tag erstellen. Wenn $target null ist, wird der aktuelle HEAD getaggt. Gibt den ObjectId des Tag-Objekts zurück.
$tagId = $repo->createTag('v2.0.0', 'Release version 2.0.0');
deleteTag
public function deleteTag(string $name): void
Einen Tag anhand seines Namens löschen.
$repo->deleteTag('v1.0.0');
packRefs
public function packRefs(): void
Schreibt die gemeinsame packed-refs-Datei anhand der aktuellen Menge loser Refs neu und entfernt die entsprechenden gemeinsamen losen Refs. Bei verknüpften Arbeitsbäumen wird in das gemeinsame Verzeichnis git geschrieben.
$repo->packRefs();
defaultBranch
public function defaultBranch(): string
Den Standard-Branch des Repositorys ermitteln. Prüft zuerst den Remote-HEAD-Symref, dann den lokalen HEAD und greift schließlich auf main oder master zurück.
isBranchMerged
public function isBranchMerged(string $branch, ?string $target = null): bool
Prüfen, ob ein Branch vollständig in einen anderen Branch gemergt wurde (standardmäßig in den Standard-Branch).
if ($repo->isBranchMerged('feature/done')) {
$repo->deleteBranch('feature/done');
}
checkout
public function checkout(string $target): void
Branches wechseln oder HEAD loslösen. Aktualisiert HEAD, den Index und den Arbeitsbaum. $target ist ein Branch-Name, ein Tag, ein vollständiger Hash oder ein Revisionsausdruck; alles, was kein Branch ist, löst HEAD los.
Löst RuntimeException aus, wenn eine lokale Änderung (gestaged oder nicht) oder eine nicht verfolgte Datei in einem Pfad liegt, der sich zwischen dem aktuellen und dem Ziel-Tree unterscheidet.
Nicht committete Änderungen in anderen verfolgten Dateien werden nicht übernommen: Index und Arbeitsbaum werden anhand des Ziel-Trees neu erstellt. Dadurch gehen Änderungen an Dateien verloren, die auf beiden Seiten identisch sind und die Git beibehalten würde (#2). Committe oder stash sie zuerst. merge(), cherryPick(), revert(), rebase() und die Bisect-Methoden erstellen den Arbeitsbaum auf dieselbe Weise neu.
$repo->checkout('feature/login');
$repo->checkout($repo->resolve('v1.0.0')->hex); // Detached HEAD
Index
index
public function index(): Index
Den aktuellen Index (Staging-Bereich) aus .git/index lesen und zurückgeben.
add
public function add(string ...$paths): void
Dateien stagen. Liest jede Datei aus dem Arbeitsbaum, erstellt ein Blob-Objekt und aktualisiert den Index. Jedes Argument muss ein Datei- oder Symlink-Pfad relativ zum Stammverzeichnis des Arbeitsbaums sein; Verzeichnisse und Globs werden nicht erweitert, und eine fehlende Datei löst RuntimeException aus.
$repo->add('src/Feature.php', 'tests/FeatureTest.php');
remove
public function remove(string ...$paths): void
public function removeCached(string ...$paths): void
Verfolgte Pfade sowohl aus dem Index als auch aus dem Arbeitsbaum entfernen. Für ein Verhalten wie bei Git werden --cached sowie -r / --recursive in der Argumentliste unterstützt.
$repo->remove('old-file.txt');
$repo->remove('-r', 'src');
$repo->remove('--cached', 'old-file.txt');
$repo->removeCached('old-file.txt');
mv
public function mv(string $source, string $destination): void
Eine Datei sowohl im Arbeitsbaum als auch im Index verschieben oder umbenennen.
$repo->mv('old-name.php', 'new-name.php');
Commits
commit
public function commit(?string $message = null, ?string $author = null): ObjectId
Einen Commit aus dem aktuellen Index erstellen. Erstellt aus den Indexeinträgen eine Tree-Hierarchie, erzeugt das Commit-Objekt mit HEAD als übergeordnetem Commit (falls vorhanden) und aktualisiert HEAD. Gibt den ObjectId des neuen Commits zurück.
$message darf nur null sein, wenn ein Merge, Cherry-Pick, Revert oder Rebase wegen eines Konflikts angehalten wurde; dann wird die vorbereitete Nachricht verwendet. Andernfalls löst eine null-Nachricht RuntimeException('Commit message required') aus. Ein Commit löst außerdem einen Fehler aus, wenn der Index nicht gemergte Pfade enthält, der Index in einem Repository ohne Commits leer ist oder sich der Tree seit HEAD nicht geändert hat.
Der Parameter $author ist eine vollständige git-Zeichenfolge für den Autor (Name <email> timestamp timezone). Ist er null, wird der Wert anhand von Umgebungsvariablen, Konstanten und .git/config aufgelöst, und zwar in der unter Erste Schritte beschriebenen Reihenfolge.
$id = $repo->commit('Fix null pointer bug');
show
public function show(string $revision): array
Einen Commit-ähnlichen Verweis und seinen Diff gegenüber dem ersten übergeordneten Commit anzeigen. Wird die Revision zu einem annotierten Tag aufgelöst, enthält der Rückgabewert außerdem ['tag' => Tag], und commit ist der aufgelöste Ziel-Commit.
$result = $repo->show('HEAD');
echo $result['commit']->message;
foreach ($result['diff'] as $diff) {
echo $diff->format();
}
reset
public function reset(string $revision, string $mode = 'mixed'): void
HEAD auf einen Commit zurücksetzen. Modi:
'soft': nur HEAD verschieben'mixed': HEAD verschieben + Index zurücksetzen (Standard)'hard': HEAD verschieben + Index zurücksetzen + Arbeitsbaum zurücksetzen
$repo->reset('HEAD~1', 'soft');
$repo->reset('main', 'hard');
restore
public function restore(string $path, ?string $source = null, bool $staged = false, bool $worktree = false): void
Einen Pfad aus dem Index oder einer bestimmten Quellrevision wiederherstellen. Wenn kein Flag gesetzt ist, stellt Pitmaster den Arbeitsbaum aus dem Index wieder her (oder aus $source, falls angegeben). staged: true stellt den Index aus HEAD (oder $source) wieder her und lässt den Arbeitsbaum unverändert; mit staged: true, worktree: true werden beide wiederhergestellt.
$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
public function cherryPick(string $revision): ObjectId
public function cherryPickContinue(): ObjectId
public function cherryPickAbort(): void
Einen Commit als neuen Commit auf dem aktuellen Branch anwenden und dabei den ursprünglichen Autor beibehalten. Wenn Konflikte den Vorgang anhalten, löse sie auf, stage die Pfade und rufe dann cherryPickContinue() oder cherryPickAbort() auf.
$newId = $repo->cherryPick('feature~2');
// After resolving conflicts:
$repo->add('src/File.php');
$repo->cherryPickContinue();
revert
public function revert(string $revision): ObjectId
public function revertContinue(): ObjectId
public function revertAbort(): void
Einen Commit erstellen, der einen anderen Commit rückgängig macht. Wenn Konflikte den Revert anhalten, löse sie auf, stage die Pfade und rufe dann revertContinue() oder revertAbort() auf.
$revertId = $repo->revert('HEAD~1');
// After resolving conflicts:
$repo->add('src/File.php');
$repo->revertContinue();
rebase
public function rebase(string $onto): array
public function rebaseContinue(): array
public function rebaseAbort(): void
public function rebaseSkip(): array
Den aktuellen Branch auf eine andere Revision rebasen. Pitmaster unterstützt derzeit lineare Rebases mit einem Git-ähnlichen Unterbrechungsstatus bei Konflikten sowie fortsetzen, abbrechen und überspringen. HEAD muss auf einen Branch zeigen.
rebase(), rebaseContinue() und rebaseSkip() geben ['success' => bool, 'commits' => int, 'conflicts' => list<string>] zurück: ob der Rebase abgeschlossen wurde, wie viele Commits angewendet wurden und welche Pfade beim Anhalten Konflikte verursachten.
$result = $repo->rebase('main');
if (!$result['success']) {
// Resolve conflicts, then continue or skip/abort.
$repo->add('src/File.php');
$repo->rebaseContinue();
}
Status
status
public function status(): array
Status des Arbeitsbaums ermitteln. Gibt ein Array von StatusEntry-Objekten zurück, die jeweils Folgendes enthalten:
path: den Dateipfadindex: einFileStatus-Enum für Änderungen von HEAD zum Indexworktree: einFileStatus-Enum für Änderungen vom Index zum ArbeitsbaumorigPath,renameScore: bei umbenannten Einträgen gesetzt, andernfallsnull
Nicht verfolgte Dateien haben in beiden Spalten den Wert FileStatus::Untracked. Ignorierte Dateien werden nicht aufgeführt.
foreach ($repo->status() as $entry) {
echo $entry->shortFormat() . "\n"; // "M src/File.php", "?? notes.txt"
}
statusPorcelainV2
public function statusPorcelainV2(): string
Maschinenlesbare Statusausgabe im Porzellanformat v2 von git.
echo $repo->statusPorcelainV2();
// 1 M. N... 000000 000000 000000 0000...0000 0000...0000 modified-file.txt
// ? untracked-file.txt
Diff
diff
public function diff(?string $pathspec = null, string $algorithm = 'myers'): array
Diff des Arbeitsbaums gegenüber dem Index (nicht gestagte Änderungen). Gibt ein Array von DiffResult-Objekten zurück. $pathspec filtert nach einem exakten Dateipfad. $algorithm ist 'myers' (Standard), 'patience', 'histogram' oder 'minimal'; jeder andere Wert löst InvalidArgumentException aus.
$diffs = $repo->diff();
foreach ($diffs as $diff) {
echo $diff->format(); // Unified diff output
}
diffStaged
public function diffStaged(?string $pathspec = null, string $algorithm = 'myers'): array
Diff des Index gegenüber HEAD (gestagte Änderungen). Gibt DiffResult[] zurück und erkennt dabei Umbenennungen zwischen gelöschten und hinzugefügten Dateien.
Das Argument $pathspec wird derzeit ignoriert, sodass alle gestagten Dateien zurückgegeben werden. Vor dem ersten Commit gibt die Methode ein leeres Array zurück (#5).
$staged = $repo->diffStaged();
diffTree
public function diffTree(ObjectId $a, ObjectId $b, string $algorithm = 'myers'): array
Zwei Trees anhand ihrer ObjectId vergleichen. Gibt DiffResult[] zurück. Tree-IDs übergeben, keine Commit-IDs: Eine Commit-ID wird nicht als Tree gelesen und ergibt ein leeres Ergebnis.
$old = $repo->readObject($repo->resolve('HEAD~1')->hex);
$new = $repo->head();
$diffs = $repo->diffTree($old->tree, $new->tree);
Verlauf
log
public function log(int $limit = 50, ?ObjectId $from = null): array
Den Commit-Verlauf durchlaufen, neueste zuerst, sortiert nach Committer-Zeitstempel. Gibt Commit[] zurück. Wenn $from null ist, wird bei HEAD begonnen. Wenn HEAD noch keinen Commit hat, wird ein leeres Array zurückgegeben.
$commits = $repo->log(10);
logAll
public function logAll(int $limit = 50): array
Commits durchlaufen, die von jeder Ref und HEAD aus erreichbar sind, neueste zuerst. Gibt Commit[] zurück.
logOneline
public function logOneline(int $limit = 50, bool $all = false, ?string $path = null): array
Protokollzeilen im Format git log --oneline (abc1234 Subject) ausgeben, ausgehend von HEAD, von allen Refs ($all) oder nach Pfad gefiltert.
logPath
public function logPath(string $path, int $limit = 50): array
Verlauf nach einem Dateipfad filtern. Gibt nur Commits zurück, deren Diff gegenüber dem ersten übergeordneten Commit genau diese Datei hinzufügt, ändert, löscht oder umbenennt. Verzeichnispfade stimmen nicht überein.
Es werden nur die neuesten 5 * $limit Commits geprüft. Ältere Commits, die die Datei betreffen, können daher im Ergebnis fehlen (#7).
$commits = $repo->logPath('src/Repository.php', 20);
Merge
merge
public function merge(string $branch, string $strategy = 'recursive'): MergeResult
public function mergeOctopus(array $branches): MergeResult
public function mergeContinue(): ObjectId
public function mergeAbort(): void
Einen Branch (oder eine beliebige Revision) in HEAD mergen. Erkennt Fast-Forward-Merges automatisch. Bei anderen Merges werden Konflikte auf Tree-Ebene erkannt und bei Erfolg wird ein Merge-Commit erstellt. Bei Konflikten wird der Vorgang angehalten und ein Git-ähnlicher Merge-Status in Index und Arbeitsbaum geschrieben. Löse die Konflikte auf, stage die Pfade und rufe dann mergeContinue() oder mergeAbort() auf.
$strategy 'ours' erstellt einen Merge-Commit, der den Tree von HEAD beibehält; jeder andere Wert verwendet den standardmäßigen rekursiven Merge. mergeOctopus() führt zwei oder mehr Branches in einem Commit zusammen. Bei Konflikten in einem Branch wird ein nicht sauberes Ergebnis zurückgegeben, ohne einen Merge-Status zu schreiben oder einen Commit zu erstellen.
Wird ein Branch gemergt, der bereits in HEAD enthalten ist, entsteht ein weiterer Merge-Commit, statt „Already up to date“ zu melden (#6). Nicht committete Änderungen in verfolgten Dateien werden wie unter checkout() beschrieben überschrieben.
Gibt ein MergeResult zurück mit:
clean: ob der Merge ohne Konflikte erfolgreich warcommitId: die ID des Merge-Commits (bei sauberem Ergebnis)conflictPaths: Array der Pfade zu Dateien mit Konflikten (bei nicht sauberem Ergebnis)mergedContents: Zuordnung von Konfliktpfaden zu Dateiinhalten mit Konfliktmarkierungen (bei nicht sauberem Ergebnis)
$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
public function mergeBase(ObjectId $a, ObjectId $b): ?ObjectId
Die Merge-Basis (den niedrigsten gemeinsamen Vorfahren) zweier Commits finden. Gibt null zurück, wenn kein gemeinsamer Vorfahr existiert.
$base = $repo->mergeBase(
$repo->resolve('main'),
$repo->resolve('feature/login'),
);
Bisect
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
Binär nach dem Commit suchen, der eine Änderung eingeführt hat. bisectStart() speichert die fehlerhaften und guten Revisionen, checkt den ersten Kandidaten aus und gibt ihn zurück. bisectGood() und bisectBad() markieren den aktuellen HEAD (oder $revision), checken den nächsten Kandidaten aus und geben ihn zurück. Bleibt nur ein Verdächtiger übrig, wird dieser Commit zurückgegeben und bleibt der Kandidat: Er ist der erste fehlerhafte Commit. bisectReset() beendet die Sitzung und kehrt zum Branch oder Commit zurück, an dem sie begonnen hat.
$candidate = $repo->bisectStart('HEAD', 'v1.0.0');
// test $candidate ...
$candidate = $repo->bisectBad();
$candidate = $repo->bisectGood();
$repo->bisectReset();
Netzwerk
fetch
public function fetch(string $remote = 'origin', ?int $depth = null): void
Von einem Remote abrufen. Lädt neue Objekte herunter und aktualisiert Remote-Tracking-Refs. $depth übergeben, um einen flachen Verlauf zu vertiefen oder zu begrenzen.
fetch() und die Methoden push*() lösen bei einem Handle, das mit ['processes' => false] geöffnet wurde, RuntimeException aus.
$repo->fetch();
$repo->fetch('upstream');
push
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
Den aktuellen oder einen angegebenen Branch zu einem Remote pushen. Varianten mit Force-with-lease, atomar und als Spiegelung sind für strengere oder umfassendere Ref-Aktualisierungen verfügbar.
$repo->push();
$repo->push('origin', 'feature/login');
$repo->pushForceWithLease('origin', 'main', $repo->resolve('refs/remotes/origin/main'));
$repo->pushAtomic('origin', ['main', 'release']);
$repo->pushMirror();
Arbeitsbäume
addWorktree
public function addWorktree(string $path, string $branch, ?ObjectId $from = null, ?string $name = null): Worktree
Einen verknüpften Arbeitsbaum hinzufügen. Erstellt den Branch, falls er nicht existiert, richtet die Metadaten des Arbeitsbaums ein und erstellt die Arbeitsbaumdateien. $name übergeben, wenn du einen deterministischen Metadaten-Slug brauchst, der sich vom Basisnamen des Checkout-Verzeichnisses unterscheidet.
$wt = $repo->addWorktree('/tmp/review', 'feature/review');
$wt = $repo->addWorktree('/tmp/checkouts/review', 'feature/review', name: 'review-wt');
removeWorktree
public function removeWorktree(string $pathOrName, bool $force = false): void
Einen verknüpften Arbeitsbaum entfernen. Mit $force = true auch dann entfernen, wenn er gesperrt ist.
worktrees
public function worktrees(): array
Alle Arbeitsbäume auflisten (Haupt- und verknüpfte). Gibt Worktree[] zurück.
foreach ($repo->worktrees() as $wt) {
echo "{$wt->path} [{$wt->branch}]\n";
}
Konfiguration
config
public function config(): GitConfig
Greift auf die Repository-Konfiguration von git zu. Liest und schreibt Konfigurationswerte.
$config = $repo->config();
$name = $config->get('user.name');
$config->set('user.email', 'new@example.com');
Interner Zugriff
Diese Methoden legen interne Komponenten für fortgeschrittene Anwendungsfälle offen.
objectDatabase
public function objectDatabase(): ObjectDatabase
Auf die rohe Objektdatenbank zugreifen (lose und gepackte Speicher).
refDatabase
public function refDatabase(): RefDatabase
Auf die rohe Ref-Datenbank zugreifen (lose und gepackte Refs).
Klassen auf niedrigerer Ebene
Diese Klassen werden nicht von Repository umschlossen und aus dessen internen Komponenten erstellt.
Pitmaster\Graph\Blame
public function blame(ObjectId $headId, string $path): array
Gibt eine Zeile pro Eintrag aus $path unter $headId zurück: ['line' => int, 'hash' => string, 'author' => string, 'content' => string]. author ist die vollständige Identitätszeichenfolge (Name <email> timestamp timezone).
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
public function grep(ObjectId $treeId, string $pattern, string $prefix = '', array $options = []): array
Durchsucht die Blobs eines Trees. Gibt ['path' => string, 'line' => int, 'content' => string] pro passender Zeile zurück. Optionen: regex (behandelt das Muster als PCRE-Muster) und ignore_case. Ein ungültiger regulärer Ausdruck löst InvalidArgumentException aus.
use Pitmaster\Graph\Grep;
$grep = new Grep($repo->objectDatabase());
$matches = $grep->grep($repo->head()->tree, 'TODO', '', ['ignore_case' => true]);
Pitmaster\Ref\Notes
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
Liest und schreibt git-Notizen, die unter einer Notes-Ref gespeichert sind. listAll() liefert die Zuordnung von Commit-Hashes zu Notizinhalten zurück.
use Pitmaster\Ref\Notes;
$notes = new Notes($repo->objectDatabase(), $repo->refDatabase());
$notes->set($repo->resolve('HEAD'), "Reviewed\n");
echo $notes->get($repo->resolve('HEAD'));