# Aloitus

## Asennus

Asenna Pitmaster komennolla Composer:

```bash
composer require pitmaster/pitmaster
```

## Vaatimukset

- **PHP 8.2+** sekä readonly-luokat, enum-tyypit ja konstruktorin parametrien ylennys
- **ext-zlib** objektien pakkaamiseen ja purkamiseen (sisältyy useimpiin asennuksiin)
- **ext-json** toimintatilatiedostoihin ja Git LFS API -hyötykuormiin
- **ext-mbstring**, ilmoitettu tiedostossa `composer.json`, joten Composer tarvitsee sen asennuksen yhteydessä
- **ext-ctype** tiivisteiden vahvistamiseen (käytössä useimmissa PHP-koosteissa, mutta sitä ei ole ilmoitettu tiedostossa `composer.json`)

Tietovaraston ydintoiminnot eivät tarvitse `git`-binääritiedostoa, FFI:tä eivätkä ulkoisia apuohjelmia. Valinnaisilla ominaisuuksilla on lisävaatimuksia 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.

## Avaa olemassa oleva tietovarasto

```php
use Pitmaster\Pitmaster;

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

Tämä avaa tietovaraston annetussa polussa. Pitmaster paikantaa `.git`-hakemiston (tai ratkaisee linkitettyjen työpuiden `.git`-tiedoston) ja alustaa objektitietokannan, viitetietokannan ja asetukset.

`open()`, `init()` ja `clone()` hyväksyvät valinnaisten argumenttien taulukon viimeisenä argumenttinaan:

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

Hookit suoritetaan oletusarvoisesti. `Pitmaster::processFreeOptions()` palauttaa arvon `['processes' => false, 'hooks' => false]`; paikallinen luku ja kirjoitus toimivat edelleen tällaisella kahvalla.

## Tarkista, onko polku tietovarasto

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

## Alusta uusi tietovarasto

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

Tämä luo `.git`-hakemistorakenteen, jossa ovat objektit, viitteet, HEAD (osoittaa kohteeseen `refs/heads/main`) ja oletusasetukset.

Luo SHA-256-tietovarasto antamalla objektimuoto toisena argumenttina:

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

Tietovaraston objektitunnukset ovat 64 heksadesimaalimerkkiä, ja asetuksiin kirjataan `extensions.objectformat = sha256`. Myöhemmin avatut tietovarastot saavat muodon tästä asetusmerkinnästä.

## Lue HEAD-commit

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

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

Metodi `head()` ratkaisee HEADin (seuraten symbolisia viitteitä) ja palauttaa `Commit`-objektin.

## Luettele haarat ja tagit

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

## Käy commit-historia läpi

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

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

Voit myös aloittaa tietystä commitista:

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

## Tarkista työpuun tila

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

## Lisää tiedostoja indeksiin ja tee 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";
```

Tekijän nimi ja sähköposti ratkaistaan tässä järjestyksessä: ympäristömuuttujat `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, ympäristömuuttujat `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL`, vakiot `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, tietovaraston oma `.git/config` (`user.name` ja `user.email`) ja lopuksi `Pitmaster <pitmaster@localhost>`. Luetaan vain tietovaraston asetustiedosto ja sen sisällyttämät tiedostot, ei tiedostoa `~/.gitconfig`. Commitin tekijä ratkaistaan samalla tavalla `*_COMMITTER_*`-nimistä ja oletuksena käytetään tekijän vakioita.

## Laske erot

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

## Kloonaa etätietovarasto

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

Tämä etsii viitteet, noutaa pakettitiedoston, määrittää etähakuhaarojen seurannan ja ottaa oletushaaran käyttöön. HTTP(S)-URL-osoitteet käyttävät älykästä HTTP-protokollaa ja vaihtavat tarvittaessa rajoitettuun HTTP-protokollaan; SSH-URL-osoitteet käyttävät SSH-siirtotapaa. Anna syvyys kolmantena argumenttina tehdäksesi matalan kloonin: `Pitmaster::clone($url, $path, 1)`.

## Lue objekti tiivisteen perusteella

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

## Määritykset

Pitmaster noudattaa tekijätiedoissa ja etä-URL-osoitteissa tietovaraston `.git/config`-asetuksia. Voit myös määrittää globaalit oletukset PHP-vakioilla ennen kuin Pitmaster suoritetaan:

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

| Vakio | Oletus | Vaikutus |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | ei mitään | Tekijän tiedot (katso yllä oleva järjestys) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | tekijän arvot | Commitin tekijän tiedot |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Älykkään HTTP-protokollan aikakatkaisu sekunteina (kokonaisluku) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | Paketteja luettaessa sallittu deltaketjun enimmäissyvyys (kokonaisluku) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | Muistissa objektivälimuistissa säilytettävien objektien määrä |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Objektivälimuistin tavumääräraja |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Pakettikohtaiseen välimuistiin tallennettujen ratkaistujen deltaobjektien määrä |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | Pakettikohtaisen välimuistin tavumääräraja |
| `PITMASTER_MAX_PACK_MEMORY` | ei mitään | Vanhempi nimi pakettikohtaisen välimuistin tavumäärärajalle; käytetään vain, jos `PITMASTER_PACK_RESOLVED_CACHE_BYTES` ei ole määritetty |

Tavuarvoksi käy kokonaisluku tai merkkijono, jonka lopussa on `k`, `m` tai `g` (`'256M'`). Virheellisten arvojen sijaan käytetään oletusarvoa.

Ympäristömuuttujat ohittavat identiteettivakiot: `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`, `PITMASTER_AUTHOR_DATE`, niitä vastaavat `PITMASTER_COMMITTER_*`-muuttujat sekä gitin omat muuttujat `GIT_AUTHOR_*` ja `GIT_COMMITTER_*`. SSH-siirto lukee muuttujat `PITMASTER_SSH_*`, jotka kuvataan kohdassa [Protokollat](https://pitmaster.inline0.dev/fi/docs/network/protocols).

Tiivistealgoritmille ei ole vakiota. Objektimuoto valitaan tietovarastoa luotaessa (`Pitmaster::init($path, 'sha256')` tai `init --object-format=sha256` palvelussa CLI), ja sen jälkeen se luetaan tietovaraston asetuksista.