Ξεκινώντας

Εγκατάσταση

Εγκαταστήστε το Pitmaster μέσω Composer:

composer require pitmaster/pitmaster

Απαιτήσεις

• PHP 8.2+ με κλάσεις μόνο για ανάγνωση, enums και προώθηση κατασκευαστή
• ext-zlib για συμπίεση/αποσυμπίεση αντικειμένων (ενσωματωμένο στις περισσότερες εγκαταστάσεις)
• ext-json για αρχεία κατάστασης λειτουργιών και ωφέλιμα φορτία Git LFS API
• ext-mbstring, δηλωμένο στο composer.json, επομένως το Composer το απαιτεί κατά την εγκατάσταση
• ext-ctype για επικύρωση hash (ενεργοποιημένο στις περισσότερες εκδόσεις PHP, αλλά δεν δηλώνεται στο composer.json)

Οι βασικές λειτουργίες αποθετηρίου δεν απαιτούν το εκτελέσιμο git, FFI ή εξωτερικά βοηθητικά εργαλεία. Οι προαιρετικές δυνατότητες έχουν πρόσθετες απαιτήσεις εκτέλεσης: η εκτέλεση hook χρησιμοποιεί proc_open(), ενώ η μεταφορά SSH χρησιμοποιεί ext-ssh2 όταν έχει φορτωθεί· διαφορετικά εκκινεί το εκτελέσιμο ssh του συστήματος μέσω του proc_open().

Άνοιγμα υπάρχοντος αποθετηρίου

use Pitmaster\Pitmaster;

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

Αυτό ανοίγει το αποθετήριο στη δεδομένη διαδρομή. Το Pitmaster εντοπίζει τον κατάλογο .git (ή επιλύει ένα αρχείο .git για συνδεδεμένα worktrees) και αρχικοποιεί τη βάση δεδομένων αντικειμένων, τη βάση δεδομένων αναφορών και τις ρυθμίσεις.

Τα open(), init() και clone() δέχονται πίνακα επιλογών ως τελευταίο όρισμα:

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

Τα hooks εκτελούνται από προεπιλογή. Το Pitmaster::processFreeOptions() επιστρέφει ['processes' => false, 'hooks' => false]· οι τοπικές αναγνώσεις και εγγραφές συνεχίζουν να λειτουργούν σε αυτό το handle.

Έλεγχος αν μια διαδρομή είναι αποθετήριο

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

Αρχικοποίηση νέου αποθετηρίου

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

Αυτό δημιουργεί τη δομή καταλόγων .git με αντικείμενα, refs, HEAD (που δείχνει στο refs/heads/main) και μια προεπιλεγμένη ρύθμιση.

Για να δημιουργήσετε ένα αποθετήριο SHA-256, περάστε τη μορφή αντικειμένων ως δεύτερο όρισμα:

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

Τα αναγνωριστικά αντικειμένων σε αυτό το αποθετήριο έχουν 64 δεκαεξαδικούς χαρακτήρες και η ρύθμιση καταγράφει το extensions.objectformat = sha256. Τα αποθετήρια που ανοίγονται αργότερα αντλούν τη μορφή από αυτήν την εγγραφή ρύθμισης.

Ανάγνωση του commit HEAD

$head = $repo->head();

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

Η μέθοδος head() επιλύει το HEAD (ακολουθώντας συμβολικές refs) και επιστρέφει ένα αντικείμενο Commit.

Λίστα κλάδων και tags

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

Διάσχιση του ιστορικού commit

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

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

Μπορείτε επίσης να ξεκινήσετε από ένα συγκεκριμένο commit:

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

Έλεγχος κατάστασης του δέντρου εργασίας

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

Προσθήκη αρχείων στο ευρετήριο και δημιουργία commit

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

Το όνομα και το email του συντάκτη επιλύονται με την εξής σειρά: οι μεταβλητές περιβάλλοντος PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, οι μεταβλητές περιβάλλοντος GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL, οι σταθερές PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, το ίδιο το .git/config του αποθετηρίου (user.name και user.email) και, τέλος, το Pitmaster <pitmaster@localhost>. Διαβάζεται μόνο το αρχείο ρυθμίσεων του αποθετηρίου (και τα αρχεία που περιλαμβάνει), όχι το ~/.gitconfig. Ο συντάκτης commit επιλύεται με τον ίδιο τρόπο από τα ονόματα *_COMMITTER_* και, αν χρειαστεί, χρησιμοποιεί τις σταθερές του συντάκτη.

Υπολογισμός διαφορών

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

Κλωνοποίηση απομακρυσμένου αποθετηρίου

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

Αυτό εντοπίζει τα refs, ανακτά το αρχείο pack, ρυθμίζει τα branches παρακολούθησης απομακρυσμένων και κάνει checkout το προεπιλεγμένο branch. HTTP(S) Οι διευθύνσεις URL χρησιμοποιούν smart HTTP και επιστρέφουν σε dumb HTTP· οι διευθύνσεις URL SSH χρησιμοποιούν το transport SSH. Περάστε ένα βάθος ως τρίτο όρισμα για shallow clone: Pitmaster::clone($url, $path, 1).

Ανάγνωση οποιουδήποτε αντικειμένου βάσει hash

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

Διαμόρφωση

Το Pitmaster σέβεται το .git/config του αποθετηρίου για πληροφορίες συντάκτη και απομακρυσμένες διευθύνσεις URL. Μπορείτε επίσης να ορίσετε καθολικές προεπιλεγμένες τιμές με τις σταθερές PHP, που ορίζονται πριν εκτελεστεί το Pitmaster:

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

Οι τιμές byte δέχονται ακέραιο ή συμβολοσειρά με επίθημα k, m ή g ('256M'). Οι μη έγκυρες τιμές επανέρχονται στην προεπιλογή.

Οι μεταβλητές περιβάλλοντος υπερισχύουν των σταθερών ταυτότητας: PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, τα αντίστοιχα PITMASTER_COMMITTER_*, καθώς και οι μεταβλητές GIT_AUTHOR_* και GIT_COMMITTER_* του git. Το transport SSH διαβάζει τις μεταβλητές PITMASTER_SSH_*, όπως περιγράφεται στα Πρωτόκολλα.

Δεν υπάρχει σταθερά για τον αλγόριθμο hash. Η μορφή αντικειμένων επιλέγεται κατά τη δημιουργία του αποθετηρίου (Pitmaster::init($path, 'sha256') ή init --object-format=sha256 στο CLI) και στη συνέχεια διαβάζεται από τη διαμόρφωση του αποθετηρίου.