# Alustamine

## Paigaldamine

Installige Pitmaster käsuga Composer:

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

## Nõuded

- **PHP 8.2+** koos kirjutuskaitstud klasside, enumite ja konstruktoris tehtava atribuutide määramisega
- **ext-zlib** objektide tihendamiseks ja lahtipakkimiseks (enamikus paigaldustes sisseehitatud)
- **ext-json** toiminguoleku failide ja Git LFS API koormiste jaoks
- **ext-mbstring**, deklareeritud failis `composer.json`, seega vajab Composer seda installimise ajal
- **ext-ctype** räsi valideerimiseks (enamikus PHP järgudes lubatud, kuid failis `composer.json` deklareerimata)

Põhihoidla toimingud ei vaja binaarfaili `git`, FFI-d ega väliseid abivahendeid. Valikulistel funktsioonidel on täiendavad käitusaja nõuded: hook’ide käivitamine kasutab `proc_open()`, transport SSH kasutab laadimise korral `ext-ssh2`-t ja muul juhul käivitab süsteemi binaarfaili `ssh` käsu `proc_open()` kaudu.

## Olemasoleva hoidla avamine

```php
use Pitmaster\Pitmaster;

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

See avab hoidla antud asukohas. Pitmaster leiab kataloogi `.git` (või lahendab seotud tööpuude korral faili `.git`) ning lähtestab objektide andmebaasi, viiteandmebaasi ja konfiguratsiooni.

`open()`, `init()` ja `clone()` aktsepteerivad viimase argumendina valikute massiivi:

```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’id käivitatakse vaikimisi. `Pitmaster::processFreeOptions()` tagastab `['processes' => false, 'hooks' => false]`; kohalik lugemine ja kirjutamine toimivad sellise käitleja korral edasi.

## Kontrollimine, kas asukoht on hoidla

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

## Uue hoidla lähtestamine

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

See loob kataloogistruktuuri `.git`, mis sisaldab objekte, viiteid, HEAD-i (osutab väärtusele `refs/heads/main`) ja vaikekonfiguratsiooni.

SHA-256 hoidla loomiseks andke teise argumendina objektivorming:

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

Selle hoidla objektitunnused koosnevad 64 kuueteistkümnendmärgist ja konfiguratsioonis on kirjas `extensions.objectformat = sha256`. Hiljem avatud hoidlad loevad vormingu konfiguratsioonikirjest.

## HEAD-commit’i lugemine

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

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

Meetod `head()` lahendab HEAD-i (järgides sümboolseid viiteid) ja tagastab objekti `Commit`.

## Harude ja siltide loetlemine

```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-ajaloo läbimine

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

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

Võite alustada ka kindlast commit’ist:

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

## Tööpuidu oleku kontrollimine

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

## Failide valikusse lisamine ja commit’i tegemine

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

Autori nimi ja e-posti aadress lahendatakse järgmises järjekorras: keskkonnamuutujad `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, keskkonnamuutujad `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL`, konstandid `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, hoidla enda `.git/config` (`user.name` ja `user.email`) ning viimaks `Pitmaster <pitmaster@localhost>`. Loetakse ainult hoidla konfiguratsioonifaili (ja faile, mida see kaasab), mitte `~/.gitconfig`. Commit’i tegija lahendatakse samamoodi nimede `*_COMMITTER_*` alusel ja vaikeväärtusena kasutatakse autori konstante.

## Erinevuste arvutamine

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

## Kaughoidla kloonimine

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

See tuvastab viited, hangib pakifaili, seadistab kaugjälgitavad harud ja lülitab välja vaikimisi haru. HTTP(S) URL-id kasutavad nutikat HTTP-i ja lähevad vajaduse korral üle lihtsustatud HTTP-ile; SSH URL-id kasutavad SSH-transporti. Madala sügavusega kloonimiseks edastage sügavus kolmanda argumendina: `Pitmaster::clone($url, $path, 1)`.

## Loe suvalist objekti räsi järgi

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

## Konfiguratsioon

Pitmaster järgib autoriandmete ja kaug-URL-ide puhul hoidla `.git/config`-i. Saate määrata ka globaalsed vaikeväärtused konstantidega PHP, mis tuleb määratleda enne Pitmaster käivitamist:

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

| Konstant | Vaikeväärtus | Mõju |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | puudub | Autori identiteet (vt ülaltoodud järjekorda) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | autori väärtused | Muutja identiteet |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Nutika HTTP-i ajalõpp sekundites (täisarv) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | Pakifailide lugemisel lubatud delta-ahela maksimaalne sügavus (täisarv) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | Mälus hoitavate objektide arv objektivahemälus |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Objektivahemälu baitide eelarve |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Lahendatud deltaobjektide arv, mida iga pakifaili kohta vahemällu salvestatakse |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | Pakivahemälu baitide eelarve |
| `PITMASTER_MAX_PACK_MEMORY` | puudub | Pakivahemälu baitide eelarve varasem nimi, mida kasutatakse ainult siis, kui `PITMASTER_PACK_RESOLVED_CACHE_BYTES` pole määratletud |

Baidiväärtus võib olla täisarv või string, mille lõpus on `k`, `m` või `g` (`'256M'`). Vigased väärtused asendatakse vaikeväärtusega.

Keskkonnamuutujad kirjutavad identiteedikonstandid üle: `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`, `PITMASTER_AUTHOR_DATE`, nende `PITMASTER_COMMITTER_*`-vasted ning giti enda muutujad `GIT_AUTHOR_*` ja `GIT_COMMITTER_*`. Transport SSH loeb muutujaid `PITMASTER_SSH_*`, mida kirjeldatakse jaotises [Protokollid](https://pitmaster.inline0.dev/et/docs/network/protocols).

Räsialgoritmi jaoks konstanti pole. Objektivorming valitakse hoidla loomisel (`Pitmaster::init($path, 'sha256')` või `init --object-format=sha256` väärtusega CLI) ja loetakse seejärel hoidla konfiguratsioonist.