PHP API

Pitmaster\Pitmaster

Η κλάση Pitmaster\Pitmaster είναι το στατικό σημείο εισόδου. Παρέχει μεθόδους factory για το άνοιγμα, τη δημιουργία και την κλωνοποίηση αποθετηρίων, καθώς και βοηθητικές μεθόδους εντοπισμού.

use Pitmaster\Pitmaster;

open

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

Ανοίγει ένα υπάρχον αποθετήριο στη θέση $path. Η διαδρομή πρέπει να είναι η ρίζα του working tree (που περιέχει το .git/). Υποστηρίζει επίσης συνδεδεμένα worktrees (όπου το .git είναι αρχείο που περιέχει το gitdir: <path>) και γυμνά αποθετήρια (όπου το $path είναι ο ίδιος ο κατάλογος .git).

Το $options δέχεται δύο boolean τιμές, και οι δύο true από προεπιλογή:

• hooks: εκτελεί scripts .git/hooks. Περάστε false για να τα παραλείψετε για αυτό το handle.
• processes: επιτρέπει οτιδήποτε εκκινεί διεργασία ή ανοίγει μεταφορά δικτύου. Περάστε false για να απενεργοποιήσετε τα hooks, το hook fsmonitor, το clone, το fetch, το push και τη μεταφορά διεργασίας SSH. Οι τοπικές αναγνώσεις και εγγραφές εξακολουθούν να λειτουργούν.

Προκαλεί InvalidArgumentException αν η διαδρομή δεν είναι αποθετήριο git.

$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

Αρχικοποιεί ένα νέο αποθετήριο στη θέση $path. Δημιουργεί τη δομή καταλόγου .git με τα objects/, refs/heads/, refs/tags/, hooks/, info/, HEAD (που δείχνει στο refs/heads/main) και ένα προεπιλεγμένο config.

Το $objectFormat είναι 'sha1' ή 'sha256'. Ένα αποθετήριο SHA-256 λαμβάνει τα repositoryformatversion = 1 και extensions.objectformat = sha256 στις ρυθμίσεις του. Κάθε άλλη τιμή προκαλεί InvalidArgumentException. Το $options δέχεται τα ίδια κλειδιά με το open().

Προκαλεί RuntimeException αν υπάρχει ήδη αποθετήριο στη διαδρομή.

$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

Κλωνοποιεί ένα απομακρυσμένο αποθετήριο. Αρχικοποιεί ένα νέο αποθετήριο, εντοπίζει απομακρυσμένα refs, ανακτά το αρχείο pack, ρυθμίζει κλάδους παρακολούθησης απομακρυσμένων και δημιουργεί το working tree. Οι διευθύνσεις URL SSH (ssh://... ή user@host:path) χρησιμοποιούν τη μεταφορά SSH· οι υπόλοιπες διευθύνσεις URL χρησιμοποιούν smart HTTP και επιστρέφουν σε dumb HTTP όταν αποτύχει η smart ανταλλαγή. Περάστε το $depth για ρηχό clone.

Προκαλεί RuntimeException όταν το $options['processes'] είναι false. Αν το clone αποτύχει και το $path δεν υπήρχε προηγουμένως, ο κατάλογος που δημιουργήθηκε εν μέρει αφαιρείται.

$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

Επιστρέφει ['processes' => false, 'hooks' => false], για περιβάλλοντα εκτέλεσης που δεν πρέπει να εκκινούν διεργασίες του συστήματος. Περάστε το στο open() ή στο init().

isRepository

public static function isRepository(string $path): bool

Ελέγχει αν μια διαδρομή είναι αποθετήριο git. Επιστρέφει true για κανονικά αποθετήρια (κατάλογος .git/), συνδεδεμένα worktrees (αρχείο .git) και γυμνά αποθετήρια (υπάρχει το αρχείο HEAD).

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

isWorktree

public static function isWorktree(string $path): bool

Ελέγχει αν μια διαδρομή είναι συνδεδεμένο worktree (όχι το κύριο αποθετήριο). Επιστρέφει true μόνο αν το .git είναι αρχείο που περιέχει αναφορά gitdir:.

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

commonGitDir

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

Επιλύει τον κοινό κατάλογο git από οποιαδήποτε διαδρομή checkout. Για κανονικά αποθετήρια, είναι ο κατάλογος .git. Για συνδεδεμένα worktrees, είναι ο κοινόχρηστος κατάλογος git που περιέχει τα αντικείμενα, τις ρυθμίσεις και τα packed-refs. Επιστρέφει null αν η διαδρομή δεν είναι αποθετήριο.

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

Pitmaster\Repository

Η κλάση Pitmaster\Repository είναι το κύριο handle για όλες τις λειτουργίες git. Αποκτήστε ένα μέσω των Pitmaster::open(), Pitmaster::init() ή Pitmaster::clone().

use Pitmaster\Repository;

Accessors διαδρομών

gitDir

public function gitDir(): string

Επιστρέφει τον κατάλογο git ανά worktree. Για κανονικά αποθετήρια είναι το .git/. Για συνδεδεμένα worktrees, είναι το .git/worktrees/<name>/.

commonGitDir

public function commonGitDir(): string

Επιστρέφει τον κοινόχρηστο κατάλογο git. Για κανονικά αποθετήρια είναι το ίδιο με το gitDir(). Για συνδεδεμένα worktrees, είναι ο κατάλογος .git/ του κύριου αποθετηρίου (όπου βρίσκονται τα αντικείμενα, οι ρυθμίσεις και τα packed-refs).

workDir

public function workDir(): string

Επιστρέφει τη διαδρομή της ρίζας του working tree.

isLinkedWorktree

public function isLinkedWorktree(): bool

Επιστρέφει true αν αυτό το handle αποθετηρίου είναι συνδεδεμένο worktree.

isBare, hooksEnabled, processesEnabled

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

Αναφέρει αν το αποθετήριο δεν έχει working tree και ποιες από τις επιλογές hooks / processes ισχύουν για αυτό το handle. Το hooksEnabled() είναι false όποτε οι διεργασίες είναι απενεργοποιημένες.

Αντικείμενα

readObject

public function readObject(string $hash): GitObject

Διαβάζει οποιοδήποτε αντικείμενο με το πλήρες δεκαεξαδικό hash του (40 χαρακτήρες ή 64 σε αποθετήριο SHA-256). Δεν γίνονται δεκτά συντομευμένα hash. Επιστρέφει μια παρουσία Blob, Tree, Commit ή Tag. Αναζητά πρώτα στα loose objects και έπειτα στα αρχεία pack.

Προκαλεί ObjectNotFoundException αν δεν βρεθεί το hash.

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

writeObject

public function writeObject(GitObject $object): ObjectId

Γράφει ένα αντικείμενο στο αποθετήριο loose objects. Επιστρέφει το υπολογισμένο ObjectId.

use Pitmaster\Object\Blob;

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

catFile

public function catFile(string $hash): string

Επιστρέφει το ακατέργαστο περιεχόμενο ενός αντικειμένου, ισοδύναμο με το git cat-file -p.

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

objectExists

public function objectExists(string $hash): bool

Ελέγχει αν υπάρχει ένα αντικείμενο στο αποθετήριο (loose ή packed).

listObjects

public function listObjects(): array

Παραθέτει όλα τα hash αντικειμένων στο αποθετήριο. Επιστρέφει έναν πίνακα από δεκαεξαδικές συμβολοσειρές.

Αναφορές

head

public function head(): Commit

Επιστρέφει το τρέχον commit του HEAD. Ακολουθεί συμβολικά refs (HEAD -> refs/heads/main -> hash commit).

Προκαλεί RuntimeException αν το HEAD δεν δείχνει σε έγκυρο commit (π.χ. e.g, κενό αποθετήριο).

branch

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

Χωρίς ορίσματα, επιστρέφει το όνομα του τρέχοντος κλάδου (π.χ. e.g, 'main') ή null αν το HEAD είναι αποσυνδεδεμένο.

Με όνομα κλάδου, το επιλύει στο hash commit του (δεκαεξαδική συμβολοσειρά) ή επιστρέφει null αν ο κλάδος δεν υπάρχει.

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

branches

public function branches(): array

Επιστρέφει έναν ταξινομημένο πίνακα με όλα τα ονόματα κλάδων (χωρίς το πρόθεμα refs/heads/).

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

tags

public function tags(): array

Επιστρέφει έναν ταξινομημένο πίνακα με όλα τα ονόματα ετικετών (χωρίς το πρόθεμα refs/tags/).

resolve

public function resolve(string $revision): ObjectId

Επιλύει μια έκφραση αναθεώρησης σε ObjectId. Υποστηρίζει:

• Πλήρη δεκαεξαδικά hash (40 χαρακτήρες ή 64 για SHA-256). Δεν επιλύονται συντομευμένα hash όπως το abc1234.
• HEAD
• Ονόματα κλάδων (main, feature/login)
• Ονόματα ετικετών (v1.0.0)
• Πλήρεις διαδρομές ref (refs/heads/main)
• Εκφράσεις αναθεώρησης (HEAD~3, main^2)

Προκαλεί RuntimeException αν δεν είναι δυνατή η επίλυση της αναθεώρησης.

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

allRefs

public function allRefs(): array

Επιστρέφει όλα τα refs ως συσχετιστικό πίνακα από όνομα ref σε δεκαεξαδικό hash.

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

updateRef

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

Ενημερώνει ένα ref ώστε να δείχνει σε νέο στόχο.

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

createBranch

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

Δημιουργεί έναν νέο κλάδο. Αν το $from είναι null, δημιουργεί κλάδο από το τρέχον HEAD.

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

deleteBranch

public function deleteBranch(string $name): void

Διαγράφει έναν κλάδο με βάση το όνομά του. Προκαλεί RuntimeException αν ο κλάδος έχει γίνει checkout ή δεν υπάρχει. Σε αντίθεση με το git branch -d, δεν ελέγχει αν ο κλάδος έχει συγχωνευθεί.

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

createLightweightTag

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

Δημιουργεί μια ελαφριά ετικέτα. Αν το $target είναι null, προσθέτει ετικέτα απευθείας στο τρέχον HEAD.

$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

Δημιουργεί μια σχολιασμένη ετικέτα. Αν το $target είναι null, προσθέτει ετικέτα στο τρέχον HEAD. Επιστρέφει το ObjectId του αντικειμένου ετικέτας.

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

deleteTag

public function deleteTag(string $name): void

Διαγράφει μια ετικέτα με βάση το όνομά της.

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

packRefs

public function packRefs(): void

Επανεγγράφει το κοινόχρηστο αρχείο packed-refs από το τρέχον σύνολο loose refs και αφαιρεί τα αντίστοιχα κοινόχρηστα loose refs. Για συνδεδεμένα worktrees, γράφει στον κοινό κατάλογο git.

$repo->packRefs();

defaultBranch

public function defaultBranch(): string

Επιλύει τον προεπιλεγμένο κλάδο του αποθετηρίου. Ελέγχει πρώτα το συμβολικό ref του απομακρυσμένου HEAD, έπειτα το τοπικό HEAD και τέλος καταφεύγει στο main ή στο master.

isBranchMerged

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

Ελέγχει αν ένας κλάδος έχει συγχωνευθεί πλήρως σε άλλον κλάδο (από προεπιλογή, στον προεπιλεγμένο κλάδο).

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

checkout

public function checkout(string $target): void

Αλλάζει κλάδο ή αποσυνδέει το HEAD. Ενημερώνει τα HEAD, index και working tree. Το $target είναι όνομα κλάδου, ετικέτα, πλήρες hash ή έκφραση αναθεώρησης· οτιδήποτε δεν είναι κλάδος αποσυνδέει το HEAD.

Προκαλεί RuntimeException όταν μια τοπική αλλαγή (σε στάδιο ή όχι) ή ένα αρχείο που δεν παρακολουθείται βρίσκεται σε διαδρομή που διαφέρει ανάμεσα στο τρέχον και το στοχευόμενο δέντρο.

Οι μη υποβληθείσες αλλαγές σε άλλα αρχεία που παρακολουθούνται δεν διατηρούνται: το index και το working tree αναδημιουργούνται από το δέντρο-στόχο, επομένως οι επεξεργασίες σε αρχεία που είναι ίδια και στις δύο πλευρές χάνονται, ενώ το git θα τις διατηρούσε (#2). Κάντε πρώτα commit ή stash τις αλλαγές. Τα merge(), cherryPick(), revert(), rebase() και οι μέθοδοι bisect αναδημιουργούν το working tree με τον ίδιο τρόπο.

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

Ευρετήριο

index

public function index(): Index

Διαβάζει και επιστρέφει το τρέχον index (περιοχή σταδιοποίησης) από το .git/index.

add

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

Σταδιοποιεί αρχεία. Διαβάζει κάθε αρχείο από το working tree, δημιουργεί ένα αντικείμενο blob και ενημερώνει το index. Κάθε όρισμα πρέπει να είναι διαδρομή αρχείου (ή συμβολικού συνδέσμου) σχετική με τη ρίζα του working tree· οι κατάλογοι και τα glob δεν επεκτείνονται, ενώ αν λείπει κάποιο αρχείο προκαλείται RuntimeException.

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

remove

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

Αφαιρεί διαδρομές που παρακολουθούνται τόσο από το index όσο και από το working tree. Υποστηρίζει τα --cached και -r / --recursive στη λίστα ορισμάτων για συμπεριφορά τύπου Git.

$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

Μετακινεί/μετονομάζει ένα αρχείο τόσο στο working tree όσο και στο index.

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

Υποβολές αλλαγών

commit

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

Δημιουργεί ένα commit από το τρέχον index. Δημιουργεί μια ιεραρχία δέντρων από τις εγγραφές του index, δημιουργεί το αντικείμενο commit με γονέα το HEAD (αν υπάρχει) και ενημερώνει το HEAD. Επιστρέφει το ObjectId του νέου commit.

Το $message μπορεί να είναι null μόνο όταν μια συγχώνευση, επιλογή commit, αναίρεση ή αναδιάταξη έχει σταματήσει λόγω διένεξης· τότε χρησιμοποιείται το προετοιμασμένο μήνυμα. Διαφορετικά, ένα μήνυμα null προκαλεί RuntimeException('Commit message required'). Το commit προκαλεί επίσης σφάλμα όταν το index περιέχει μη συγχωνευμένες διαδρομές, όταν το index είναι κενό σε αποθετήριο χωρίς commits και όταν το δέντρο δεν έχει αλλάξει από το HEAD.

Η παράμετρος $author είναι μια πλήρης συμβολοσειρά συντάκτη git (Name <email> timestamp timezone). Αν είναι null, επιλύεται από μεταβλητές περιβάλλοντος, σταθερές και το .git/config, με τη σειρά που περιγράφεται στην ενότητα Έναρξη.

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

show

public function show(string $revision): array

Εμφανίζει ένα commit-ish και τις διαφορές του από τον πρώτο γονέα. Όταν η αναθεώρηση επιλύεται σε σχολιασμένη ετικέτα, η τιμή επιστροφής περιλαμβάνει επίσης το ['tag' => Tag] και το commit είναι το 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 σε ένα commit. Λειτουργίες:

• 'soft': μετακινεί μόνο το HEAD
• 'mixed': μετακινεί το HEAD και επαναφέρει το index (προεπιλογή)
• 'hard': μετακινεί το HEAD, επαναφέρει το index και επαναφέρει το working tree

$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

Επαναφέρει μια διαδρομή από το index ή από συγκεκριμένη αναθεώρηση πηγής. Αν δεν έχει οριστεί καμία από τις δύο σημαίες, το Pitmaster επαναφέρει το worktree από το index (ή από το $source, αν δοθεί). Το staged: true επαναφέρει το index από το HEAD (ή από το $source) και αφήνει το worktree ανέπαφο· περάστε το staged: true, worktree: true για να επαναφέρετε και τα δύο.

$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

Εφαρμόζει ένα commit ως νέο commit στον τρέχοντα κλάδο, διατηρώντας τον αρχικό συντάκτη. Αν η λειτουργία σταματήσει λόγω διενέξεων, επιλύστε τις, σταδιοποιήστε τις διαδρομές και έπειτα καλέστε το cherryPickContinue() ή το cherryPickAbort().

$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

Δημιουργεί ένα commit που αναιρεί άλλο commit. Αν η αναίρεση σταματήσει λόγω διενέξεων, επιλύστε τις, σταδιοποιήστε τις διαδρομές και έπειτα καλέστε το revertContinue() ή το revertAbort().

$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

Αναδιατάσσει τον τρέχοντα κλάδο πάνω σε άλλη αναθεώρηση. Το Pitmaster καλύπτει προς το παρόν γραμμικές αναδιατάξεις με κατάσταση διακοπής τύπου Git για διενέξεις, καθώς και συνέχιση, ακύρωση και παράλειψη. Το HEAD πρέπει να δείχνει σε κλάδο.

Τα rebase(), rebaseContinue() και rebaseSkip() επιστρέφουν ['success' => bool, 'commits' => int, 'conflicts' => list<string>]: αν ολοκληρώθηκε η αναδιάταξη, πόσα commits εφαρμόστηκαν και ποιες διαδρομές είχαν διενέξεις όταν σταμάτησε.

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

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

Κατάσταση

status

public function status(): array

Υπολογίζει την κατάσταση του working tree. Επιστρέφει έναν πίνακα από αντικείμενα StatusEntry, καθένα από τα οποία περιέχει:

• path: τη διαδρομή αρχείου
• index: enum FileStatus για αλλαγές από HEAD προς index
• worktree: enum FileStatus για αλλαγές από index προς worktree
• origPath, renameScore: ορίζονται για μετονομασμένες εγγραφές, διαφορετικά null

Τα αρχεία που δεν παρακολουθούνται έχουν FileStatus::Untracked και στις δύο στήλες. Τα αρχεία που αγνοούνται δεν αναφέρονται.

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

statusPorcelainV2

public function statusPorcelainV2(): string

Έξοδος κατάστασης σε μορφή αναγνώσιμη από μηχανές, σύμφωνα με τη μορφή porcelain v2 του git.

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

Διαφορές

diff

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

Συγκρίνει το working tree με το index (αλλαγές που δεν έχουν σταδιοποιηθεί). Επιστρέφει έναν πίνακα από αντικείμενα DiffResult. Το $pathspec φιλτράρει βάσει μίας ακριβούς διαδρομής αρχείου. Το $algorithm είναι 'myers' (προεπιλογή), 'patience', 'histogram' ή 'minimal'· οποιαδήποτε άλλη τιμή προκαλεί InvalidArgumentException.

$diffs = $repo->diff();

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

diffStaged

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

Συγκρίνει το index με το HEAD (σταδιοποιημένες αλλαγές). Επιστρέφει DiffResult[], με εντοπισμό μετονομασιών μεταξύ διαγραμμένων και προστεθειμένων αρχείων.

Το όρισμα $pathspec αγνοείται προς το παρόν, επομένως επιστρέφεται κάθε σταδιοποιημένο αρχείο, ενώ η μέθοδος επιστρέφει κενό πίνακα πριν από το πρώτο commit (#5).

$staged = $repo->diffStaged();

diffTree

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

Συγκρίνει δύο δέντρα με βάση το ObjectId τους. Επιστρέφει DiffResult[]. Περάστε αναγνωριστικά δέντρων, όχι αναγνωριστικά commit: ένα αναγνωριστικό commit δεν διαβάζεται ως δέντρο και έχει ως αποτέλεσμα κενό.

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

Αρχείο καταγραφής

log

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

Διατρέχει το ιστορικό commit, με πρώτο το νεότερο βάσει της χρονοσφραγίδας του συντάκτη. Επιστρέφει Commit[]. Αν το $from είναι null, ξεκινά από το HEAD. Επιστρέφει κενό πίνακα αν το HEAD δεν έχει ακόμη commit.

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

logAll

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

Διατρέχει τα commit που είναι προσβάσιμα από κάθε ref και το HEAD, με πρώτο το νεότερο. Επιστρέφει Commit[].

logOneline

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

Επιστρέφει γραμμές αρχείου καταγραφής σε μορφή git log --oneline (abc1234 Subject), από το HEAD, από όλα τα refs ($all) ή φιλτραρισμένες βάσει διαδρομής.

logPath

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

Φιλτράρει το αρχείο καταγραφής με βάση διαδρομή αρχείου. Επιστρέφει μόνο commit των οποίων η διαφορά από τον πρώτο γονέα προσθέτει, τροποποιεί, διαγράφει ή μετονομάζει το συγκεκριμένο αρχείο. Οι διαδρομές καταλόγων δεν αντιστοιχίζονται.

Εξετάζονται μόνο τα νεότερα 5 * $limit commit, επομένως παλαιότερα commit που επηρεάζουν το αρχείο μπορεί να λείπουν από το αποτέλεσμα (#7).

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

Συγχώνευση

merge

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

Συγχωνεύει έναν κλάδο (ή οποιαδήποτε αναθεώρηση) στο HEAD. Εντοπίζει αυτόματα τις συγχωνεύσεις fast-forward. Για συγχωνεύσεις που δεν είναι fast-forward, εκτελεί εντοπισμό διενέξεων σε επίπεδο δέντρου και δημιουργεί commit συγχώνευσης αν δεν υπάρχουν διενέξεις. Αν προκύψουν διενέξεις, η διαδικασία σταματά και γράφει την κατάσταση συγχώνευσης τύπου Git στο index και στο worktree· επιλύστε τις διαδρομές, σταδιοποιήστε τις και έπειτα καλέστε το mergeContinue() ή το mergeAbort().

Το $strategy 'ours' καταγράφει ένα commit συγχώνευσης που διατηρεί το δέντρο του HEAD· οποιαδήποτε άλλη τιμή χρησιμοποιεί την προεπιλεγμένη αναδρομική συγχώνευση. Το mergeOctopus() συγχωνεύει δύο ή περισσότερους κλάδους σε ένα commit. Αν οποιοσδήποτε κλάδος έχει διενέξεις, επιστρέφει αποτέλεσμα με διενέξεις, χωρίς να γράψει κατάσταση συγχώνευσης ή να δημιουργήσει commit.

Η συγχώνευση ενός κλάδου που περιλαμβάνεται ήδη στο HEAD δημιουργεί άλλο ένα commit συγχώνευσης αντί να εμφανίσει «Already up to date» (#6). Οι μη δεσμευμένες αλλαγές σε παρακολουθούμενα αρχεία αντικαθίστανται, όπως περιγράφεται στην ενότητα checkout().

Επιστρέφει ένα MergeResult με:

• clean: αν η συγχώνευση ολοκληρώθηκε χωρίς διενέξεις
• commitId: το ID του commit συγχώνευσης (αν ολοκληρώθηκε καθαρά)
• conflictPaths: πίνακα διαδρομών αρχείων με διενέξεις (αν δεν ολοκληρώθηκε καθαρά)
• mergedContents: αντιστοίχιση διαδρομής με το περιεχόμενο του αρχείου που περιέχει δείκτες διένεξης (αν δεν ολοκληρώθηκε καθαρά)

$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

Εντοπίζει τη βάση συγχώνευσης (τον χαμηλότερο κοινό πρόγονο) δύο commit. Επιστρέφει null αν δεν υπάρχει κοινός πρόγονος.

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

Δυαδική αναζήτηση

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

Εκτελεί δυαδική αναζήτηση για το commit που εισήγαγε μια αλλαγή. Το bisectStart() καταγράφει τις κακές και καλές αναθεωρήσεις, κάνει checkout του πρώτου υποψηφίου και τον επιστρέφει. Τα bisectGood() και bisectBad() ορίζουν το τρέχον HEAD (ή το $revision) και κάνουν checkout του επόμενου υποψηφίου, τον οποίο και επιστρέφουν. Όταν απομείνει ένας μόνο ύποπτος, επιστρέφεται αυτό το commit και παραμένει ο υποψήφιος: είναι το πρώτο κακό commit. Το bisectReset() τερματίζει τη συνεδρία και επιστρέφει στον κλάδο ή στο commit από όπου ξεκίνησε.

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

Δίκτυο

fetch

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

Κάνει λήψη από απομακρυσμένο αποθετήριο. Κατεβάζει νέα αντικείμενα και ενημερώνει τις αναφορές παρακολούθησης απομακρυσμένων κλάδων. Περάστε το $depth για να επεκτείνετε ή να περιορίσετε το ρηχό ιστορικό.

Οι μέθοδοι fetch() και push*() προκαλούν RuntimeException σε handle που ανοίχτηκε με ['processes' => false].

$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

Στέλνει τον τρέχοντα κλάδο (ή έναν καθορισμένο κλάδο) σε απομακρυσμένο αποθετήριο. Διατίθενται οι παραλλαγές force-with-lease, atomic και mirror για αυστηρότερες ή ευρύτερες ενημερώσεις αναφορών.

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

Δέντρα εργασίας

addWorktree

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

Προσθέτει ένα συνδεδεμένο worktree. Δημιουργεί τον κλάδο αν δεν υπάρχει, ρυθμίζει τα μεταδεδομένα του worktree και δημιουργεί τα αρχεία του δέντρου εργασίας. Περάστε το $name όταν χρειάζεστε ένα ντετερμινιστικό slug μεταδεδομένων διαφορετικό από το βασικό όνομα του καταλόγου checkout.

$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

Αφαιρεί ένα συνδεδεμένο worktree. Χρησιμοποιήστε το $force = true για αφαίρεση ακόμη κι αν είναι κλειδωμένο.

worktrees

public function worktrees(): array

Εμφανίζει όλα τα worktree (κύριο και συνδεδεμένα). Επιστρέφει Worktree[].

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

Ρυθμίσεις

config

public function config(): GitConfig

Πρόσβαση στη διαμόρφωση git του αποθετηρίου. Ανάγνωση και εγγραφή τιμών διαμόρφωσης.

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

Εσωτερική πρόσβαση

Αυτές οι μέθοδοι παρέχουν πρόσβαση σε εσωτερικά στοιχεία για προχωρημένες περιπτώσεις χρήσης.

objectDatabase

public function objectDatabase(): ObjectDatabase

Πρόσβαση στην ακατέργαστη βάση δεδομένων αντικειμένων (χαλαρές και pack αποθήκες).

refDatabase

public function refDatabase(): RefDatabase

Πρόσβαση στην ακατέργαστη βάση δεδομένων αναφορών (χαλαρές και συσκευασμένες αναφορές).

Κλάσεις χαμηλότερου επιπέδου

Αυτές οι κλάσεις δεν περιβάλλονται από το Repository και δημιουργούνται από τα εσωτερικά στοιχεία του.

Pitmaster\Graph\Blame

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

Επιστρέφει μία εγγραφή ανά γραμμή του $path στο $headId: ['line' => int, 'hash' => string, 'author' => string, 'content' => string]. Το author είναι η πλήρης συμβολοσειρά ταυτότητας (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

Αναζητά στα blobs ενός δέντρου. Επιστρέφει ['path' => string, 'line' => int, 'content' => string] ανά γραμμή που ταιριάζει. Επιλογές: regex (αντιμετωπίζει το μοτίβο ως μοτίβο PCRE) και ignore_case. Μη έγκυρη κανονική έκφραση προκαλεί InvalidArgumentException.

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

Διαβάζει και γράφει σημειώσεις git αποθηκευμένες σε αναφορά σημειώσεων. Το listAll() επιστρέφει αντιστοίχιση από κατακερματισμό commit σε περιεχόμενο σημείωσης.

use Pitmaster\Ref\Notes;

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