# Johdanto
Pitmaster on puhdas PHP-kirjasto, joka lukee ja kirjoittaa Git-tietovarastoja natiivisti. Tietovaraston ydintoiminnoissa ei kutsuta `git`-binääritiedostoa komentotulkista eikä käytetä FFI:tä. Git-objektimalli, pakettitiedostomuoto, hakemistomuoto ja älykäs HTTP-siirtotapa on toteutettu kielellä PHP.

## Miksi Pitmaster on olemassa

PHP-sovellukset, jotka käsittelevät Git-tietovarastoja, kutsuvat yleensä `git`-binääritiedostoa komentotulkista. Tämä toimii, mutta luo tiukan riippuvuuden siitä, että `git` on asennettu, aiheuttaa turvallisuusriskejä, jotka liittyvät arvoihin `exec()` ja `proc_open()`, ja vaikeuttaa sovelluksen käyttöönottoa rajoitetuissa ympäristöissä (säiliöissä ilman gitiä, jaetussa ylläpitopalvelussa ja palvelimettomissa funktioissa).

Pitmaster poistaa `git`-riippuvuuden tietovaraston ydintoiminnoista. PHP-sovelluksesi voi lukea commit-historiaa, luoda commiteja, laskea eroja, tarkistaa tilan ja puskea etävarastoihin älykkään HTTP-protokollan kautta käyttämällä vain PHPn sisäänrakennettuja funktioita. Hookit ja SSH-siirto ovat poikkeuksia: molemmat käynnistävät prosesseja, ja kummankin voi poistaa käytöstä tietovaraston kahvakohtaisesti (katso [Hookit](https://pitmaster.inline0.dev/fi/docs/advanced/hooks)).

## Mitä se tekee

- Lukee ja kirjoittaa irrallisia objekteja (blob, tree, commit, tag)
- Lukee pakettitiedostoja ja ratkaisee deltaketjuja (OFS_DELTA ja REF_DELTA)
- Kirjoittaa pakettitiedostoja verkkotoimintoja varten
- Lukee ja kirjoittaa indeksiä/staging-aluetta (muodoissa v2, v3, v4)
- Lukee ja kirjoittaa viitteitä (haarat, tagit, HEAD, packed-refs, reftable)
- Laskee erot gitin yhtenäisessä muodossa käyttäen Myers-, Patience-, Histogram- ja Minimal-algoritmeja
- Suorittaa kolmitieyhdistämisiä ja tunnistaa ristiriidat
- Käy commit-graafeja läpi (loki, periytyminen, yhdistämiskanta)
- Käyttää Gitn älykästä HTTP-protokollaa (kloonaus, nouto, push)
- Tukee työpuita, aliprojekteja, stash-toimintoa, hookeja ja Git LFS:tä

## Vaatimukset

- PHP 8.2 tai uudempi
- `zlib`-laajennus (sisältyy lähes kaikkiin PHP-asennuksiin)
- `json`-laajennus
- `mbstring`-laajennus (ilmoitettu tiedostossa `composer.json`, joten Composer tarvitsee sen asennuksen yhteydessä)
- `ctype`-laajennus (käytetään objektitiivisteiden vahvistamiseen; käytössä useimmissa PHP-koosteissa, mutta sitä ei ole ilmoitettu tiedostossa `composer.json`)

Tietovaraston ydintoiminnot eivät tarvitse `git`-binääritiedostoa. Valinnaiset ominaisuudet voivat vaatia lisäominaisuuksia suoritusaikana: hookien suoritus käyttää `proc_open()`:tä, ja SSH-siirto käyttää `ext-ssh2`:a, jos se on ladattuna; muussa tapauksessa se käynnistää järjestelmän `ssh`-binääritiedoston `proc_open()`n kautta.

## Pikaesimerkki

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

Aloita kohdasta [Aloitus](https://pitmaster.inline0.dev/fi/docs/getting-started) ja tutustu sitten muihin toimintoihin kohdissa [API](https://pitmaster.inline0.dev/fi/docs/api), [CLI](https://pitmaster.inline0.dev/fi/docs/cli) ja [Toiminnot](https://pitmaster.inline0.dev/fi/docs/operations/read). Kohdassa [Testaus](https://pitmaster.inline0.dev/fi/docs/testing) kerrotaan, miten Pitmaster testataan suhteessa tuotteeseen `git`.