Przejdź do treści

PHP API

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: bfe242f

Pitmaster\Pitmaster

Klasa Pitmaster\Pitmaster jest statycznym punktem wejścia. Udostępnia metody fabrykujące do otwierania, tworzenia i klonowania repozytoriów oraz funkcje pomocnicze do ich wykrywania.

PHP
use Pitmaster\Pitmaster;

open

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

Otwórz istniejące repozytorium w $path. Ścieżka powinna wskazywać katalog główny drzewa roboczego (zawierający .git/). Obsługiwane są także powiązane worktree (w których .git jest plikiem zawierającym gitdir: <path>) oraz repozytoria bare (w których $path jest samym katalogiem .git).

$options przyjmuje dwie wartości logiczne, obie domyślnie true:

  • hooks: uruchamianie skryptów .git/hooks. Przekaż false, aby je pominąć dla tego uchwytu.
  • processes: zezwolenie na wszystko, co uruchamia proces lub otwiera transport sieciowy. Przekaż false, aby wyłączyć hooki, hook fsmonitor, klonowanie, pobieranie, wysyłanie oraz transport procesowy SSH. Odczyt i zapis lokalny nadal działają.

Zgłasza InvalidArgumentException, jeśli ścieżka nie wskazuje repozytorium 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

Zainicjuj nowe repozytorium w $path. Tworzy strukturę katalogów .git z objects/, refs/heads/, refs/tags/, hooks/, info/, HEAD (wskazującym na refs/heads/main) oraz domyślnym config.

$objectFormat ma wartość 'sha1' lub 'sha256'. Repozytorium SHA-256 otrzymuje w konfiguracji repositoryformatversion = 1 i extensions.objectformat = sha256. Każda inna wartość zgłasza InvalidArgumentException. $options przyjmuje te same klucze co open().

Zgłasza RuntimeException, jeśli repozytorium już istnieje w tej ścieżce.

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

Sklonuj zdalne repozytorium. Inicjuje nowe repo, wykrywa zdalne referencje, pobiera plik pack, konfiguruje zdalne gałęzie śledzące i tworzy drzewo robocze. Adresy URL SSH (ssh://... lub user@host:path) używają transportu SSH; pozostałe adresy URL używają inteligentnego HTTP, a gdy wymiana w tym trybie się nie powiedzie, przechodzą na prosty HTTP. Przekaż $depth, aby wykonać płytkie klonowanie.

Zgłasza RuntimeException, gdy $options['processes'] ma wartość false. Jeśli klonowanie się nie powiedzie, a $path wcześniej nie istniało, częściowo utworzony katalog zostanie usunięty.

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

Zwraca ['processes' => false, 'hooks' => false] dla środowisk uruchomieniowych, które nie mogą uruchamiać procesów na hoście. Przekaż tę wartość do open() lub init().

isRepository

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

Sprawdź, czy ścieżka wskazuje repozytorium git. Zwraca true dla zwykłych repozytoriów (katalog .git/), powiązanych worktree (plik .git) i repozytoriów bare (gdy istnieje plik HEAD).

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

isWorktree

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

Sprawdź, czy ścieżka wskazuje powiązane worktree (a nie główne repozytorium). Zwraca true tylko wtedy, gdy .git jest plikiem zawierającym odwołanie gitdir:.

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

commonGitDir

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

Rozwiąż ścieżkę do wspólnego katalogu git na podstawie dowolnej ścieżki kopii roboczej. W zwykłych repozytoriach jest to katalog .git. W powiązanych worktree jest to współdzielony katalog git zawierający obiekty, konfigurację i packed-refs. Zwraca null, jeśli ścieżka nie wskazuje repozytorium.

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

Pitmaster\Repository

Klasa Pitmaster\Repository jest głównym uchwytem do wszystkich operacji git. Można go uzyskać za pomocą Pitmaster::open(), Pitmaster::init() lub Pitmaster::clone().

PHP
use Pitmaster\Repository;

Akcesory ścieżek

gitDir

PHP
public function gitDir(): string

Zwraca katalog git danego worktree. W zwykłych repozytoriach jest to .git/. W powiązanych worktree jest to .git/worktrees/<name>/.

commonGitDir

PHP
public function commonGitDir(): string

Zwraca współdzielony katalog git. W zwykłych repozytoriach jest taki sam jak gitDir(). W powiązanych worktree jest to katalog .git/ głównego repozytorium (zawierający obiekty, konfigurację i packed-refs).

workDir

PHP
public function workDir(): string

Zwraca ścieżkę katalogu głównego drzewa roboczego.

isLinkedWorktree

PHP
public function isLinkedWorktree(): bool

Zwraca true, jeśli ten uchwyt repozytorium wskazuje powiązane worktree.

isBare, hooksEnabled, processesEnabled

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

Informuje, czy repozytorium nie ma drzewa roboczego oraz które opcje hooks / processes są aktywne dla tego uchwytu. hooksEnabled() ma wartość false zawsze wtedy, gdy procesy są wyłączone.

Obiekty

readObject

PHP
public function readObject(string $hash): GitObject

Odczytaj dowolny obiekt, podając jego pełny skrót szesnastkowy (40 znaków lub 64 w repozytorium SHA-256). Skrócone skróty nie są akceptowane. Zwraca instancję Blob, Tree, Commit lub Tag. Najpierw przeszukuje luźne obiekty, a następnie pliki pack.

Zgłasza ObjectNotFoundException, jeśli nie znaleziono skrótu.

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

writeObject

PHP
public function writeObject(GitObject $object): ObjectId

Zapisz obiekt w magazynie luźnych obiektów. Zwraca obliczony ObjectId.

PHP
use Pitmaster\Object\Blob;

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

catFile

PHP
public function catFile(string $hash): string

Zwraca surową zawartość obiektu; odpowiednikiem jest git cat-file -p.

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

objectExists

PHP
public function objectExists(string $hash): bool

Sprawdź, czy obiekt istnieje w repozytorium (wśród luźnych lub spakowanych obiektów).

listObjects

PHP
public function listObjects(): array

Wyświetl wszystkie skróty obiektów w repozytorium. Zwraca tablicę ciągów szesnastkowych.

Referencje

PHP
public function head(): Commit

Zwraca bieżący commit HEAD. Podąża za referencjami symbolicznymi (HEAD -> refs/heads/main -> skrót commita).

Zgłasza RuntimeException, jeśli HEAD nie wskazuje prawidłowego commita (e.g, puste repozytorium).

branch

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

Bez argumentów zwraca nazwę bieżącej gałęzi (e.g, 'main') lub null, jeśli HEAD jest odłączony.

Po podaniu nazwy gałęzi rozwiązuje ją do skrótu commita (ciągu szesnastkowego) lub zwraca null, jeśli gałąź nie istnieje.

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

branches

PHP
public function branches(): array

Zwraca posortowaną tablicę wszystkich nazw gałęzi (bez prefiksu refs/heads/).

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

tags

PHP
public function tags(): array

Zwraca posortowaną tablicę wszystkich nazw tagów (bez prefiksu refs/tags/).

resolve

PHP
public function resolve(string $revision): ObjectId

Rozwiąż wyrażenie rewizji do obiektu ObjectId. Obsługiwane są:

  • Pełne skróty szesnastkowe (40 znaków lub 64 dla SHA-256). Skrócone skróty, takie jak abc1234, nie są rozwiązywane.
  • HEAD
  • Nazwy gałęzi (main, feature/login)
  • Nazwy tagów (v1.0.0)
  • Pełne ścieżki referencji (refs/heads/main)
  • Wyrażenia rewizji (HEAD~3, main^2)

Zgłasza RuntimeException, jeśli nie można rozwiązać rewizji.

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

allRefs

PHP
public function allRefs(): array

Zwraca wszystkie referencje w postaci tablicy asocjacyjnej mapującej nazwy referencji na skróty szesnastkowe.

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

updateRef

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

Zaktualizuj referencję, aby wskazywała nowy cel.

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

createBranch

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

Utwórz nową gałąź. Jeśli $from ma wartość null, utwórz gałąź na podstawie bieżącego HEAD.

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

deleteBranch

PHP
public function deleteBranch(string $name): void

Usuń gałąź według nazwy. Zgłasza RuntimeException, jeśli gałąź jest wypisana lub nie istnieje. W przeciwieństwie do git branch -d nie sprawdza, czy gałąź została scalona.

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

createLightweightTag

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

Utwórz lekki tag. Jeśli $target ma wartość null, przypisz tag bezpośrednio do bieżącego HEAD.

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

Utwórz tag z adnotacją. Jeśli $target ma wartość null, przypisz tag do bieżącego HEAD. Zwraca ObjectId obiektu tagu.

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

deleteTag

PHP
public function deleteTag(string $name): void

Usuń tag według nazwy.

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

packRefs

PHP
public function packRefs(): void

Zapisz ponownie współdzielony plik packed-refs na podstawie bieżącego zestawu luźnych referencji i usuń odpowiadające im współdzielone luźne referencje. W przypadku powiązanych worktree zapis następuje we wspólnym katalogu git.

PHP
$repo->packRefs();

defaultBranch

PHP
public function defaultBranch(): string

Rozwiąż domyślną gałąź repozytorium. Najpierw sprawdza symboliczną referencję HEAD zdalnego repozytorium, potem lokalny HEAD, a na końcu przechodzi do main lub master.

isBranchMerged

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

Sprawdź, czy gałąź została w pełni scalona z inną gałęzią (domyślnie z gałęzią domyślną).

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

checkout

PHP
public function checkout(string $target): void

Przełącz gałęzie lub odłącz HEAD. Aktualizuje HEAD, indeks i drzewo robocze. $target może być nazwą gałęzi, tagiem, pełnym skrótem lub wyrażeniem rewizji; jeśli nie wskazuje gałęzi, HEAD zostaje odłączony.

Zgłasza RuntimeException, gdy zmiana lokalna (przygotowana lub nie) albo nieśledzony plik znajduje się w ścieżce, która różni się między bieżącym a docelowym drzewem.

Nieutrwalone zmiany w innych śledzonych plikach nie zostaną przeniesione: indeks i drzewo robocze są odtwarzane na podstawie docelowego drzewa, więc zmiany w plikach identycznych po obu stronach zostaną utracone, podczas gdy git by je zachował (#2). Najpierw je zatwierdź lub odłóż do schowka. merge(), cherryPick(), revert(), rebase() i metody bisect odtwarzają drzewo robocze w ten sam sposób.

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

Indeks

index

PHP
public function index(): Index

Odczytaj i zwróć bieżący indeks (obszar przygotowania) z .git/index.

add

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

Przygotuj pliki. Odczytuje każdy plik z drzewa roboczego, tworzy obiekt blob i aktualizuje indeks. Każdy argument musi być ścieżką pliku (lub dowiązania symbolicznego) względem katalogu głównego drzewa roboczego; katalogi i wzorce glob nie są rozwijane, a brakujący plik powoduje zgłoszenie RuntimeException.

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

remove

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

Usuń śledzone ścieżki zarówno z indeksu, jak i drzewa roboczego. Obsługuje --cached oraz -r / --recursive na liście argumentów, zapewniając działanie zgodne z 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

Przenieś lub zmień nazwę pliku zarówno w drzewie roboczym, jak i w indeksie.

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

Commity

commit

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

Utwórz commit na podstawie bieżącego indeksu. Buduje hierarchię drzewa z wpisów indeksu, tworzy obiekt commita z HEAD jako rodzicem (jeśli istnieje) i aktualizuje HEAD. Zwraca ObjectId nowego commita.

$message może mieć wartość null tylko wtedy, gdy scalanie, cherry-pick, cofanie lub rebase zostały wstrzymane z powodu konfliktu; przygotowana wiadomość zostanie wtedy użyta. W pozostałych przypadkach wiadomość null powoduje zgłoszenie RuntimeException('Commit message required'). Commit jest również zgłaszany, gdy indeks zawiera nierozstrzygnięte ścieżki, indeks jest pusty w repozytorium bez commitów lub drzewo jest niezmienione względem HEAD.

Parametr $author to pełny ciąg autora git (Name <email> timestamp timezone). Jeśli ma wartość null, jest ustalany na podstawie zmiennych środowiskowych, stałych i .git/config, w kolejności opisanej w Pierwsze kroki.

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

show

PHP
public function show(string $revision): array

Pokaż commit lub podobną do niego rewizję oraz różnice względem pierwszego rodzica. Gdy rewizja wskazuje na tag z adnotacją, zwracana wartość zawiera również ['tag' => Tag], a commit wskazuje na docelowy commit po rozwinięciu tagu.

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

Zresetuj HEAD do commita. Tryby:

  • 'soft': przesuń tylko HEAD
  • 'mixed': przesuń HEAD i zresetuj indeks (domyślnie)
  • 'hard': przesuń HEAD, zresetuj indeks i zresetuj drzewo robocze
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

Przywróć ścieżkę z indeksu lub wskazanej rewizji źródłowej. Jeśli nie ustawiono żadnej z flag, Pitmaster przywraca drzewo robocze z indeksu (lub z $source, jeśli podano). staged: true przywraca indeks z HEAD (lub $source), pozostawiając drzewo robocze bez zmian; przekaż staged: true, worktree: true, aby przywrócić oba.

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

Zastosuj commit jako nowy commit w bieżącej gałęzi, zachowując pierwotnego autora. Jeśli konflikty wstrzymają operację, rozwiąż je, przygotuj ścieżki, a następnie wywołaj cherryPickContinue() lub 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

Utwórz commit cofający inny commit. Jeśli konflikt wstrzyma cofanie, rozwiąż go, przygotuj ścieżki, a następnie wywołaj revertContinue() lub 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

Wykonaj rebase bieżącej gałęzi na podstawie innej rewizji. Pitmaster obsługuje obecnie rebase liniowe ze stanem zatrzymania z powodu konfliktów zgodnym z Git oraz kontynuowanie, przerywanie i pomijanie operacji. HEAD musi wskazywać gałąź.

rebase(), rebaseContinue() i rebaseSkip() zwracają ['success' => bool, 'commits' => int, 'conflicts' => list<string>]: informację, czy rebase się zakończył, liczbę zastosowanych commitów oraz ścieżki powodujące konflikt, jeśli operacja została wstrzymana.

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

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

Stan

status

PHP
public function status(): array

Oblicz stan drzewa roboczego. Zwraca tablicę obiektów StatusEntry, z których każdy zawiera:

  • path: ścieżkę pliku
  • index: wyliczenie FileStatus dla zmian między HEAD a indeksem
  • worktree: wyliczenie FileStatus dla zmian między indeksem a drzewem roboczym
  • origPath, renameScore: ustawione dla zmienionych nazw wpisów, w przeciwnym razie null

Nieśledzone pliki mają FileStatus::Untracked w obu kolumnach. Ignorowane pliki nie są zgłaszane.

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

statusPorcelainV2

PHP
public function statusPorcelainV2(): string

Wyjście stanu czytelne dla maszyn, w formacie porcelain v2 systemu git.

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

Różnice

diff

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

Porównaj drzewo robocze z indeksem (zmiany nieprzygotowane). Zwraca tablicę obiektów DiffResult. $pathspec filtruje wyniki według jednej dokładnej ścieżki pliku. $algorithm ma wartość 'myers' (domyślnie), 'patience', 'histogram' lub 'minimal'; każda inna wartość powoduje zgłoszenie 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

Porównaj indeks z HEAD (zmiany przygotowane). Zwraca DiffResult[] z wykrywaniem zmian nazw między usuniętymi a dodanymi plikami.

Argument $pathspec jest obecnie ignorowany, więc zwracany jest każdy przygotowany plik. Przed pierwszym commitem metoda zwraca pustą tablicę (#5).

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

diffTree

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

Porównaj dwa drzewa na podstawie ich ObjectId. Zwraca DiffResult[]. Przekaż identyfikatory drzew, a nie commitów: identyfikator commita nie jest odczytywany jako drzewo i daje pusty wynik.

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

Historia

log

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

Przejdź historię commitów, zaczynając od najnowszych według znacznika czasu committera. Zwraca Commit[]. Jeśli $from ma wartość null, zaczyna od HEAD. Zwraca pustą tablicę, jeśli HEAD nie wskazuje jeszcze żadnego commita.

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

logAll

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

Przejdź commity osiągalne z każdej referencji i HEAD, zaczynając od najnowszych. Zwraca Commit[].

logOneline

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

Zwróć wiersze dziennika w formacie git log --oneline (abc1234 Subject), z HEAD, ze wszystkich referencji ($all) lub przefiltrowane według ścieżki.

logPath

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

Dziennik przefiltrowany według ścieżki pliku. Zwraca tylko te commity, których różnice względem pierwszego rodzica dodają, modyfikują, usuwają lub zmieniają nazwę dokładnie tego pliku. Ścieżki katalogów nie są dopasowywane.

Sprawdzanych jest tylko 5 * $limit najnowszych commitów, więc starsze commity dotyczące pliku mogą nie pojawić się w wynikach (#7).

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

Scalanie

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

Scal gałąź (lub dowolną rewizję) z HEAD. Automatycznie wykrywa scalenia typu fast-forward. W przypadku scalenia bez fast-forward sprawdza konflikty na poziomie drzewa i tworzy commit scalający, jeśli nie ma konfliktów. Gdy wystąpi konflikt, zapisuje w indeksie i drzewie roboczym stan scalania zgodny z Git; rozwiąż konflikty, przygotuj ścieżki, a następnie wywołaj mergeContinue() lub mergeAbort().

$strategy 'ours' zapisuje commit scalający, który zachowuje drzewo HEAD; każda inna wartość powoduje użycie domyślnego scalania rekurencyjnego. mergeOctopus() scala co najmniej dwie gałęzie w jeden commit. Jeśli wystąpi konflikt w którejkolwiek gałęzi, zwraca wynik wskazujący na nieudane scalanie bez zapisywania stanu scalania ani tworzenia commita.

Scalenie gałęzi, która jest już zawarta w HEAD, tworzy kolejny commit scalający zamiast zgłosić „Already up to date” (#6). Niezatwierdzone zmiany w śledzonych plikach są nadpisywane, jak opisano w sekcji checkout().

Zwraca MergeResult z:

  • clean: informacją, czy scalanie zakończyło się bez konfliktów
  • commitId: identyfikatorem commita scalającego (jeśli scalanie przebiegło czysto)
  • conflictPaths: tablicą ścieżek do plików powodujących konflikt (jeśli wystąpił konflikt)
  • mergedContents: ścieżką do pliku z zawartością i znacznikami konfliktu (jeśli wystąpił konflikt)
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

Znajduje bazę scalania (najniższego wspólnego przodka) dwóch commitów. Zwraca null, jeśli nie istnieje wspólny przodek.

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

Bisekcja

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

Wyszukiwanie binarne commita, który wprowadził zmianę. bisectStart() zapisuje błędne i poprawne rewizje, przełącza się na pierwszego kandydata i go zwraca. bisectGood() i bisectBad() oznaczają bieżący HEAD (lub $revision), a następnie przełączają się na kolejnego kandydata i go zwracają. Gdy pozostaje jeden podejrzany commit, zostaje on zwrócony i nadal jest kandydatem: to pierwszy błędny commit. bisectReset() kończy sesję i wraca do gałęzi lub commita, od którego się rozpoczęła.

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

Sieć

fetch

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

Pobiera dane ze zdalnego repozytorium. Pobiera nowe obiekty i aktualizuje zdalne referencje śledzące. Przekaż $depth, aby pogłębić płytką historię lub ograniczyć jej zakres.

fetch() i metody push*() zgłaszają RuntimeException dla uchwytu otwartego z ['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

Wysyła bieżącą gałąź (lub wskazaną gałąź) do zdalnego repozytorium. Dostępne są warianty force-with-lease, atomic i mirror, które zapewniają ściślejszą kontrolę lub szerszą aktualizację referencji.

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

Drzewa robocze

addWorktree

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

Dodaje powiązane drzewo robocze. Tworzy gałąź, jeśli jeszcze nie istnieje, konfiguruje metadane drzewa roboczego i tworzy pliki w drzewie roboczym. Przekaż $name, gdy potrzebujesz deterministycznego sluga metadanych, który różni się od nazwy katalogu kopii roboczej.

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

Usuwa powiązane drzewo robocze. Użyj $force = true, aby usunąć je nawet wtedy, gdy jest zablokowane.

worktrees

PHP
public function worktrees(): array

Wyświetla wszystkie drzewa robocze (główne i powiązane). Zwraca Worktree[].

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

Konfiguracja

config

PHP
public function config(): GitConfig

Umożliwia dostęp do konfiguracji git repozytorium. Odczytuje i zapisuje wartości konfiguracji.

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

Dostęp wewnętrzny

Te metody udostępniają komponenty wewnętrzne do zaawansowanych zastosowań.

objectDatabase

PHP
public function objectDatabase(): ObjectDatabase

Umożliwia dostęp do surowej bazy obiektów (luźne obiekty i magazyny pakietów).

refDatabase

PHP
public function refDatabase(): RefDatabase

Umożliwia dostęp do surowej bazy referencji (luźne i spakowane referencje).

Klasy niższego poziomu

Te klasy nie są opakowane przez Repository i są tworzone na podstawie jego komponentów wewnętrznych.

Pitmaster\Graph\Blame

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

Zwraca po jednym wpisie na każdy wiersz $path w $headId: ['line' => int, 'hash' => string, 'author' => string, 'content' => string]. author to pełny ciąg identyfikacyjny (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

Przeszukuje bloby drzewa. Zwraca ['path' => string, 'line' => int, 'content' => string] dla każdego pasującego wiersza. Opcje: regex (traktuje wzorzec jako wzorzec PCRE) oraz ignore_case. Nieprawidłowe wyrażenie regularne powoduje zgłoszenie 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

Odczytuje i zapisuje notatki git przechowywane pod referencją notes. listAll() zwraca mapowanie skrótów commitów na treść notatek.

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