# Darbo pradžia

## Diegimas

Įdiekite Pitmaster naudodami Composer:

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

## Reikalavimai

- **PHP 8.2+** su tik skaitomomis klasėmis, enum ir konstruktoriaus parametrų perkėlimu
- **ext-zlib** objektams suspausti ir išskleisti (daugumoje įdiegimų jau yra)
- **ext-json** operacijų būsenos failams ir Git LFS API duomenims
- **ext-mbstring**, nurodytas `composer.json`, todėl Composer jo reikalauja diegimo metu
- **ext-ctype** maišoms tikrinti (įjungtas daugumoje PHP versijų, bet nenurodytas `composer.json`)

Pagrindinėms saugyklos operacijoms nereikia `git` dvejetainio failo, FFI ar išorinių pagalbinių įrankių. Pasirinktinėms funkcijoms reikia papildomų vykdymo aplinkos galimybių: hook vykdymui naudojamas `proc_open()`, o SSH transportas naudoja `ext-ssh2`, jei jis įkeltas, o kitu atveju per `proc_open()` paleidžiamas sistemos `ssh` dvejetainis failas.

## Atidaryti esamą saugyklą

```php
use Pitmaster\Pitmaster;

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

Taip atidaroma saugykla nurodytame kelyje. Pitmaster suranda `.git` katalogą (arba išsprendžia `.git` failą susietiems darbiniams medžiams) ir inicijuoja objektų duomenų bazę, nuorodų duomenų bazę bei konfigūraciją.

`open()`, `init()` ir `clone()` priima parinkčių masyvą kaip paskutinį argumentą:

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

Hook vykdomi pagal numatytuosius nustatymus. `Pitmaster::processFreeOptions()` grąžina `['processes' => false, 'hooks' => false]`; vietinis skaitymas ir rašymas su tokia nuoroda veikia toliau.

## Patikrinti, ar kelias yra saugykla

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

## Inicijuoti naują saugyklą

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

Taip sukuriama `.git` katalogų struktūra su objektais, nuorodomis, HEAD (nurodančiu į `refs/heads/main`) ir numatytąja konfigūracija.

Norėdami sukurti SHA-256 saugyklą, kaip antrą argumentą perduokite objektų formatą:

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

Šios saugyklos objektų ID sudaro 64 šešioliktainiai simboliai, o konfigūracijoje įrašyta `extensions.objectformat = sha256`. Vėliau atidarytos saugyklos formatą nustato pagal šį konfigūracijos įrašą.

## Nuskaityti HEAD įrašą

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

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

Metodas `head()` išsprendžia HEAD (sekdamas simbolines nuorodas) ir grąžina objektą `Commit`.

## Išvardyti šakas ir žymas

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

## Pereiti įrašų istoriją

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

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

Taip pat galite pradėti nuo konkretaus įrašo:

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

## Patikrinti darbinio medžio būseną

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

## Įtraukti failus į indeksą ir sukurti įrašą

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

Autoriaus vardas ir el. paštas nustatomi tokia tvarka: `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL` aplinkos kintamieji, `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL` aplinkos kintamieji, konstantos `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, pačios saugyklos `.git/config` (`user.name` ir `user.email`) ir galiausiai `Pitmaster <pitmaster@localhost>`. Skaitomas tik saugyklos konfigūracijos failas (ir jo įtraukiami failai), o `~/.gitconfig` neskaitomas. Įrašytojas nustatomas taip pat, naudojant `*_COMMITTER_*` pavadinimus; jei jų nėra, naudojamos autoriaus konstantos.

## Apskaičiuoti skirtumus

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

## Klonuoti nuotolinę saugyklą

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

Aptinkamos nuorodos, gaunamas paketo failas, nustatomos nuotolinio sekimo šakos ir išimama numatytoji šaka. HTTP(S) URL naudoja išmanųjį HTTP ir, jam nepavykus, pereina prie paprastojo HTTP; SSH URL naudoja SSH transportą. Norėdami atlikti negilų klonavimą, kaip trečią argumentą perduokite gylį: `Pitmaster::clone($url, $path, 1)`.

## Nuskaityti bet kurį objektą pagal maišą

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

## Konfigūracija

Pitmaster atsižvelgia į saugyklos `.git/config`, kurioje saugoma autoriaus informacija ir nuotoliniai URL. Taip pat galite nustatyti visuotines numatytąsias reikšmes naudodami PHP konstantas, apibrėžtas prieš paleidžiant 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');
```

| Konstanta | Numatytoji reikšmė | Poveikis |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | nėra | Autoriaus tapatybė (žr. pirmiau pateiktą tvarką) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | autoriaus reikšmės | Įrašytojo tapatybė |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Išmaniojo HTTP skirtojo laiko limitas sekundėmis (sveikasis skaičius) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | Didžiausias deltų grandinės gylis skaitant paketus (sveikasis skaičius) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | Objektų, laikomų atmintyje esančioje objektų podėlyje, skaičius |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Objektų podėlio dydžio baitais riba |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Kiekviename pakete podėlyje laikomų išspręstų deltų objektų skaičius |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | To paketų podėlio dydžio baitais riba |
| `PITMASTER_MAX_PACK_MEMORY` | nėra | Ankstesnis paketų podėlio dydžio baitais ribos pavadinimas, naudojamas tik tada, kai `PITMASTER_PACK_RESOLVED_CACHE_BYTES` neapibrėžta |

Baitų reikšmė gali būti sveikasis skaičius arba eilutė su priesaga `k`, `m` arba `g` (`'256M'`). Netinkamos reikšmės pakeičiamos numatytąja.

Aplinkos kintamieji turi pirmenybę prieš tapatybės konstantas: `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`, `PITMASTER_AUTHOR_DATE`, atitinkamos `PITMASTER_COMMITTER_*` reikšmės ir paties git kintamieji `GIT_AUTHOR_*` bei `GIT_COMMITTER_*`. SSH transportas nuskaito `PITMASTER_SSH_*` kintamuosius, aprašytus skiltyje [Protokolai](https://pitmaster.inline0.dev/lt/docs/network/protocols).

Maišos algoritmui nėra konstantos. Objektų formatas pasirenkamas kuriant saugyklą (`Pitmaster::init($path, 'sha256')` arba `init --object-format=sha256` sistemoje CLI), o vėliau nuskaitomas iš saugyklos konfigūracijos.