# Uvod
Pitmaster je čista knjižnica PHP, ki izvorno bere in zapisuje repozitorije Git. Osnovna opravila v repozitoriju ne zaganjajo binarne datoteke `git` in ne uporabljajo FFI. Objektni model Git, oblika datotek paketa, oblika indeksa in pametni prenos HTTP so implementirani v PHP.

## Zakaj obstaja Pitmaster

Aplikacije PHP, ki delujejo z repozitoriji Git, običajno zaženejo binarno datoteko `git`. To deluje, vendar ustvari močno odvisnost od nameščenega `git`, prinaša varnostna tveganja pri `exec()` in `proc_open()` ter otežuje uvajanje aplikacije v omejenih okoljih (v vsebnikih brez git, pri deljenem gostovanju in v funkcijah brez strežnika).

Pitmaster odpravi odvisnost od `git` pri osnovnem delu z repozitorijem. Vaša aplikacija PHP lahko bere zgodovino objav, ustvarja objave, izračunava razlike, preverja stanje in pošilja spremembe v oddaljene repozitorije prek pametnega protokola HTTP, pri čemer uporablja samo vgrajene funkcije PHP. Izjemi sta kavlji in prenos SSH: oba zaženeta procese in ju je mogoče izklopiti za posamezno povezavo z repozitorijem (glejte [Kavlji](https://pitmaster.inline0.dev/sl/docs/advanced/hooks)).

## Kaj omogoča

- Bere in zapisuje ohlapne objekte (blob, tree, commit, tag)
- Bere datoteke pack in razrešuje verige delta (OFS_DELTA in REF_DELTA)
- Zapisuje datoteke pack za omrežne operacije
- Bere in zapisuje indeks/območje za pripravo (formati v2, v3, v4)
- Bere in zapisuje sklice (veje, oznake, HEAD, packed-refs, reftable)
- Izračunava razlike (algoritmi Myers, Patience, Histogram in Minimal) v enotni obliki git
- Izvaja tristranske združitve z zaznavanjem sporov
- Spremlja grafe commitov (dnevnik, predniki, osnova združitve)
- Uporablja pametni protokol Git HTTP (clone, fetch, push)
- Podpira delovna drevesa, podmodule, stash, hooks in Git LFS

## Kaj zahteva

- PHP 8.2 ali novejši
- Razširitev `zlib` (vgrajena v skoraj vse namestitve PHP)
- Razširitev `json`
- Razširitev `mbstring` (navedena v `composer.json`, zato jo Composer zahteva ob namestitvi)
- Razširitev `ctype` (uporablja se za preverjanje zgoščenih vrednosti objektov; omogočena v večini gradenj PHP, vendar ni navedena v `composer.json`)

Osnovna opravila v repozitoriju ne zahtevajo binarne datoteke `git`. Izbirne funkcije lahko potrebujejo dodatne zmogljivosti izvajalnega okolja: izvajanje kavljev uporablja `proc_open()`, prenos SSH pa uporablja `ext-ssh2`, če je naložen, sicer pa zažene sistemsko binarno datoteko `ssh` prek `proc_open()`.

## Kratek primer

```php
use Pitmaster\Pitmaster;

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

// Read the current HEAD commit
$head = $repo->head();
echo $head->message;

// List branches
foreach ($repo->branches() as $branch) {
    echo $branch . "\n";
}

// Check status
foreach ($repo->status() as $entry) {
    echo "{$entry->path}: {$entry->index->value}{$entry->worktree->value}\n";
}

// Create a commit
$repo->add('src/Feature.php');
$commitId = $repo->commit('Add new feature');
```

Začnite z razdelkom [Uvod](https://pitmaster.inline0.dev/sl/docs/getting-started), nato pa za preostale funkcije uporabite razdelke [API](https://pitmaster.inline0.dev/sl/docs/api), [CLI](https://pitmaster.inline0.dev/sl/docs/cli) in [Opravila](https://pitmaster.inline0.dev/sl/docs/operations/read). Razdelek [Testiranje](https://pitmaster.inline0.dev/sl/docs/testing) pojasnjuje, kako se Pitmaster preverja glede na `git`.