# Ξεκινώντας

## Εγκατάσταση

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

```bash
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()`.

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

```php
use Pitmaster\Pitmaster;

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

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

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

```php
// Do not run .git/hooks scripts for this handle
$repo = Pitmaster::open('/path/to/project', ['hooks' => false]);

// Do not start any process: no hooks, no fsmonitor hook, no clone/fetch/push, no SSH
$repo = Pitmaster::open('/path/to/project', Pitmaster::processFreeOptions());
```

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

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

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

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

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

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

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

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

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

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

```php
$head = $repo->head();

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

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

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

```php
// All branch names
$branches = $repo->branches();
// ['main', 'feature/login', 'bugfix/typo']

// Current branch name (null if detached)
$current = $repo->branch();
// 'main'

// All tag names
$tags = $repo->tags();
// ['v1.0.0', 'v1.1.0']
```

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

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

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

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

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

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

```php
use Pitmaster\Status\FileStatus;

$entries = $repo->status();

foreach ($entries as $entry) {
    if ($entry->index === FileStatus::Untracked) {
        echo "?? {$entry->path}\n";
    } elseif ($entry->index === FileStatus::Modified) {
        echo "M  {$entry->path}\n";
    } elseif ($entry->worktree === FileStatus::Modified) {
        echo " M {$entry->path}\n";
    }
}
```

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

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

// Create a commit
$commitId = $repo->commit('Add new feature with tests');

echo "Created commit: {$commitId->hex}\n";
```

Το όνομα και το 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_*` και, αν χρειαστεί, χρησιμοποιεί τις σταθερές του συντάκτη.

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

```php
// Unstaged changes (worktree vs index)
$diffs = $repo->diff();

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

// Staged changes (index vs HEAD)
$staged = $repo->diffStaged();
```

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

```php
$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

```php
$object = $repo->readObject($fullHash); // full 40-character (or 64 for SHA-256) hex hash

if ($object instanceof \Pitmaster\Object\Blob) {
    echo $object->content;
} elseif ($object instanceof \Pitmaster\Object\Commit) {
    echo $object->message;
}
```

## Διαμόρφωση

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

```php
define('PITMASTER_AUTHOR_NAME', 'Your Name');
define('PITMASTER_AUTHOR_EMAIL', 'you@example.com');
define('PITMASTER_HTTP_TIMEOUT', 60);        // Seconds
define('PITMASTER_MAX_DELTA_CHAIN', 50);     // Max delta chain depth
define('PITMASTER_OBJECT_CACHE_BYTES', '64M');
```

| Σταθερά | Προεπιλογή | Επίδραση |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | καμία | Ταυτότητα συντάκτη (βλ. παραπάνω σειρά) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | τιμές συντάκτη | Ταυτότητα committer |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Χρονικό όριο smart HTTP σε δευτερόλεπτα (ακέραιος) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | Μέγιστο βάθος αλυσίδας delta κατά την ανάγνωση pack (ακέραιος) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | Αντικείμενα που διατηρούνται στην προσωρινή μνήμη αντικειμένων στη μνήμη |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Όριο byte της προσωρινής μνήμης αντικειμένων |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Επιλυμένα αντικείμενα delta σε προσωρινή μνήμη ανά pack |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | Όριο byte αυτής της προσωρινής μνήμης pack |
| `PITMASTER_MAX_PACK_MEMORY` | καμία | Παλαιότερη ονομασία για το όριο byte της προσωρινής μνήμης pack, χρησιμοποιείται μόνο όταν δεν έχει οριστεί το `PITMASTER_PACK_RESOLVED_CACHE_BYTES` |

Οι τιμές 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_*`, όπως περιγράφεται στα [Πρωτόκολλα](https://pitmaster.inline0.dev/el/docs/network/protocols).

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