# PHP API

## `Pitmaster\Pitmaster`

Klass `Pitmaster\Pitmaster` on staatiline sisenemispunkt. See pakub varamute avamise, loomise ja kloonimise tehasemeetodeid ning tuvastusabilisi.

```php
use Pitmaster\Pitmaster;
```

### `open`

```php
public static function open(string $path, array $options = []): Repository
```

Ava olemasolev varamu asukohas `$path`. Tee peaks olema tööpuu juur (sisaldama faili `.git/`). Toetatud on ka lingitud tööpuud (kus `.git` on fail, mis sisaldab väärtust `gitdir: <path>`) ja paljasvaramud (kus `$path` on kataloog `.git` ise).

`$options` võtab vastu kaks tõeväärtust, mõlemad on vaikimisi `true`:

- `hooks`: käivita `.git/hooks` skriptid. Anna sellele käepidemele nende vahelejätmiseks väärtus `false`.
- `processes`: luba kõik, mis käivitab protsessi või avab võrguühenduse. Anna väärtus `false`, et keelata konksud, fsmonitor-konks, kloonimine, toomine, saatmine ja SSH-protsessitransport. Kohalik lugemine ja kirjutamine toimib endiselt.

Kui tee ei ole git-varamu, visatakse `InvalidArgumentException`.

```php
$repo = Pitmaster::open('/home/user/project');
$repo = Pitmaster::open('/home/user/project', ['hooks' => false]);
$repo = Pitmaster::open('/home/user/project', Pitmaster::processFreeOptions());
```

### `init`

```php
public static function init(string $path, string $objectFormat = 'sha1', array $options = []): Repository
```

Initsialiseeri uus varamu asukohas `$path`. Loob kataloogistruktuuri `.git` koos failidega `objects/`, `refs/heads/`, `refs/tags/`, `hooks/`, `info/`, `HEAD` (mis osutab väärtusele `refs/heads/main`) ja vaikimisi `config`-iga.

`$objectFormat` on `'sha1'` või `'sha256'`. SHA-256 varamu saab oma seadistusse väärtused `repositoryformatversion = 1` ja `extensions.objectformat = sha256`. Mis tahes muu väärtuse korral visatakse `InvalidArgumentException`. `$options` kasutab samu võtmeid mis `open()`.

Kui määratud teel on varamu juba olemas, visatakse `RuntimeException`.

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

### `clone`

```php
public static function clone(string $url, string $path, ?int $depth = null, array $options = []): Repository
```

Klooni kaugvaramu. Initsialiseerib uue varamu, otsib kaugviited, toob pakifaili, seadistab kaugjälgimisharud ja loob tööpuu. SSH URL-id (`ssh://...` või `user@host:path`) kasutavad transporti SSH; muud URL-id kasutavad nutikat HTTP-protokolli ja lähevad selle vahetuse ebaõnnestumisel üle lihtsale HTTP-protokollile. Madala ajalooga kloonimiseks anna väärtus `$depth`.

Visatakse `RuntimeException`, kui `$options['processes']` on `false`. Kui kloonimine ebaõnnestub ja `$path` polnud varem olemas, eemaldatakse osaliselt loodud kataloog.

```php
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/repo');
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/shallow', 1);
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/repo', null, ['hooks' => false]);
```

### `processFreeOptions`

```php
public static function processFreeOptions(): array
```

Tagastab `['processes' => false, 'hooks' => false]` käituskeskkondade jaoks, mis ei tohi hostiprotsesse käivitada. Anna see edasi valikule `open()` või `init()`.

### `isRepository`

```php
public static function isRepository(string $path): bool
```

Kontrolli, kas tee on git-varamu. Tagastab väärtuse `true` tavaliste varamute (kataloog `.git/`), lingitud tööpuude (fail `.git`) ja paljasvaramute (fail `HEAD` olemas) puhul.

```php
if (Pitmaster::isRepository('/path/to/check')) {
    // It's a git repo
}
```

### `isWorktree`

```php
public static function isWorktree(string $path): bool
```

Kontrolli, kas tee on lingitud tööpuu (mitte põhivaramu). Tagastab väärtuse `true` ainult siis, kui `.git` on fail, mis sisaldab viidet `gitdir:`.

```php
if (Pitmaster::isWorktree('/path/to/worktree')) {
    // It's a linked worktree
}
```

### `commonGitDir`

```php
public static function commonGitDir(string $path): ?string
```

Lahenda ühise git-kataloogi tee mis tahes väljavõtte teest. Tavaliste varamute puhul on see kataloog `.git`. Lingitud tööpuude puhul on see jagatud git-kataloog, mis sisaldab objekte, seadistust ja packed-refs-i. Kui tee pole varamu, tagastatakse `null`.

```php
$common = Pitmaster::commonGitDir('/path/to/worktree');
// '/path/to/main-repo/.git'
```

---

## `Pitmaster\Repository`

Klass `Pitmaster\Repository` on kõigi git-toimingute peamine käepide. Hankige see valikuga `Pitmaster::open()`, `Pitmaster::init()` või `Pitmaster::clone()`.

```php
use Pitmaster\Repository;
```

### Juurdepääsuteed

#### `gitDir`

```php
public function gitDir(): string
```

Tagastab tööpuupõhise git-kataloogi. Tavaliste varamute puhul on see `.git/`. Lingitud tööpuude puhul on see `.git/worktrees/<name>/`.

#### `commonGitDir`

```php
public function commonGitDir(): string
```

Tagastab jagatud git-kataloogi. Tavaliste varamute puhul sama mis `gitDir()`. Lingitud tööpuude puhul on see põhivaramu kataloog `.git/`, kus asuvad objektid, seadistus ja packed-refs.

#### `workDir`

```php
public function workDir(): string
```

Tagastab tööpuu juurteena oleva tee.

#### `isLinkedWorktree`

```php
public function isLinkedWorktree(): bool
```

Tagastab väärtuse `true`, kui see varamu käepide on lingitud tööpuu.

#### `isBare`, `hooksEnabled`, `processesEnabled`

```php
public function isBare(): bool
public function hooksEnabled(): bool
public function processesEnabled(): bool
```

Näitab, kas varamul puudub tööpuu ja millised valikutest `hooks` / `processes` on selle käepideme jaoks lubatud. `hooksEnabled()` on alati `false`, kui protsessid on keelatud.

---

### Objektid

#### `readObject`

```php
public function readObject(string $hash): GitObject
```

Loe mis tahes objekti selle täieliku kuueteistkümnendräsi alusel (40 märki või SHA-256 varamus 64). Lühendatud räsisid ei aktsepteerita. Tagastab `Blob`, `Tree`, `Commit` või `Tag` eksemplari. Otsib esmalt lahtistest objektidest, seejärel pakifailidest.

Kui räsi ei leita, visatakse `ObjectNotFoundException`.

```php
$object = $repo->readObject('a1b2c3d4e5f6...');
```

#### `writeObject`

```php
public function writeObject(GitObject $object): ObjectId
```

Kirjuta objekt lahtiste objektide hoidlasse. Tagastab arvutatud väärtuse `ObjectId`.

```php
use Pitmaster\Object\Blob;

$blob = Blob::fromContent('Hello, world!');
$id = $repo->writeObject($blob);
```

#### `catFile`

```php
public function catFile(string $hash): string
```

Tagastab objekti töötlemata sisu, mis on samaväärne valikuga `git cat-file -p`.

```php
echo $repo->catFile('a1b2c3d4...');
```

#### `objectExists`

```php
public function objectExists(string $hash): bool
```

Kontrolli, kas objekt on varamus olemas (lahtine või pakitud).

#### `listObjects`

```php
public function listObjects(): array
```

Loetleb kõik varamu objekti-räsid. Tagastab kuueteistkümnendstringide massiivi.

---

### Viited

#### `head`

```php
public function head(): Commit
```

Tagastab praeguse HEAD-i sissekande. Järgib sümboolseid viiteid (HEAD -> refs/heads/main -> sissekande räsi).

Kui HEAD ei osuta kehtivale sissekandele (e.g., tühi varamu), visatakse `RuntimeException`.

#### `branch`

```php
public function branch(?string $name = null): ?string
```

Ilma argumentideta tagastab praeguse haru nime (e.g., `'main'`) või `null`, kui HEAD on lahutatud olekus.

Harunime korral lahendab selle sissekande räsiks (kuueteistkümnendstringiks) või tagastab `null`, kui haru pole olemas.

```php
$current = $repo->branch();        // 'main'
$hash = $repo->branch('feature');   // 'abc123...' or null
```

#### `branches`

```php
public function branches(): array
```

Tagastab kõigi harunimede sorditud massiivi (ilma prefiksita `refs/heads/`).

```php
$branches = $repo->branches();
// ['bugfix/typo', 'feature/login', 'main']
```

#### `tags`

```php
public function tags(): array
```

Tagastab kõigi sildinimede sorditud massiivi (ilma prefiksita `refs/tags/`).

#### `resolve`

```php
public function resolve(string $revision): ObjectId
```

Lahenda versiooniväljend väärtuseks `ObjectId`. Toetatud on:
- Täielikud kuueteistkümnendräsi väärtused (40 märki või SHA-256 puhul 64). Lühendatud räsisid, näiteks `abc1234`, ei lahendata.
- `HEAD`
- Harunimed (`main`, `feature/login`)
- Sildinimed (`v1.0.0`)
- Täielikud viiteteed (`refs/heads/main`)
- Versiooniväljendid (`HEAD~3`, `main^2`)

Kui versiooni ei saa lahendada, visatakse `RuntimeException`.

```php
$id = $repo->resolve('HEAD~3');
$id = $repo->resolve('v1.0.0');
$id = $repo->resolve('feature/login');
```

#### `allRefs`

```php
public function allRefs(): array
```

Tagastab kõik viited assotsiatiivse massiivina, kus viitenimed on seotud kuueteistkümnendräsidega.

```php
$refs = $repo->allRefs();
// ['refs/heads/main' => 'abc123...', 'refs/tags/v1.0.0' => 'def456...']
```

#### `updateRef`

```php
public function updateRef(string $name, ObjectId $target): void
```

Uuenda viidet nii, et see osutaks uuele sihtmärgile.

```php
$repo->updateRef('refs/heads/main', $commitId);
```

#### `createBranch`

```php
public function createBranch(string $name, ?ObjectId $from = null): void
```

Loo uus haru. Kui `$from` on null, luuakse haru praegusest HEAD-ist.

```php
$repo->createBranch('feature/new-thing');
$repo->createBranch('hotfix', $repo->resolve('v1.0.0'));
```

#### `deleteBranch`

```php
public function deleteBranch(string $name): void
```

Kustuta haru nime järgi. Kui haru on välja kontrollitud või seda pole olemas, visatakse `RuntimeException`. Erinevalt valikust `git branch -d` ei kontrollita, kas haru on liidetud.

```php
$repo->deleteBranch('feature/old');
```

#### `createLightweightTag`

```php
public function createLightweightTag(string $name, ?ObjectId $target = null): void
```

Loo kerge silt. Kui `$target` on null, märgistatakse otse praegune HEAD.

```php
$repo->createLightweightTag('v2.0.0');
$repo->createLightweightTag('hotfix-start', $repo->resolve('main~2'));
```

#### `createTag`

```php
public function createTag(string $name, string $message, ?ObjectId $target = null, ?string $tagger = null): ObjectId
```

Loo kommenteeritud silt. Kui `$target` on null, märgistatakse praegune HEAD. Tagastab sildi objekti väärtuse `ObjectId`.

```php
$tagId = $repo->createTag('v2.0.0', 'Release version 2.0.0');
```

#### `deleteTag`

```php
public function deleteTag(string $name): void
```

Kustuta silt nime järgi.

```php
$repo->deleteTag('v1.0.0');
```

#### `packRefs`

```php
public function packRefs(): void
```

Kirjuta ühine fail `packed-refs` uuesti praegusest lahtiste viidete hulgast ja kärbi vastavad ühised lahtised viited. Lingitud tööpuude puhul kirjutatakse see ühisesse git-kataloogi.

```php
$repo->packRefs();
```

#### `defaultBranch`

```php
public function defaultBranch(): string
```

Lahenda varamu vaikimisi haru. Kontrollib esmalt kaug-HEAD-i sümboolset viidet, seejärel kohalikku HEAD-i ja kasutab lõpuks väärtust `main` või `master`.

#### `isBranchMerged`

```php
public function isBranchMerged(string $branch, ?string $target = null): bool
```

Kontrolli, kas haru on teise haruga täielikult liidetud (vaikimisi vaikimisi haruga).

```php
if ($repo->isBranchMerged('feature/done')) {
    $repo->deleteBranch('feature/done');
}
```

#### `checkout`

```php
public function checkout(string $target): void
```

Vaheta haru või lahuta HEAD. Uuendab HEAD-i, indeksit ja tööpuud. `$target` võib olla haru nimi, silt, täielik räsi või versiooniväljend; kõik, mis pole haru, lahutab HEAD-i.

Visatakse `RuntimeException`, kui muudetud (indeksisse lisatud või lisamata) või jälgimata fail asub teel, mis erineb praeguse ja sihtpuu vahel.

Teistes jälgitavates failides olevad sissekandmata muudatused ei kandu üle: indeks ja tööpuu ehitatakse sihtpuust uuesti, mistõttu mõlemal pool identsete failide muudatused lähevad kaotsi, samas kui git säilitaks need ([#2](https://github.com/inline0/pitmaster/issues/2)). Tehke esmalt sissekanne või pange muudatused kõrvale. Valikud `merge()`, `cherryPick()`, `revert()`, `rebase()` ja poolituse määramise meetodid ehitavad tööpuu samal viisil uuesti.

```php
$repo->checkout('feature/login');
$repo->checkout($repo->resolve('v1.0.0')->hex);  // Detached HEAD
```

---

### Indeks

#### `index`

```php
public function index(): Index
```

Loe ja tagasta praegune indeks (ettevalmistusala) asukohast `.git/index`.

#### `add`

```php
public function add(string ...$paths): void
```

Lisa failid ettevalmistusalasse. Loeb iga faili tööpuust, loob bloobiobjekti ja uuendab indeksit. Iga argument peab olema tööpuu juure suhtes suhteline faili (või sümbollingi) tee; katalooge ja failimustreid ei laiendata ning puuduva faili korral visatakse `RuntimeException`.

```php
$repo->add('src/Feature.php', 'tests/FeatureTest.php');
```

#### `remove`

```php
public function remove(string ...$paths): void
public function removeCached(string ...$paths): void
```

Eemalda jälgitavad teed nii indeksist kui ka tööpuust. Toetab argumentide loendis `--cached` ning kombinatsiooni `-r` / `--recursive`, et käituda nagu Git.

```php
$repo->remove('old-file.txt');
$repo->remove('-r', 'src');
$repo->remove('--cached', 'old-file.txt');
$repo->removeCached('old-file.txt');
```

#### `mv`

```php
public function mv(string $source, string $destination): void
```

Teisalda või nimeta fail ümber nii tööpuus kui ka indeksis.

```php
$repo->mv('old-name.php', 'new-name.php');
```

---

### Sissekanded

#### `commit`

```php
public function commit(?string $message = null, ?string $author = null): ObjectId
```

Loo praegusest indeksist sissekanne. Ehitab indeksikirjetest puuhierarhia, loob sissekandeobjekti, mille vanem on HEAD (kui see on olemas), ja uuendab HEAD-i. Tagastab uue sissekande väärtuse `ObjectId`.

`$message` võib olla `null` ainult siis, kui liitmine, valiku teisaldamine, ennistamine või baasiharule ümberpaigutamine on konflikti tõttu peatunud; sel juhul kasutatakse ettevalmistatud sõnumit. Muul juhul visatakse tühja `null`-sõnumi korral `RuntimeException('Commit message required')`. Sissekande tegemisel visatakse viga ka siis, kui indeksis on lahendamata teid, indeks on sissekanneteta varamus tühi või puu pole HEAD-ist muutunud.

Parameeter `$author` on täielik git-autori string (`Name <email> timestamp timezone`). Kui see on null, lahendatakse see keskkonnamuutujate, konstantide ja `.git/config` põhjal alustamisjuhendis kirjeldatud järjekorras [Alustamine](https://pitmaster.inline0.dev/et/docs/getting-started).

```php
$id = $repo->commit('Fix null pointer bug');
```

#### `show`

```php
public function show(string $revision): array
```

Kuva sissekande sarnane objekt ja selle erinevus esimese vanemaga. Kui versioon lahendub kommenteeritud sildiks, sisaldab tagastusväärtus ka `['tag' => Tag]` ning `commit` on lahtipakitud sihtsissekanne.

```php
$result = $repo->show('HEAD');
echo $result['commit']->message;

foreach ($result['diff'] as $diff) {
    echo $diff->format();
}
```

#### `reset`

```php
public function reset(string $revision, string $mode = 'mixed'): void
```

Lähtesta HEAD sissekandele. Režiimid:
- `'soft'`: liiguta ainult HEAD-i
- `'mixed'`: liiguta HEAD-i ja lähtesta indeks (vaikimisi)
- `'hard'`: liiguta HEAD-i, lähtesta indeks ja tööpuu

```php
$repo->reset('HEAD~1', 'soft');
$repo->reset('main', 'hard');
```

#### `restore`

```php
public function restore(string $path, ?string $source = null, bool $staged = false, bool $worktree = false): void
```

Taasta tee indeksist või määratud lähteversioonist. Kui kumbagi lippu pole määratud, taastab Pitmaster tööpuu indeksist (või väärtusest `$source`, kui see on antud). `staged: true` taastab indeksi HEAD-ist (või väärtusest `$source`) ega muuda tööpuud; mõlema taastamiseks anna väärtus `staged: true, worktree: true`.

```php
$repo->restore('src/File.php');                                        // Worktree from index
$repo->restore('src/File.php', staged: true);                          // Index from HEAD
$repo->restore('src/File.php', 'HEAD~1');                              // Worktree from another commit
$repo->restore('src/File.php', 'HEAD~1', staged: true, worktree: true); // Index + worktree from another commit
```

#### `cherryPick`

```php
public function cherryPick(string $revision): ObjectId
public function cherryPickContinue(): ObjectId
public function cherryPickAbort(): void
```

Rakenda sissekanne praegusele harule uue sissekandena, säilitades algse autori. Kui konflikt peatab toimingu, lahenda konfliktid, lisa teed ettevalmistusalasse ja kutsu seejärel `cherryPickContinue()` või `cherryPickAbort()`.

```php
$newId = $repo->cherryPick('feature~2');

// After resolving conflicts:
$repo->add('src/File.php');
$repo->cherryPickContinue();
```

#### `revert`

```php
public function revert(string $revision): ObjectId
public function revertContinue(): ObjectId
public function revertAbort(): void
```

Loo sissekanne, mis tühistab teise sissekande. Kui konflikt peatab ennistamise, lahenda konfliktid, lisa teed ettevalmistusalasse ja kutsu seejärel `revertContinue()` või `revertAbort()`.

```php
$revertId = $repo->revert('HEAD~1');

// After resolving conflicts:
$repo->add('src/File.php');
$repo->revertContinue();
```

#### `rebase`

```php
public function rebase(string $onto): array
public function rebaseContinue(): array
public function rebaseAbort(): void
public function rebaseSkip(): array
```

Paiguta praegune haru teise versiooni peale ümber. Pitmaster toetab praegu lineaarset ümberpaigutamist, konfliktide korral Git-laadset peatumisolekut ning jätkamist, katkestamist ja vahelejätmist. HEAD peab osutama harule.

`rebase()`, `rebaseContinue()` ja `rebaseSkip()` tagastavad `['success' => bool, 'commits' => int, 'conflicts' => list<string>]`: kas ümberpaigutamine lõppes, mitu sissekannet rakendati ja millised teed põhjustasid peatumisel konflikti.

```php
$result = $repo->rebase('main');

if (!$result['success']) {
    // Resolve conflicts, then continue or skip/abort.
    $repo->add('src/File.php');
    $repo->rebaseContinue();
}
```

---

### Olek

#### `status`

```php
public function status(): array
```

Arvuta tööpuu olek. Tagastab massiivi `StatusEntry` objektidest, millest igaüks sisaldab:
- `path`: faili tee
- `index`: `FileStatus` loend HEAD-i ja indeksi muudatuste jaoks
- `worktree`: `FileStatus` loend indeksi ja tööpuu muudatuste jaoks
- `origPath`, `renameScore`: määratud ümbernimetatud kirjete korral, muidu `null`

Jälgimata failide mõlemas veerus on `FileStatus::Untracked`. Eiratud faile ei kuvata.

```php
foreach ($repo->status() as $entry) {
    echo $entry->shortFormat() . "\n"; // "M  src/File.php", "?? notes.txt"
}
```

#### `statusPorcelainV2`

```php
public function statusPorcelainV2(): string
```

Masinloetav olekuväljund giti portselani v2 vormingus.

```php
echo $repo->statusPorcelainV2();
// 1 M. N... 000000 000000 000000 0000...0000 0000...0000 modified-file.txt
// ? untracked-file.txt
```

---

### Erinevused

#### `diff`

```php
public function diff(?string $pathspec = null, string $algorithm = 'myers'): array
```

Võrdle tööpuud indeksiga (ettevalmistusalasse lisamata muudatused). Tagastab massiivi `DiffResult` objektidest. `$pathspec` piirab tulemuse täpselt ühe failiteega. `$algorithm` on `'myers'` (vaikimisi), `'patience'`, `'histogram'` või `'minimal'`; mis tahes muu väärtuse korral visatakse `InvalidArgumentException`.

```php
$diffs = $repo->diff();

foreach ($diffs as $diff) {
    echo $diff->format();  // Unified diff output
}
```

#### `diffStaged`

```php
public function diffStaged(?string $pathspec = null, string $algorithm = 'myers'): array
```

Võrdle indeksit HEAD-iga (ettevalmistusalasse lisatud muudatused). Tagastab `DiffResult[]` koos kustutatud ja lisatud failide nimede tuvastamisega.

Argumenti `$pathspec` praegu eiratakse, seega tagastatakse kõik ettevalmistusalasse lisatud failid. Enne esimest sissekannet tagastab meetod tühja massiivi ([#5](https://github.com/inline0/pitmaster/issues/5)).

```php
$staged = $repo->diffStaged();
```

#### `diffTree`

```php
public function diffTree(ObjectId $a, ObjectId $b, string $algorithm = 'myers'): array
```

Võrdle kaht puud nende väärtuse `ObjectId` järgi. Tagastab `DiffResult[]`. Anna puu ID-d, mitte sissekande ID-sid: sissekande ID-d ei loeta puuks ja tulemus on tühi.

```php
$old = $repo->readObject($repo->resolve('HEAD~1')->hex);
$new = $repo->head();
$diffs = $repo->diffTree($old->tree, $new->tree);
```

---

### Ajalugu

#### `log`

```php
public function log(int $limit = 50, ?ObjectId $from = null): array
```

Läbi sissekannete ajalugu, uusimast alustades sissekandja ajatempli järgi. Tagastab `Commit[]`. Kui `$from` on null, alustatakse HEAD-ist. Kui HEAD-il pole veel sissekannet, tagastatakse tühi massiiv.

```php
$commits = $repo->log(10);
```

#### `logAll`

```php
public function logAll(int $limit = 50): array
```

Läbi kõigi viidete ja HEAD-i kaudu kättesaadavad sissekanded, uusimast alustades. Tagastab `Commit[]`.

#### `logOneline`

```php
public function logOneline(int $limit = 50, bool $all = false, ?string $path = null): array
```

Tagasta logiread vormingus `git log --oneline` (`abc1234 Subject`), HEAD-ist, kõigist viidetest (`$all`) või teekohafiltriga.

#### `logPath`

```php
public function logPath(string $path, int $limit = 50): array
```

Failiteega filtreeritud logi. Tagastab ainult need sissekanded, mille erinevus esimesest vanemast lisab, muudab, kustutab või nimetab ümber täpselt selle faili. Kataloogiteed ei sobi.

Kontrollitakse ainult uusimaid `5 * $limit` sissekandeid, mistõttu vanemad faili puudutavad sissekanded võivad tulemusest puududa ([#7](https://github.com/inline0/pitmaster/issues/7)).

```php
$commits = $repo->logPath('src/Repository.php', 20);
```

---

### Liitmine

#### `merge`

```php
public function merge(string $branch, string $strategy = 'recursive'): MergeResult
public function mergeOctopus(array $branches): MergeResult
public function mergeContinue(): ObjectId
public function mergeAbort(): void
```

Liida haru (või mis tahes versioon) HEAD-i sisse. Tuvastab automaatselt edasiliitmise. Kui edasiliitmine pole võimalik, tuvastab puutasandil konfliktid ja loob konfliktide puudumisel liitmississekande. Konflikti korral kirjutatakse liitmise olek Git-vormingus indeksisse ja tööpuusse; lahenda teed, lisa need ettevalmistusalasse ja kutsu seejärel `mergeContinue()` või `mergeAbort()`.

`$strategy` `'ours'` salvestab liitmississekande, mis säilitab HEAD-i puu; mis tahes muu väärtus kasutab vaikimisi rekursiivset liitmist. `mergeOctopus()` liidab kaks või enam haru üheks sissekandeks. Kui mõni haru põhjustab konflikti, tagastatakse konfliktidega tulemus ilma liitmisolekut kirjutamata või sissekannet loomata.

Kui liita haru, mis juba sisaldub HEAD-is, luuakse teise liitmise kinnistus, selle asemel et teatada „Already up to date” ([#6](https://github.com/inline0/pitmaster/issues/6)). Jälgitavates failides olevad kinnitamata muudatused kirjutatakse üle, nagu kirjeldatud jaotises `checkout()`.

Tagastab `MergeResult`, millel on:
- `clean`: kas liitmine õnnestus konfliktideta
- `commitId`: liitmise kinnistuse ID (puhta tulemuse korral)
- `conflictPaths`: konfliktsete failide radade massiiv (konflikti korral)
- `mergedContents`: konfliktsete radade vastendus failisisule koos konfliktimarkeritega (konflikti korral)

```php
$result = $repo->merge('feature/login');

if ($result->clean) {
    echo "Merged: {$result->commitId->hex}\n";
} else {
    echo "Conflicts in: " . implode(', ', $result->conflictPaths) . "\n";
    $repo->add('src/File.php');
    $repo->mergeContinue();
}
```

#### `mergeBase`

```php
public function mergeBase(ObjectId $a, ObjectId $b): ?ObjectId
```

Leiavad kahe kinnistuse liitmise aluse (madalaima ühise eellase). Tagastab nulli, kui ühist eellast pole.

```php
$base = $repo->mergeBase(
    $repo->resolve('main'),
    $repo->resolve('feature/login'),
);
```

### Bisektsioon

```php
public function bisectStart(string $bad, string $good): ObjectId
public function bisectGood(?string $revision = null): ?ObjectId
public function bisectBad(?string $revision = null): ?ObjectId
public function bisectReset(): void
```

Otsib binaarselt üles kinnistuse, mis muutuse sisse tõi. `bisectStart()` salvestab vigased ja head versioonid, lülitub esimesele kandidaadile ja tagastab selle. `bisectGood()` ja `bisectBad()` märgivad praeguse HEAD-i (või `$revision`) ning lülituvad järgmisele kandidaadile ja tagastavad selle. Kui alles jääb üks kahtlusalune, tagastatakse see kinnistus ja see jääb kandidaadiks: tegu on esimese vigase kinnistusega. `bisectReset()` lõpetab seansi ja naaseb haru või kinnistuse juurde, kus see algas.

```php
$candidate = $repo->bisectStart('HEAD', 'v1.0.0');
// test $candidate ...
$candidate = $repo->bisectBad();
$candidate = $repo->bisectGood();
$repo->bisectReset();
```

---

### Võrk

#### `fetch`

```php
public function fetch(string $remote = 'origin', ?int $depth = null): void
```

Toob andmed kaug hoidlast. Laadib alla uued objektid ja uuendab kaugjälitusviiteid. Anna `$depth`, et süvendada või piirata madalat ajalugu.

`fetch()` ja meetodid `push*()` tekitavad `RuntimeException`, kui käepide on avatud valikuga `['processes' => false]`.

```php
$repo->fetch();
$repo->fetch('upstream');
```

#### `push`

```php
public function push(string $remote = 'origin', ?string $branch = null): void
public function pushForceWithLease(string $remote = 'origin', ?string $branch = null, ?ObjectId $expected = null): void
public function pushAtomic(string $remote = 'origin', array $branches = []): void
public function pushMirror(string $remote = 'origin'): void
```

Lükka praegune haru (või määratud haru) kaughoidlasse. Saadaval on lease'iga sundimise, aatomilised ja peegelvariandid rangemate või laiemate viiteuuenduste jaoks.

```php
$repo->push();
$repo->push('origin', 'feature/login');
$repo->pushForceWithLease('origin', 'main', $repo->resolve('refs/remotes/origin/main'));
$repo->pushAtomic('origin', ['main', 'release']);
$repo->pushMirror();
```

---

### Tööpuid

#### `addWorktree`

```php
public function addWorktree(string $path, string $branch, ?ObjectId $from = null, ?string $name = null): Worktree
```

Lisa lingitud tööpuu. Loob haru, kui seda pole olemas, seadistab tööpuu metaandmed ja loob tööpuu failid. Anna `$name`, kui vajad deterministlikku metaandmete lühinime, mis erineb väljavõtte kataloogi põhinimest.

```php
$wt = $repo->addWorktree('/tmp/review', 'feature/review');
$wt = $repo->addWorktree('/tmp/checkouts/review', 'feature/review', name: 'review-wt');
```

#### `removeWorktree`

```php
public function removeWorktree(string $pathOrName, bool $force = false): void
```

Eemalda lingitud tööpuu. Kasuta `$force = true`, et eemaldada see ka lukustatuna.

#### `worktrees`

```php
public function worktrees(): array
```

Loetle kõik tööpuud (peamine ja lingitud). Tagastab `Worktree[]`.

```php
foreach ($repo->worktrees() as $wt) {
    echo "{$wt->path} [{$wt->branch}]\n";
}
```

---

### Seadistus

#### `config`

```php
public function config(): GitConfig
```

Pääse ligi hoidla git-seadistusele. Loe ja kirjuta seadistusväärtusi.

```php
$config = $repo->config();
$name = $config->get('user.name');
$config->set('user.email', 'new@example.com');
```

---

### Sisemine ligipääs

Need meetodid võimaldavad edasijõudnud kasutusjuhtudel ligipääsu sisekomponentidele.

#### `objectDatabase`

```php
public function objectDatabase(): ObjectDatabase
```

Pääse ligi töötlemata objektide andmebaasile (lahtised ja pakitud hoidlad).

#### `refDatabase`

```php
public function refDatabase(): RefDatabase
```

Pääse ligi töötlemata viidete andmebaasile (lahtised ja pakitud viited).

---

## Madalama taseme klassid

Neid klasse ei mähita `Repository` ümber ning need luuakse selle sisekomponentide põhjal.

### `Pitmaster\Graph\Blame`

```php
public function blame(ObjectId $headId, string $path): array
```

Tagastab ühe kirje `$path` iga rea kohta asukohas `$headId`: `['line' => int, 'hash' => string, 'author' => string, 'content' => string]`. `author` on täielik identiteedistring (`Name <email> timestamp timezone`).

```php
use Pitmaster\Graph\Blame;

$blame = new Blame($repo->objectDatabase());

foreach ($blame->blame($repo->resolve('HEAD'), 'src/File.php') as $line) {
    echo substr($line['hash'], 0, 8) . " {$line['content']}\n";
}
```

### `Pitmaster\Graph\Grep`

```php
public function grep(ObjectId $treeId, string $pattern, string $prefix = '', array $options = []): array
```

Otsib puu bloobidest. Tagastab iga vaste rea kohta `['path' => string, 'line' => int, 'content' => string]`. Valikud: `regex` (käsitle mustrit PCRE-mustrina) ja `ignore_case`. Vigane regulaaravaldis tekitab `InvalidArgumentException`.

```php
use Pitmaster\Graph\Grep;

$grep = new Grep($repo->objectDatabase());
$matches = $grep->grep($repo->head()->tree, 'TODO', '', ['ignore_case' => true]);
```

### `Pitmaster\Ref\Notes`

```php
public function get(ObjectId $commitId, string $notesRef = 'refs/notes/commits'): ?string
public function set(ObjectId $commitId, string $noteContent, string $notesRef = 'refs/notes/commits'): void
public function remove(ObjectId $commitId, string $notesRef = 'refs/notes/commits'): void
public function listAll(string $notesRef = 'refs/notes/commits'): array
public function merge(string $sourceRef, string $targetRef = 'refs/notes/commits'): void
```

Loeb ja kirjutab märkmeid git, mis on salvestatud märkmeviite alla. `listAll()` tagastab sissekande räsi ja märkme sisu paari.

```php
use Pitmaster\Ref\Notes;

$notes = new Notes($repo->objectDatabase(), $repo->refDatabase());
$notes->set($repo->resolve('HEAD'), "Reviewed\n");
echo $notes->get($repo->resolve('HEAD'));
```